mirrors/dotnet-installer
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages 1 Wiki Activity Actions

Add manual pages for current commands

Browse source 
Convert the existing README.md from command directories into man pages. This
was done using pandoc. Some commands still don't have READMEs so they are not
present here.

Fix #3
This commit is contained in:
Zlatko Knezevic 2015-12-29 11:06:10 -08:00
parent 8bccd0b93b
commit 2f51091785
13 changed files with 432 additions and 29 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

34
Documentation/manpages/dotnet-cli.1 Normal file
View file

@ -0,0 +1,34 @@
.\" Automatically generated by Pandoc 1.15.1
.\"
.hy
.TH "dotnet-cli" "1" "" "" ""
.SH dotnet
.SH NAME
.PP
dotnet \-\- general driver for running the command\-line commands
.SH SYNOPSIS
.PP
dotnet [common\-options] [command] arguments (#arguments)
.SH DESCRIPTION
.PP
dotnet is a generic driver for the CLI toolchain.
Invoked on its own, it will give out brief usage instructions.
.PP
Each specific feature is implemented as a command.
In order to use the feautre, it is specified after dotnet, i.e.
dotnet compile.
All of the arguments following the command are command\[aq]s own
arguments.
.SH Arguments
.PP
\-v, \-\-verbose Enable verbose output
.PP
\-\-version Print out the version of the CLI tooling
.SH Commands
.PP
There are many possible commands that you can use.
The few main ones are: * run \- run your code from source * compile \-
compile your source code * publish \- publish
.SH SEE ALSO
.PP
dotnet\-compile dotnet\-run dotnet\-publish

128
Documentation/manpages/dotnet-compile.1 Normal file
View file

@ -0,0 +1,128 @@
.\" Automatically generated by Pandoc 1.15.1
.\"
.hy
.TH "dotnet-compiler" "1" "" "" ""
.SH dotnet\-compile
.SH NAME
.PP
dotnet\-compile \-\- Compiles source files for a single project to a
binary format and saves to a target file.
.SH SYNOPSIS
.PP
dotnet compile options (#options)
.SH DESCRIPTION
.PP
The compile command compiles source files from a single project to a
binary file, either IL byte code or native machine code, depending on
the options provided.
The default option is compilation to IL byte code, but may change in the
future.
.PP
Users who want to benefit from incremental builds and who want to
compile both the project and its dependencies should use the Build
command.
.PP
The default IL [\-\-il] output is a PE32 exe [exe], with the default
extension of ".exe" on all OSes.
The exe must include a public static void or public static int main
entry point, or it is an error.
The dll [dll] output option has the default extension of ".dll".
.PP
The IL exe output type needs a runtime host to execute.
The IL exe output type also copies a host to the output directory.
The host is renamed to the name of the exe.
For example, if the file is intended to be "foo" (\f[C]\-o\ foo\f[]),
then the host will be called foo, with the appropriate default native
file extension fo the OS (see the native file extensions, below).
The PE32 exe will be called "[filename]"\-app.exe".
In this case, it would be called "foo\-app.exe".
The executables also require a special configuration section in
project.json:
.IP
.nf
\f[C]
{\
\ \ \ \ "compilerOptions":\ {
\ \ \ \ \ \ "emitEntryPoints":\ true
\ \ \ \ }
}
\f[]
.fi
.PP
The default native [\-\-native] output is a native exe that conforms to
the architecture of the underlying operating system (i.e.
running on 64\-bit OS will produce a native 64\-bit exe).
This can be overriden via the \-\-arch switch and specifying the wanted
architecture.
The executable has a default extension of "" on Linux and OS X and
".exe" on Windows.
The source must include a static void main entry point, or it is an
error, unless otherwise specified in the project.json.
The dynamic library [dylib] output option has the default extension of
".so" on Linux/UNIX, ".dynlib" on OS X and ".dll" on Windows.
The static library [staticlib] option has the default extension of ".a"
on Linux, UNIX and OS X and ".lib" on Windows.
.PP
This command relies on the following artifacts: source files,
project.json project file, project.lock.json temporary file and restored
NuGet dependencies.
.PP
The project.json file represents and describes the project.
It can contain several setting, which are described in the
Build (https://docs.asp.net/en/latest/dnx/projects.html#building).
The most important information in the project.json file are the root
(not transitive) NuGet dependencies and the files to be compiled.
By default, this is a wildcard \-\- "*.cs".
It supports both inclusion and exclusion semantics.
.PP
The project.lock.json file is expanded form of the project.json file.
It includes the transitive closure of the project, per framework.
It is produced by a NuGet client, typically by using the
\f[C]dotnet\ restore\f[] command.
The project.lock.json file can be used by tools to safely determine the
closure of dependencies, without having to manually calculate them.
This file is only intended for tools, is temporary and should not be
checked into source control.
It should be present in .gitignore files.
.PP
It is important to know that a project.lock.json is invalid given that a
project.json has been changed.
The project.lock.json has enough information to determine this state
given a project.json.
The compile command validates this state and will error if the
project.lock.json is invalid.
.PP
The compile command relies on NuGet dependencies for compilation, as
references.
These are expected to be found in the user\-local NuGet cache (typically
location here).
It is an error state if a given NuGet package is not found.
.PP
Output files, are written to the child \f[C]bin\f[] folder, which will
be created if it doesn\[aq]t exist.
Files will be overwritten as needed.
The temporary files that are created during compilation are placed in
the child \f[C]obj\f[] folder.
.SH Options
.PP
\-n, \-\-native [exe | dynlib | lib] Compiles source to native machine
code, for the local machine.
The default is a native executable.
The default exe extension is no extension and ".exe" on Windows.
The default dynlib extension is ".a", ".dynlib" on OS X and ".dll" on
Windows.
.PP
\-\-il [exe | dll] Compiles source to IL byte code, which is (typically)
portable across machine types.
The default output is a PE32 exe, with the default extension of ".exe"
on all OSes.
The exe must include a static main entry point, or it is an error.
The DLL output option has the default extension of ".dll".
.PP
\-o, \-\-output filename Specifies the filename to be used.
It is an error not to specify an output filename.
If no extension is provided, the default one is provided for the output
type.
.PP
\-v, \-\-verbose Prints verbose logging information, to follow the flow
of execution of the command.

57
Documentation/manpages/dotnet-native.1 Normal file
View file

@ -0,0 +1,57 @@
.\" Automatically generated by Pandoc 1.15.1
.\"
.hy
.TH "dotnet-native" "1" "" "" ""
.SH dotnet\-compile
.SH NAME
.PP
dotnet\-compile\-native \-\- Compiles IL binaries to native binaries.
.SH SYNOPSIS
.PP
dotnet compile options (#options)
.SH DESCRIPTION
.PP
The \f[C]compile\-native\f[] command compiles IL assemblies to native
machine code.
It is used by \f[C]dotnet\-compile\ \-\-native\f[].
.PP
The output is a native exe that conforms to the architecture of the
underlying operating system (i.e.
running on 64\-bit OS will produce a native 64\-bit exe).
This can be overriden via the \-\-arch switch and specifying the wanted
architecture.
The executable has a default extension of "" on Linux and OS X and
".exe" on Windows.
The source must include a `static void Main(string[] args) entry point
and specify compilerOptions.emitEntryPoint in the project.json.
.PP
Output files are written to the child \f[C]bin\f[] folder, which will be
created if it doesn\[aq]t exist.
Files will be overwritten as needed.
.SH Options
.PP
\-\-appdepsdk Path to custom AppDepSDK
.PP
\-c, \-\-configuration [debug|release] Build configuration.
Defaults to \f[C]debug\f[].
.PP
\-\-ilcargs Custom arguments for the IL Compiler.
.PP
\-\-ilcpath Path to a custom ilc.exe
.PP
\-\-linklib Path to static lib to link
.PP
\-\-logpath Enables logging and writes native compilation logs to the
given path.
.PP
\-m, \-\-mode [cpp|ryujit|custom] Code generation mode.
Defaults to ryujit.
.PP
\-o, \-\-out directoryname Output directory for the native executable.
.PP
\-r, \-\-reference Path to a managed dll reference for the app.
.PP
\-t, \-\-temp\-out Specifies temporary directory for intermediate files.
.PP
\-v, \-\-verbose Prints verbose logging information, to follow the flow
of execution of the command.

31
Documentation/manpages/dotnet-new.1 Normal file
View file

@ -0,0 +1,31 @@
.\" Automatically generated by Pandoc 1.15.1
.\"
.hy
.TH "dotnet-new" "1" "" "" ""
.SH dotnet\-new
.SH NAME
.PP
dotnet\-new \-\- Create a new sample project
.SH SYNOPSIS
.PP
dotnet new
.SH DESCRIPTION
.PP
The new command provides a convenient way to initalize a valid .NET Core
project and sample source code to try out the CLI toolset.
.PP
This command is invoked in the context of a directory.
When invoked, the command will result in two main artifacts being
dropped to the directory:
.IP "1." 3
A sample "Hello World" program that exists in \f[C]Program.cs\f[] file.
.IP "2." 3
A valid \f[C]project.json\f[] file
.PP
After this, the project is ready to be compiled and/or edited further.
.SH EXAMPLES
.PP
\f[C]dotnet\ new\f[] Drops a sample in the current directory.
.SH SEE ALSO
.PP
dotnet\-run(1)

89
Documentation/manpages/dotnet-publish.1 Normal file
View file

@ -0,0 +1,89 @@
.\" Automatically generated by Pandoc 1.15.1
.\"
.hy
.TH "dotnet-publish" "1" "" "" ""
.SH dotnet\-publish
.SH NAME
.PP
\f[C]dotnet\-publish\f[] > packs the application and all of its
dependencies into a folder getting it ready for publishing
.SH SYNOPSIS
.PP
\f[C]dotnet\-publish\ [options]\ [project]\f[]
.SH DESCRIPTION
.PP
\f[C]dotnet\-publish\f[] will compile the application, read through its
dependencies specified in \f[I]project.json\f[] and publish the
resulting set of files to a directory.
This directory contains the assemblies, the runtime as well as the
runnable version of the application.
This directory can then be moved to a different machine and the
application will be able to be ran regardless of existence of any other
runtime.
.PP
\f[C]dotnet\-publish\f[] needs access to \f[I]project.json\f[] to work.
If it is not specified on invocation via [project],
\f[I]project.json\f[] in the current directory will be the default.
If no \f[I]project.json\f[] can be found, \f[C]dotnet\-publish\f[] will
error out.
.PP
The command also requires information on the targeted framework and
runtime, both of which can be specified on the command line.
If the runtime is not specified, the command will default to the runtime
for the current operating system.
If the framework is not specified, the command will read the information
from the \f[I]project.json\f[] file.
In case of no valid framework found, the command will error out.
In case of multiple valid frameworks found, the command will publish for
all valid frameworks.
.SH Options
.PP
\f[C]\-f\f[], \f[C]\-\-framework\f[] [FID]
.PP
Publish the application for a given framework identifier (FID).
If not specified, FID is read from \f[I]project.json\f[].
.PP
\f[C]\-r\f[], \f[C]\-\-runtime\f[] [RID]
.PP
Publish the application for a given runtime.
Supported values for runtimes at this time are:
.IP
.nf
\f[C]
*\ ubuntu.14.04\-x64
*\ win7\-x64
*\ osx.10.10\-x64
\f[]
.fi
.PP
\f[C]\-o\f[], \f[C]\-\-output\f[]
.PP
Specify the path where to place the directory.
If not specified, will default to
\f[I]\&./bin/[configuration]/[framework]/[runtime]/\f[]
.PP
\f[C]\-c\f[], \f[C]\-\-configuration\ [Debug|Release]\f[]
.PP
Configuration to use when publishing.
If not specified, will default to "Debug".
.SH EXAMPLES
.PP
\f[C]dotnet\-publish\f[] >Publish the current application using the
\f[I]project.json\f[] framework and runtime for the current operating
system.
.PP
\f[C]dotnet\-publish\ ~/projects/app1/project.json\f[] >Publish the
application using the specified \f[I]project.json\f[]; also use
framework specified withing and runtime for the current operating
system.
.PP
\f[C]dotnet\-publish\ \-\-framework\ dnxcore50\f[] >Publish the current
application using the \f[C]dnxcore50\f[] framework and runtime for the
current operating system.
.PP
\f[C]dotnet\-publish\ \-\-framework\ dnxcore50\ \-\-runtime\ osx.10.10\-x64\f[]
>Publish the current application using the \f[C]dnxcore50\f[] framework
and runtime for \f[C]OS\ X\ 10.10\f[]
.SH SEE ALSO
.PP
\f[C]dotnet\-restore\f[]

38
Documentation/manpages/dotnet-run.1 Normal file
View file

@ -0,0 +1,38 @@
.\" Automatically generated by Pandoc 1.15.1
.\"
.hy
.TH "dotnet-run" "1" "" "" ""
.SH dotnet\-run
.SH NAME
.PP
dotnet\-run \-\- Runs source code \[aq]in\-place\[aq] without any
explicit compile or launch commands.
.SH SYNOPSIS
.PP
dotnet run options (#options)
.SH DESCRIPTION
.PP
The run command provides a convenient option to run source code with one
command.
It compiles source code, generates an output program and then runs that
program.
This command is useful for fast iterative development and can also be
used to run a source\-distributed program (e.g.
website).
.PP
This command relies on the compile
command (https://github.com/dotnet/cli/issues/48) to compile source
inputs to a .NET assembly, before launching the program.
The requirements for and handling of source inputs for this command are
all inhereted from the compile command.
The documentation for the compile command provides more information on
those requirements.
.PP
Output files, are written to the child \f[C]bin\f[] folder, which will
be created if it doesn\[aq]t exist.
Files will be overwritten as needed.
Temporary files are written to the child \f[C]obj\f[] folder.
.SH Options
.PP
\-v, \-\-verbose Prints verbose logging information, to follow the flow
of execution of the command.

12
src/Microsoft.DotNet.Cli/README.md
View file

@ -1,28 +1,28 @@
dotnet
======
**NAME**
# NAME
dotnet -- general driver for running the command-line commands
**SYNOPSIS**
# SYNOPSIS
dotnet [common-options] [command] [arguments]
**DESCRIPTION**
# DESCRIPTION
dotnet is a generic driver for the CLI toolchain. Invoked on its own, it will give out brief usage instructions.
Each specific feature is implemented as a command. In order to use the feautre, it is specified after dotnet, i.e. dotnet compile. All of the arguments following the command are command's own arguments.
**Arguments**
# Arguments
-v, --verbose
Enable verbose output
--version
Print out the version of the CLI tooling
**Commands**
# Commands
There are many possible commands that you can use. The few main ones are:
* run - run your code from source
@ -30,7 +30,7 @@ There are many possible commands that you can use. The few main ones are:
* publish - publish
**SEE ALSO**
# SEE ALSO
dotnet-compile
dotnet-run
dotnet-publish

8
src/Microsoft.DotNet.Tools.Compiler.Csc/README.md
View file

@ -1,13 +1,13 @@
dotnet-compile
===========
**NAME**
# NAME
dotnet-compile -- Compiles source files to a binary format and saves to a target file.
**SYNOPSIS**
# SYNOPSIS
dotnet compile [options]
**DESCRIPTION**
# DESCRIPTION
The compile command compiles source files to a binary file, either IL byte code or native machine code, depending on the options provided. The default option is compilation to IL byte code, but may change in the future.
The default IL [--il] output is a PE32 exe [exe], with the default extension of ".exe" on all OSes. The exe must include a public static void or public static int main entry point, or it is an error. The dll [dll] output option has the default extension of ".dll".
@ -36,7 +36,7 @@ The compile command relies on NuGet dependencies for compilation, as references.
Output files, are written to the child `bin` folder, which will be created if it doesn't exist. Files will be overwritten as needed. The temporary files that are created during compilation are placed in the child `obj` folder.
**Options**
# Options
-n, --native [exe | dynlib | lib]
Compiles source to native machine code, for the local machine. The default is a native executable. The default exe extension is no extension and ".exe" on Windows. The default dynlib extension is ".a", ".dynlib" on OS X and ".dll" on Windows.

8
src/Microsoft.DotNet.Tools.Compiler.Native/README.md
View file

@ -1,20 +1,20 @@
dotnet-compile
===========
**NAME**
# NAME
dotnet-compile-native -- Compiles IL binaries to native binaries.
**SYNOPSIS**
# SYNOPSIS
dotnet compile [options]
**DESCRIPTION**
# DESCRIPTION
The `compile-native` command compiles IL assemblies to native machine code. It is used by `dotnet-compile --native`.
The output is a native exe that conforms to the architecture of the underlying operating system (i.e. running on 64-bit OS will produce a native 64-bit exe). This can be overriden via the --arch switch and specifying the wanted architecture. The executable has a default extension of "" on Linux and OS X and ".exe" on Windows. The source must include a `static void Main(string[] args) entry point and specify compilerOptions.emitEntryPoint in the project.json.
Output files are written to the child `bin` folder, which will be created if it doesn't exist. Files will be overwritten as needed.
**Options**
# Options
--appdepsdk <SDK_PATH>
Path to custom AppDepSDK

10
src/Microsoft.DotNet.Tools.Compiler/README.md
View file

@ -1,13 +1,13 @@
dotnet-compile
===========
**NAME**
# NAME
dotnet-compile -- Compiles source files for a single project to a binary format and saves to a target file.
**SYNOPSIS**
# SYNOPSIS
dotnet compile [options]
**DESCRIPTION**
# DESCRIPTION
The compile command compiles source files from a single project to a binary file, either IL byte code or native machine code, depending on the options provided. The default option is compilation to IL byte code, but may change in the future.
Users who want to benefit from incremental builds and who want to compile both the project and its dependencies should use the Build command.
@ -38,7 +38,7 @@ The compile command relies on NuGet dependencies for compilation, as references.
Output files, are written to the child `bin` folder, which will be created if it doesn't exist. Files will be overwritten as needed. The temporary files that are created during compilation are placed in the child `obj` folder.
**Options**
# Options
-n, --native [exe | dynlib | lib]
Compiles source to native machine code, for the local machine. The default is a native executable. The default exe extension is no extension and ".exe" on Windows. The default dynlib extension is ".a", ".dynlib" on OS X and ".dll" on Windows.
@ -50,4 +50,4 @@ Compiles source to IL byte code, which is (typically) portable across machine ty
Specifies the filename to be used. It is an error not to specify an output filename. If no extension is provided, the default one is provided for the output type.
-v, --verbose
Prints verbose logging information, to follow the flow of execution of the command.
Prints verbose logging information, to follow the flow of execution of the command.

26
src/Microsoft.DotNet.Tools.New/README.md Normal file
View file

@ -0,0 +1,26 @@
dotnet-new
===========
# NAME
dotnet-new -- Create a new sample project
# SYNOPSIS
dotnet new
# DESCRIPTION
The new command provides a convenient way to initalize a valid .NET Core project and sample source code to try out the CLI toolset.
This command is invoked in the context of a directory. When invoked, the command will result in two main artifacts being dropped to the directory:
1. A sample "Hello World" program that exists in `Program.cs` file.
2. A valid `project.json` file
After this, the project is ready to be compiled and/or edited further.
# EXAMPLES
`dotnet new`
Drops a sample in the current directory.
# SEE ALSO
dotnet-run(1)

12
src/Microsoft.DotNet.Tools.Publish/README.md
View file

@ -1,16 +1,16 @@
dotnet-publish
==============
**NAME**
# NAME
`dotnet-publish`
> packs the application and all of its dependencies into a folder getting it ready for publishing
**SYNOPSIS**
# SYNOPSIS
`dotnet-publish [options] [project]`
**DESCRIPTION**
# DESCRIPTION
`dotnet-publish` will compile the application, read through its dependencies specified in _project.json_ and publish the resulting set of files to a directory.
This directory contains the assemblies, the runtime as well as the runnable version of the application.
@ -27,7 +27,7 @@ In case of no valid framework found, the command will error out.
In case of multiple valid frameworks found, the command will publish for all valid frameworks.
**Options**
# Options
`-f`, `--framework` [FID]
@ -55,7 +55,7 @@ If not specified, will default to "Debug".
**EXAMPLES**
# EXAMPLES
`dotnet-publish`
>Publish the current application using the _project.json_ framework and runtime for the current operating system.
@ -69,6 +69,6 @@ If not specified, will default to "Debug".
`dotnet-publish --framework dnxcore50 --runtime osx.10.10-x64`
>Publish the current application using the `dnxcore50` framework and runtime for `OS X 10.10`
**SEE ALSO**
# SEE ALSO
`dotnet-restore`

8
src/Microsoft.DotNet.Tools.Run/README.md
View file

@ -1,20 +1,20 @@
dotnet-run
===========
**NAME**
# NAME
dotnet-run -- Runs source code 'in-place' without any explicit compile or launch commands.
**SYNOPSIS**
# SYNOPSIS
dotnet run [options]
**DESCRIPTION**
# DESCRIPTION
The run command provides a convenient option to run source code with one command. It compiles source code, generates an output program and then runs that program. This command is useful for fast iterative development and can also be used to run a source-distributed program (e.g. website).
This command relies on the [compile command](https://github.com/dotnet/cli/issues/48) to compile source inputs to a .NET assembly, before launching the program. The requirements for and handling of source inputs for this command are all inhereted from the compile command. The documentation for the compile command provides more information on those requirements.
Output files, are written to the child `bin` folder, which will be created if it doesn't exist. Files will be overwritten as needed. Temporary files are written to the child `obj` folder.
**Options**
# Options
-v, --verbose
Prints verbose logging information, to follow the flow of execution of the command.