Update documentation (#3549)
* Updating README.md files as well as man pages This aligns with the latest changes in the official documentation. It also aligns dotnet test readme.md to official docs and introduces a new doc in the "Documentation" directory that deals with dotnet test protocols.
This commit is contained in:
Zlatko Knezevic
GitHub
parent
18c8a2724a
commit
4da4f95e21
16 changed files with 971 additions and 404 deletions
96
Documentation/manpages/sdk/dotnet-build.1
Normal file
96
Documentation/manpages/sdk/dotnet-build.1
Normal file
|
|
@ -0,0 +1,96 @@
|
|||
.\" Automatically generated by Pandoc 1.15.1
|
||||
.\"
|
||||
.hy
|
||||
.TH "DOTNET\-BUILD" "1" "April 2016" "" ""
|
||||
.SS NAME
|
||||
.PP
|
||||
dotnet\-build \-\- Builds a project and all of its dependencies
|
||||
.SS SYNOPSIS
|
||||
.PP
|
||||
\f[C]dotnet\ build\ [\-\-output]\ \ \ \ \ \ \ [\-\-build\-base\-path]\ [\-\-framework]\ \ \ \ \ \ \ [\-\-configuration]\ \ [\-\-runtime]\ [\-\-version\-suffix]\ \ \ \ \ [\-\-build\-profile]\ \ [\-\-no\-incremental]\ [\-\-no\-dependencies]\ \ \ \ \ [<project>]\f[]
|
||||
.SS DESCRIPTION
|
||||
.PP
|
||||
The \f[C]dotnet\ build\f[] command builds multiple source file from a
|
||||
source project and its dependencies into a binary.
|
||||
The binary will be in Intermediate Language (IL) by default and will
|
||||
have a DLL extension.
|
||||
\f[C]dotnet\ build\f[] will also drop a \f[C]\\*.deps\f[] file which
|
||||
outlines what the host needs to run the application.
|
||||
.PP
|
||||
Building requires the existence of a lock file, which means that you
|
||||
have to run \f[C]dotnet\ restore\f[] (dotnet-restore.md) prior to
|
||||
building your code.
|
||||
.PP
|
||||
Before any compilation begins, the build verb analyzes the project and
|
||||
its dependencies for incremental safety checks.
|
||||
If all checks pass, then build proceeds with incremental compilation of
|
||||
the project and its dependencies; otherwise, it falls back to
|
||||
non\-incremental compilation.
|
||||
Via a profile flag, users can choose to receive additional information
|
||||
on how they can improve their build times.
|
||||
.PP
|
||||
All projects in the dependency graph that need compilation must pass the
|
||||
following safety checks in order for the compilation process to be
|
||||
incremental: \- not use pre/post compile scripts \- not load compilation
|
||||
tools from PATH (for example, resgen, compilers) \- use only known
|
||||
compilers (csc, vbc, fsc)
|
||||
.PP
|
||||
In order to build an executable application, you need a special
|
||||
configuration section in your project.json file:
|
||||
.IP
|
||||
.nf
|
||||
\f[C]
|
||||
{\
|
||||
\ \ \ \ "compilerOptions":\ {
|
||||
\ \ \ \ \ \ "emitEntryPoint":\ true
|
||||
\ \ \ \ }
|
||||
}
|
||||
\f[]
|
||||
.fi
|
||||
.SS OPTIONS
|
||||
.PP
|
||||
\f[C]\-o\f[], \f[C]\-\-output\f[] [DIR]
|
||||
.PP
|
||||
Directory in which to place the built binaries.
|
||||
.PP
|
||||
\f[C]\-b\f[], \f[C]\-\-build\-base\-path\f[] [DIR]
|
||||
.PP
|
||||
Directory in which to place temporary outputs.
|
||||
.PP
|
||||
\f[C]\-f\f[], \f[C]\-\-framework\f[] [FRAMEWORK]
|
||||
.PP
|
||||
Compiles for a specific framework.
|
||||
The framework needs to be defined in the project.json file.
|
||||
.PP
|
||||
\f[C]\-c\f[], \f[C]\-\-configuration\f[] [Debug|Release]
|
||||
.PP
|
||||
Defines a configuration under which to build.
|
||||
If omitted, it defaults to Debug.
|
||||
.PP
|
||||
\f[C]\-r\f[], \f[C]\-\-runtime\f[] [RUNTIME_IDENTIFIER]
|
||||
.PP
|
||||
Target runtime to build for.
|
||||
.PP
|
||||
\-\-version\-suffix [VERSION_SUFFIX]
|
||||
.PP
|
||||
Defines what \f[C]*\f[] should be replaced with in the version field in
|
||||
the project.json file.
|
||||
The format follows NuGet\[aq]s version guidelines.
|
||||
.PP
|
||||
\f[C]\-\-build\-profile\f[]
|
||||
.PP
|
||||
Prints out the incremental safety checks that users need to address in
|
||||
order for incremental compilation to be automatically turned on.
|
||||
.PP
|
||||
\f[C]\-\-no\-incremental\f[]
|
||||
.PP
|
||||
Marks the build as unsafe for incremental build.
|
||||
This turns off incremental compilation and forces a clean rebuild of the
|
||||
project dependency graph.
|
||||
.PP
|
||||
\f[C]\-\-no\-dependencies\f[]
|
||||
.PP
|
||||
Ignores project\-to\-project references and only builds the root project
|
||||
specified to build.
|
||||
.SH AUTHORS
|
||||
Microsoft Corporation dotnetclifeedback\@microsoft.com.
|
||||
|
|
@ -1,38 +1,81 @@
|
|||
.\" Automatically generated by Pandoc 1.15.1
|
||||
.\"
|
||||
.hy
|
||||
.TH "dotnet-new" "1" "January 2016" "" ""
|
||||
.SH NAME
|
||||
.TH "DOTNET\-NEW" "1" "June 2016" "" ""
|
||||
.SS NAME
|
||||
.PP
|
||||
dotnet\-new \-\- Create a new sample .NET Core project
|
||||
.SH SYNOPSIS
|
||||
.SS SYNOPSIS
|
||||
.PP
|
||||
dotnet new
|
||||
.SH DESCRIPTION
|
||||
dotnet new [\-\-type] [\-\-lang]
|
||||
.SS 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.
|
||||
The \f[C]dotnet\ new\f[] command provides a convenient way to initialize
|
||||
a valid .NET Core project and sample source code to try out the Command
|
||||
Line Interface (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.
|
||||
A \f[C]Program.cs\f[] (or \f[C]Program.fs\f[]) file that contains a
|
||||
sample "Hello World" program.
|
||||
.IP "2." 3
|
||||
A valid \f[C]project.json\f[] file
|
||||
A valid \f[C]project.json\f[] file.
|
||||
.PP
|
||||
After this, the project is ready to be compiled and/or edited further.
|
||||
.SH EXAMPLES
|
||||
.SS Options
|
||||
.PP
|
||||
\f[C]\-l\f[], \f[C]\-\-lang\ [C#|F#]\f[]
|
||||
.PP
|
||||
Language of the project.
|
||||
Defaults to \f[C]C#\f[].
|
||||
\f[C]csharp\f[] (\f[C]fsharp\f[]) or \f[C]cs\f[] (\f[C]fs\f[]) are also
|
||||
valid options.
|
||||
.PP
|
||||
\f[C]\-t\f[], \f[C]\-\-type\f[]
|
||||
.PP
|
||||
Type of the project.
|
||||
Valid values for C# are:
|
||||
.IP \[bu] 2
|
||||
\f[C]console\f[]
|
||||
.IP \[bu] 2
|
||||
\f[C]web\f[]
|
||||
.IP \[bu] 2
|
||||
\f[C]lib\f[]
|
||||
.IP \[bu] 2
|
||||
\f[C]xunittest\f[]
|
||||
.PP
|
||||
Valid values for F# are:
|
||||
.IP \[bu] 2
|
||||
\f[C]console\f[]
|
||||
.SS EXAMPLES
|
||||
.PP
|
||||
\f[C]dotnet\ new\f[]
|
||||
.IP
|
||||
.nf
|
||||
\f[C]
|
||||
Drops\ a\ sample\ in\ the\ current\ directory.
|
||||
Drops\ a\ sample\ C##\ project\ in\ the\ current\ directory.
|
||||
\f[]
|
||||
.fi
|
||||
.PP
|
||||
\f[C]dotnet\ new\ \-\-lang\ f##\f[]
|
||||
.IP
|
||||
.nf
|
||||
\f[C]
|
||||
Drops\ a\ sample\ F##\ project\ in\ the\ current\ directory.
|
||||
\f[]
|
||||
.fi
|
||||
.PP
|
||||
\f[C]dotnet\ new\ \-\-lang\ c##\f[]
|
||||
.IP
|
||||
.nf
|
||||
\f[C]
|
||||
Drops\ a\ sample\ C##\ project\ in\ the\ current\ directory.
|
||||
\f[]
|
||||
.fi
|
||||
.SH SEE ALSO
|
||||
.PP
|
||||
dotnet\-run(1)
|
||||
.SH AUTHORS
|
||||
Zlatko Knezevic zlakne\@microsoft.com.
|
||||
Microsoft Corporation dotnetclifeedback\@microsoft.com.
|
||||
|
|
|
|||
91
Documentation/manpages/sdk/dotnet-pack.1
Normal file
91
Documentation/manpages/sdk/dotnet-pack.1
Normal file
|
|
@ -0,0 +1,91 @@
|
|||
.\" Automatically generated by Pandoc 1.15.1
|
||||
.\"
|
||||
.hy
|
||||
.TH "DOTNET\-PACK" "1" "June 2016" "" ""
|
||||
.SS NAME
|
||||
.PP
|
||||
\f[C]dotnet\-pack\f[] \- Packs the code into a NuGet package
|
||||
.SS SYNOPSIS
|
||||
.PP
|
||||
\f[C]dotnet\ pack\ [\-\-output]\ \ \ \ \ \ \ [\-\-no\-build]\ [\-\-build\-base\-path]\ \ \ \ \ \ \ [\-\-configuration]\ \ [\-\-version\-suffix]\ \ \ \ \ [<project>]\f[]
|
||||
.SS DESCRIPTION
|
||||
.PP
|
||||
The \f[C]dotnet\ pack\f[] command builds the project and creates NuGet
|
||||
packages.
|
||||
The result of this operation is two packages with the \f[C]nupkg\f[]
|
||||
extension.
|
||||
One package contains the code and the other contains the debug symbols.
|
||||
.PP
|
||||
NuGet dependencies of the project being packed are added to the nuspec
|
||||
file, so they are able to be resolved when the package is installed.
|
||||
Project\-to\-project references are not packaged inside the project by
|
||||
default.
|
||||
If you wish to do this, you need to reference the required project in
|
||||
your dependencies node with a \f[C]type\f[] set to "build" like in the
|
||||
following example:
|
||||
.IP
|
||||
.nf
|
||||
\f[C]
|
||||
{
|
||||
\ \ \ \ "version":\ "1.0.0\-*",
|
||||
\ \ \ \ "dependencies":\ {
|
||||
\ \ \ \ \ \ \ \ "ProjectA":\ {
|
||||
\ \ \ \ \ \ \ \ \ \ \ \ "target":\ "project",
|
||||
\ \ \ \ \ \ \ \ \ \ \ \ "type":\ "build"
|
||||
\ \ \ \ \ \ \ \ }
|
||||
\ \ \ \ }
|
||||
}
|
||||
\f[]
|
||||
.fi
|
||||
.PP
|
||||
\f[C]dotnet\ pack\f[] by default first builds the project.
|
||||
If you wish to avoid this, pass the \f[C]\-\-no\-build\f[] option.
|
||||
This can be useful in Continuous Integration (CI) build scenarios in
|
||||
which you know the code was just previously built, for example.
|
||||
.SS OPTIONS
|
||||
.PP
|
||||
\f[C][project]\f[]
|
||||
.PP
|
||||
The project to pack.
|
||||
It can be either a path to a \f[C]project.json\f[] file or to a
|
||||
directory.
|
||||
If omitted, it will default to the current directory.
|
||||
.PP
|
||||
\f[C]\-o\f[], \f[C]\-\-output\f[] [DIR]
|
||||
.PP
|
||||
Places the built packages in the directory specified.
|
||||
.PP
|
||||
\f[C]\-\-no\-build\f[]
|
||||
.PP
|
||||
Skips the building phase of the packing process.
|
||||
.PP
|
||||
\f[C]\-\-build\-base\-path\f[]
|
||||
.PP
|
||||
Places the temporary build artifacts in the specified directory.
|
||||
By default, they go to the obj directory in the current directory.
|
||||
.PP
|
||||
\f[C]\-c\f[], \f[C]\-\-configuration\ [Debug|Release]\f[]
|
||||
.PP
|
||||
Configuration to use when building the project.
|
||||
If not specified, will default to "Debug".
|
||||
.SS EXAMPLES
|
||||
.PP
|
||||
\f[C]dotnet\ pack\f[]
|
||||
.PP
|
||||
Packs the current project.
|
||||
.PP
|
||||
\f[C]dotnet\ pack\ ~/projects/app1/project.json\f[]
|
||||
.PP
|
||||
Packs the app1 project.
|
||||
.PP
|
||||
\f[C]dotnet\ pack\ \-\-output\ nupkgs\f[]
|
||||
.PP
|
||||
Packs the current application and place the resulting packages into the
|
||||
specified folder.
|
||||
.PP
|
||||
\f[C]dotnet\ pack\ \-\-no\-build\ \-\-output\ nupkgs\f[]
|
||||
.PP
|
||||
Packs the current project into the specified folder and skips the build
|
||||
step.
|
||||
.SH AUTHORS
|
||||
Microsoft Corporation dotnetclifeedback\@microsoft.com.
|
||||
|
|
@ -1,122 +1,107 @@
|
|||
.\" Automatically generated by Pandoc 1.15.1
|
||||
.\"
|
||||
.hy
|
||||
.TH "dotnet-publish" "1" "January 2016" "" ""
|
||||
.SH NAME
|
||||
.TH "DOTNET\-PUBLISH" "1" "June 2016" "" ""
|
||||
.SS NAME
|
||||
.PP
|
||||
\f[C]dotnet\-publish\f[] \- packs the application and all of its
|
||||
\f[C]dotnet\-publish\f[] \- Packs the application and all of its
|
||||
dependencies into a folder getting it ready for publishing
|
||||
.SH SYNOPSIS
|
||||
.SS SYNOPSIS
|
||||
.PP
|
||||
dotnet\-publish [\-\-framework] [\-\-runtime] [\-\-output]
|
||||
[\-\-configuration]
|
||||
\f[C]dotnet\ publish\ [\-\-framework]\ \ \ \ \ \ \ [\-\-runtime]\ [\-\-build\-base\-path]\ [\-\-output]\ \ \ \ \ \ \ [\-\-version\-suffix]\ [\-\-configuration]\ \ \ \ \ \ \ [<project>]\f[]
|
||||
.SS DESCRIPTION
|
||||
.PP
|
||||
\f[C]dotnet\ publish\f[] compiles the application, reads through its
|
||||
dependencies specified in the \f[C]project.json\f[] file and publishes
|
||||
the resulting set of files to a directory.
|
||||
.PP
|
||||
Depending on the type of portable app, the resulting directory will
|
||||
contain the following:
|
||||
.IP "1." 3
|
||||
\f[B]Portable application\f[] \- application\[aq]s intermediate language
|
||||
(IL) code and all of application\[aq]s managed dependencies.
|
||||
.RS 4
|
||||
.IP \[bu] 2
|
||||
\f[B]Portable application with native dependencies\f[] \- same as above
|
||||
with a sub\-directory for the supported platform of each native
|
||||
dependency.
|
||||
.RE
|
||||
.IP "2." 3
|
||||
\f[B]Self\-contained application\f[] \- same as above plus the entire
|
||||
runtime for the targeted platform.
|
||||
.PP
|
||||
The above types are covered in more details in the types of portable
|
||||
applications (../../app-types.md) topic.
|
||||
.SS OPTIONS
|
||||
.PP
|
||||
\f[C][project]\f[]
|
||||
.PP
|
||||
\f[C]dotnet\ publish\f[] needs access to the \f[C]project.json\f[] file
|
||||
to work.
|
||||
If it is not specified on invocation via [project],
|
||||
\f[C]project.json\f[] in the current directory will be the default.
|
||||
.PD 0
|
||||
.P
|
||||
.PD
|
||||
[< project >]
|
||||
.SH DESCRIPTION
|
||||
.PP
|
||||
\f[C]dotnet\-publish\f[] will compile the application, read through its
|
||||
dependencies specified in \f[C]project.json\f[] and publish the
|
||||
resulting set of files to a directory.
|
||||
This directory will contain the assemblies, the runtime as well as the
|
||||
executable version of the application.
|
||||
This directory can then be moved to a different machine and the
|
||||
application will be able to run regardless of existence of any other
|
||||
runtime.
|
||||
.PP
|
||||
The native dependencies of the runtime are not packaged with the
|
||||
application.
|
||||
This means that the target machine needs to have the native dependencies
|
||||
installed in order for the application to run.
|
||||
.SH OPTIONS
|
||||
.PP
|
||||
\f[C][project]\f[]
|
||||
.IP
|
||||
.nf
|
||||
\f[C]
|
||||
`dotnet\-publish`\ needs\ access\ to\ `project.json`\ to\ work.\ If\ it\ is\ not\ specified\ on\ invocation\ via\ [project],\ `project.json`\ in\ the\ current\ directory\ will\ be\ the\ default.\ \ \ \ \ If\ no\ `project.json`\ can\ be\ found,\ `dotnet\-publish`\ will\ error\ out.\ `dotnet\-publish`\ command\ also\ requires\ certain\ dependencies\ in\ the\ `project.json`\ to\ work.\ Namely\ the\ `Microsoft.NETCore.Runtime`\ package\ must\ be\ referenced\ as\ a\ dependency\ in\ order\ for\ the\ command\ to\ copy\ the\ runtime\ files\ as\ well\ as\ the\ application\[aq]s\ files\ to\ the\ published\ location.\ \
|
||||
\f[]
|
||||
.fi
|
||||
If no \f[C]project.json\f[] can be found, \f[C]dotnet\ publish\f[] will
|
||||
throw an error.
|
||||
.PP
|
||||
\f[C]\-f\f[], \f[C]\-\-framework\f[] [FID]
|
||||
.IP
|
||||
.nf
|
||||
\f[C]
|
||||
Publish\ the\ application\ for\ a\ given\ framework\ identifier\ (FID).\ If\ not\ specified,\ FID\ is\ read\ from\ `project.json`.\ 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.\
|
||||
\f[]
|
||||
.fi
|
||||
.PP
|
||||
Publishes the application for a given framework identifier (FID).
|
||||
If not specified, FID is read from \f[C]project.json\f[].
|
||||
In no valid framework is found, the command will throw an error.
|
||||
If multiple valid frameworks are found, the command will publish for all
|
||||
valid frameworks.
|
||||
.PP
|
||||
\f[C]\-r\f[], \f[C]\-\-runtime\f[] [RID]
|
||||
.IP
|
||||
.nf
|
||||
\f[C]
|
||||
Publish\ the\ application\ for\ a\ given\ runtime.\ If\ the\ option\ is\ not\ specified,\ the\ command\ will\ default\ to\ the\ runtime\ for\ the\ current\ operationg\ system.\ Supported\ values\ for\ the\ option\ at\ this\ time\ are:
|
||||
|
||||
\ \ \ \ *\ ubuntu.14.04\-x64
|
||||
\ \ \ \ *\ ubuntu.16.04\-x64
|
||||
\ \ \ \ *\ win7\-x64
|
||||
\ \ \ \ *\ win7\-x86
|
||||
\ \ \ \ *\ osx.10.10\-x64
|
||||
\ \ \ \ *\ osx.10.11\-x64
|
||||
\ \ \ \ *\ centos.7\-x64
|
||||
\ \ \ \ *\ rhel.7.2\-x64
|
||||
\ \ \ \ *\ debian.8\-x64
|
||||
\ \ \ \ *\ fedora.23\-x64
|
||||
\ \ \ \ *\ opensuse.13.2\-x64
|
||||
\f[]
|
||||
.fi
|
||||
.PP
|
||||
Publishes the application for a given runtime.
|
||||
.PP
|
||||
\f[C]\-b\f[], \f[C]\-\-build\-base\-path\f[] [DIR]
|
||||
.PP
|
||||
Directory in which to place temporary outputs.
|
||||
.PP
|
||||
\f[C]\-o\f[], \f[C]\-\-output\f[]
|
||||
.IP
|
||||
.nf
|
||||
\f[C]
|
||||
Specify\ the\ path\ where\ to\ place\ the\ directory.\ If\ not\ specified,\ will\ default\ to\ _./bin/[configuration]/[framework]/[runtime]/_
|
||||
\f[]
|
||||
.fi
|
||||
.PP
|
||||
Specify the path where to place the directory.
|
||||
If not specified, it will default to
|
||||
\f[I]\&./bin/[configuration]/[framework]/\f[] for portable applications
|
||||
or \f[I]\&./bin/[configuration]/[framework]/[runtime]\f[] for
|
||||
self\-contained applications.
|
||||
.PP
|
||||
\-\-version\-suffix [VERSION_SUFFIX]
|
||||
.PP
|
||||
Defines what \f[C]*\f[] should be replaced with in the version field in
|
||||
the project.json file.
|
||||
.PP
|
||||
\f[C]\-c\f[], \f[C]\-\-configuration\ [Debug|Release]\f[]
|
||||
.IP
|
||||
.nf
|
||||
\f[C]
|
||||
Configuration\ to\ use\ when\ publishing.\ If\ not\ specified,\ will\ default\ to\ "Debug".
|
||||
\f[]
|
||||
.fi
|
||||
.SH EXAMPLES
|
||||
.PP
|
||||
\f[C]dotnet\-publish\f[]
|
||||
.IP
|
||||
.nf
|
||||
\f[C]
|
||||
Publish\ the\ current\ application\ using\ the\ `project.json`\ framework\ and\ runtime\ for\ the\ current\ operating\ system.\
|
||||
\f[]
|
||||
.fi
|
||||
Configuration to use when publishing.
|
||||
The default value is Debug.
|
||||
.SS EXAMPLES
|
||||
.PP
|
||||
\f[C]dotnet\-publish\ ~/projects/app1/project.json\f[]
|
||||
.IP
|
||||
.nf
|
||||
\f[C]
|
||||
Publish\ the\ application\ using\ the\ specified\ `project.json`;\ also\ use\ framework\ specified\ withing\ and\ runtime\ for\ the\ current\ operating\ system.\
|
||||
\f[]
|
||||
.fi
|
||||
\f[C]dotnet\ publish\f[]
|
||||
.PP
|
||||
\f[C]dotnet\-publish\ \-\-framework\ dnxcore50\f[]
|
||||
.IP
|
||||
.nf
|
||||
\f[C]
|
||||
Publish\ the\ current\ application\ using\ the\ `dnxcore50`\ framework\ and\ runtime\ for\ the\ current\ operating\ system.\
|
||||
\f[]
|
||||
.fi
|
||||
Publishes an application using the framework found in
|
||||
\f[C]project.json\f[].
|
||||
If \f[C]project.json\f[] contains \f[C]runtimes\f[] node, publish for
|
||||
the RID of the current platform.
|
||||
.PP
|
||||
\f[C]dotnet\-publish\ \-\-framework\ dnxcore50\ \-\-runtime\ osx.10.10\-x64\f[]
|
||||
.IP
|
||||
.nf
|
||||
\f[C]
|
||||
Publish\ the\ current\ application\ using\ the\ `dnxcore50`\ framework\ and\ runtime\ for\ `OS\ X\ 10.10`
|
||||
\f[]
|
||||
.fi
|
||||
.SH SEE ALSO
|
||||
\f[C]dotnet\ publish\ ~/projects/app1/project.json\f[]
|
||||
.PP
|
||||
dotnet\-restore(1), dotnet\-compile(1)
|
||||
Publishes the application using the specified \f[C]project.json\f[].
|
||||
.PP
|
||||
\f[C]dotnet\ publish\ \-\-framework\ netcoreapp1.0\f[]
|
||||
.PP
|
||||
Publishes the current application using the \f[C]netcoreapp1.0\f[]
|
||||
framework.
|
||||
.PP
|
||||
\f[C]dotnet\ publish\ \-\-framework\ netcoreapp1.0\ \-\-runtime\ osx.10.11\-x64\f[]
|
||||
.PP
|
||||
Publishes the current application using the \f[C]netcoreapp1.0\f[]
|
||||
framework and runtime for \f[C]OS\ X\ 10.10\f[].
|
||||
This RID has to exist in the \f[C]project.json\f[] \f[C]runtimes\f[]
|
||||
node.
|
||||
.SH AUTHORS
|
||||
Zlatko Knezevic zlakne\@microsoft.com.
|
||||
Microsoft Corporation dotnetclifeedback\@microsoft.com.
|
||||
|
|
|
|||
97
Documentation/manpages/sdk/dotnet-restore.1
Normal file
97
Documentation/manpages/sdk/dotnet-restore.1
Normal file
|
|
@ -0,0 +1,97 @@
|
|||
.\" Automatically generated by Pandoc 1.15.1
|
||||
.\"
|
||||
.hy
|
||||
.TH "DOTNET\-RESTORE" "1" "June 2016" "" ""
|
||||
.SS NAME
|
||||
.PP
|
||||
\f[C]dotnet\-restore\f[] \- Restores the dependencies and tools of a
|
||||
project
|
||||
.SS SYNOPSIS
|
||||
.PP
|
||||
\f[C]dotnet\ restore\ [\-\-source]\ \ \ \ \ \ \ [\-\-packages]\ [\-\-disable\-parallel]\ \ \ \ \ \ \ [\-\-fallbacksource]\ [\-\-configfile]\ [\-\-verbosity]\ \ \ \ \ [<root>]\f[]
|
||||
.SS DESCRIPTION
|
||||
.PP
|
||||
The \f[C]dotnet\ restore\f[] command uses NuGet to restore dependencies
|
||||
as well as project\-specific tools that are specified in the
|
||||
project.json file.
|
||||
By default, the restoration of dependencies and tools are done in
|
||||
parallel.
|
||||
.PP
|
||||
In order to restore the dependencies, NuGet needs the feeds where the
|
||||
packages are located.
|
||||
Feeds are usually provided via the NuGet.config configuration file; a
|
||||
default one is present when the CLI tools are installed.
|
||||
You can specify more feeds by creating your own NuGet.config file in the
|
||||
project directory.
|
||||
Feeds can also be specified per invocation on the command line.
|
||||
.PP
|
||||
For dependencies, you can specify where the restored packages are placed
|
||||
during the restore operation using the \f[C]\-\-packages\f[] argument.
|
||||
If not specified, the default NuGet package cache is used.
|
||||
It is found in the \f[C]\&.nuget/packages\f[] directory in the
|
||||
user\[aq]s home directory on all operating systems (for example,
|
||||
\f[C]/home/user1\f[] on Linux or \f[C]C:\\Users\\user1\f[] on Windows).
|
||||
.PP
|
||||
For project\-specific tooling, \f[C]dotnet\ restore\f[] first restores
|
||||
the package in which the tool is packed, and then proceeds to restore
|
||||
the tool\[aq]s dependencies as specified in its project.json.
|
||||
.SS OPTIONS
|
||||
.PP
|
||||
\f[C][root]\f[]
|
||||
.PP
|
||||
A list of projects or project folders to restore.
|
||||
The list can contain either a path to a \f[C]project.json\f[] file, or a
|
||||
path to \f[C]global.json\f[] file or folder.
|
||||
The restore operation runs recursively for all subdirectories and
|
||||
restores for each given project.json file it finds.
|
||||
.PP
|
||||
\f[C]\-s\f[], \f[C]\-\-source\f[] [SOURCE]
|
||||
.PP
|
||||
Specifies a source to use during the restore operation.
|
||||
This overrides all of the sources specified in the NuGet.config file(s).
|
||||
.PP
|
||||
\f[C]\-\-packages\f[] [DIR]
|
||||
.PP
|
||||
Specifies the directory to place the restored packages in.
|
||||
.PP
|
||||
\f[C]\-\-disable\-parallel\f[]
|
||||
.PP
|
||||
Disables restoring multiple projects in parallel.
|
||||
.PP
|
||||
\f[C]\-f\f[], \f[C]\-\-fallbacksource\f[] [FEED]
|
||||
.PP
|
||||
Specifies a fallback source that will be used in the restore operation
|
||||
if all other sources fail.
|
||||
All valid feed formats are allowed.
|
||||
.PP
|
||||
\f[C]\-\-configfile\f[] [FILE]
|
||||
.PP
|
||||
Configuration file (NuGet.config) to use for the restore operation.
|
||||
.PP
|
||||
\f[C]\-\-verbosity\f[] [LEVEL]
|
||||
.PP
|
||||
The verbosity of logging to use.
|
||||
Allowed values: Debug, Verbose, Information, Minimal, Warning, or Error.
|
||||
.SS EXAMPLES
|
||||
.PP
|
||||
\f[C]dotnet\ restore\f[]
|
||||
.PP
|
||||
Restores dependencies and tools for the project in the current
|
||||
directory.
|
||||
.PP
|
||||
\f[C]dotnet\ restore\ ~/projects/app1/project.json\f[]
|
||||
.PP
|
||||
Restores dependencies and tools for the \f[C]app1\f[] project found in
|
||||
the given path.
|
||||
.PP
|
||||
\f[C]dotnet\ restore\ \-\-f\ c:\\packages\\mypackages\f[]
|
||||
.PP
|
||||
Restores the dependencies and tools for the project in the current
|
||||
directory using the file path provided as the fallback source.
|
||||
.PP
|
||||
\f[C]dotnet\ restore\ \-\-verbosity\ Error\f[]
|
||||
.PP
|
||||
Restores dependencies and tools for the project in the current directory
|
||||
and shows only errors in the output.
|
||||
.SH AUTHORS
|
||||
Microsoft Corporation dotnetclifeedback\@microsoft.com.
|
||||
|
|
@ -1,46 +1,88 @@
|
|||
.\" Automatically generated by Pandoc 1.15.1
|
||||
.\"
|
||||
.hy
|
||||
.TH "dotnet-run" "1" "January 2016" "" ""
|
||||
.SH NAME
|
||||
.TH "DOTNET\-RUN" "1" "June 2016" "" ""
|
||||
.SS NAME
|
||||
.PP
|
||||
dotnet\-run \-\- Runs source code \[aq]in\-place\[aq] without any
|
||||
explicit compile or launch commands.
|
||||
.SH SYNOPSIS
|
||||
.SS SYNOPSIS
|
||||
.PP
|
||||
\f[C]dotnet\ run\ [\-\-verbose]\f[]
|
||||
.SH DESCRIPTION
|
||||
\f[C]dotnet\ run\ [\-\-framework]\ [\-\-configuration]\ \ \ \ \ [\-\-project]\ [\-\-help]\ [\-\-]\f[]
|
||||
.SS DESCRIPTION
|
||||
.PP
|
||||
The run command provides a convenient option to run source code with one
|
||||
command.
|
||||
The \f[C]dotnet\ run\f[] command provides a convenient option to run
|
||||
your application from the 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).
|
||||
used to run a source\-distributed program (for example, a website).
|
||||
.PP
|
||||
This command relies on \f[C]dotnet\-compile(1)\f[] 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 inherited from the compile command.
|
||||
The documentation for the compile command provides more information on
|
||||
This command relies on \f[C]dotnet\ build\f[] (dotnet-build.md) to build
|
||||
source inputs to a .NET assembly, before launching the program.
|
||||
The requirements for this command and the handling of source inputs are
|
||||
all inherited from the build command.
|
||||
The documentation for the build 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.
|
||||
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
|
||||
.IP
|
||||
.nf
|
||||
\f[C]
|
||||
Prints\ verbose\ logging\ information,\ to\ follow\ the\ flow\ of\ execution\ of\ the\ command.
|
||||
\f[]
|
||||
.fi
|
||||
.SH SEE ALSO
|
||||
In case of a project with multiple specified frameworks,
|
||||
\f[C]dotnet\ run\f[] will first select the .NET Core frameworks.
|
||||
If those do not exist, it will error out.
|
||||
To specify other frameworks, use the \f[C]\-\-framework\f[] argument.
|
||||
.PP
|
||||
dotnet\-compile(1), dotnet\-publish(1)
|
||||
The \f[C]dotnet\ run\f[] command must be used in the context of
|
||||
projects, not built assemblies.
|
||||
If you\[aq]re trying to execute a DLL instead, you should use
|
||||
\f[C]dotnet\f[] (dotnet.md) without any command like in the following
|
||||
example:
|
||||
.PP
|
||||
\f[C]dotnet\ myapp.dll\f[]
|
||||
.PP
|
||||
For more information about the \f[C]dotnet\f[] driver, see the \&.NET
|
||||
Core Command Line Tools (CLI) (overview.md) topic.
|
||||
.SS OPTIONS
|
||||
.PP
|
||||
\f[C]\-\-\f[]
|
||||
.PP
|
||||
Delimits arguments to \f[C]dotnet\ run\f[] from arguments for the
|
||||
application being run.
|
||||
All arguments after this one will be passed to the application being
|
||||
run.
|
||||
.PP
|
||||
\f[C]\-f\f[], \f[C]\-\-framework\f[] [FID]
|
||||
.PP
|
||||
Runs the application for a given framework identifier (FID).
|
||||
.PP
|
||||
\f[C]\-c\f[], \f[C]\-\-configuration\ [Debug|Release]\f[]
|
||||
.PP
|
||||
Configuration to use when publishing.
|
||||
The default value is "Debug".
|
||||
.PP
|
||||
\f[C]\-p\f[], \f[C]\-\-project\ [PATH]\f[]
|
||||
.PP
|
||||
Specifies which project to run.
|
||||
It can be a path to a project.json file or to a directory containing a
|
||||
project.json file.
|
||||
It defaults to current directory if not specified.
|
||||
.SS EXAMPLES
|
||||
.PP
|
||||
\f[C]dotnet\ run\f[]
|
||||
.PP
|
||||
Runs the project in the current directory.
|
||||
.PP
|
||||
\f[C]dotnet\ run\ \-\-project\ /projects/proj1/project.json\f[]
|
||||
.PP
|
||||
Runs the project specified.
|
||||
.PP
|
||||
\f[C]dotnet\ run\ \-\-configuration\ Release\ \-\-\ \-\-help\f[]
|
||||
.PP
|
||||
Runs the project in the current directory.
|
||||
The \f[C]\-\-help\f[] argument above is passed to the application being
|
||||
run, since the \f[C]\-\-\f[] argument was used.
|
||||
.SH AUTHORS
|
||||
Zlatko Knezevic zlakne\@microsoft.com.
|
||||
Microsoft Corporation dotnetclifeedback\@microsoft.com.
|
||||
|
|
|
|||
170
Documentation/manpages/sdk/dotnet-test.1
Normal file
170
Documentation/manpages/sdk/dotnet-test.1
Normal file
|
|
@ -0,0 +1,170 @@
|
|||
.\" Automatically generated by Pandoc 1.15.1
|
||||
.\"
|
||||
.hy
|
||||
.TH "DOTNET\-TEST" "1" "April 2016" "" ""
|
||||
.SH Dotnet Test, Adapters and Test Runners
|
||||
.PP
|
||||
This document covers the interactions between dotnet test, a potential
|
||||
adapter (like VS) and test runners (like
|
||||
xunit (https://github.com/dotnet/coreclr.xunit)).
|
||||
.PP
|
||||
It describes the communication protocol for these agents, the parameters
|
||||
that the runner needs to support and the modes on which dotnet test and
|
||||
the runner work.
|
||||
.SS Running modes
|
||||
.PP
|
||||
Dotnet test supports two running modes:
|
||||
.IP "1." 3
|
||||
Console: In console mode, dotnet test simply executes fully whatever
|
||||
command gets passed to it and outputs the results.
|
||||
Anytime you invoke dotnet test without passing \-\-port, it will run in
|
||||
console mode, which in turn will cause the runner to run in console
|
||||
mode.
|
||||
.IP "2." 3
|
||||
Design time: Anytime you pass a port to dotnet test, we will run in
|
||||
design time.
|
||||
That means that dotnet test will connect to that port using TCP and will
|
||||
then exchange a established set of messages with whatever else is
|
||||
connected to that port.
|
||||
When this happens, the runner also receives a port (a new one, mind you)
|
||||
that dotnet test will use to communicate with it.
|
||||
The reason why the runner also uses TCP to communicate with dotnet test
|
||||
is because in design mode, it is not sufficient to just output results
|
||||
to the console.
|
||||
We need to send the adapter structure messages containing the results of
|
||||
the test execution.
|
||||
.SS Communication protocol in design time.
|
||||
.IP "1." 3
|
||||
Because during design time, dotnet test connects to a port when it
|
||||
starts up, the adapter needs to be listening on that port otherwise
|
||||
dotnet test will fail.
|
||||
We did it like this so that the adapter could reserve all the ports it
|
||||
needs by binding and listening to them before dotnet test ran and tried
|
||||
to get ports for the runner.
|
||||
.IP "2." 3
|
||||
Once dotnet test starts, it sends a TestSession.Connected message to the
|
||||
adapter indicating that it is ready to receive messages.
|
||||
.IP "3." 3
|
||||
It is possible to send an optional version
|
||||
check (https://github.com/dotnet/cli/blob/rel/1.0.0/src/Microsoft.Extensions.Testing.Abstractions/Messages/ProtocolVersionMessage.cs)
|
||||
message with the adapter version of the protocol in it.
|
||||
Dotnet test will send back the version of the protocol that it supports.
|
||||
.PP
|
||||
All messages have the format described here:
|
||||
Message.cs (https://github.com/dotnet/cli/blob/rel/1.0.0/src/Microsoft.Extensions.Testing.Abstractions/Messages/Message.cs).
|
||||
The payload formats for each message is described in links to the
|
||||
classes used to de/serialize the information in the description of the
|
||||
protocol.
|
||||
.SS Test Execution
|
||||
.PP
|
||||
[IMAGE: alt
|
||||
tag (../../../../Documentation/images/DotnetTestExecuteTests.png)]
|
||||
.IP "1." 3
|
||||
After the optional version check, the adapter sends a
|
||||
TestExecution.GetTestRunnerProcessStartInfo, with the
|
||||
tests (https://github.com/dotnet/cli/blob/rel/1.0.0/src/Microsoft.Extensions.Testing.Abstractions/Messages/RunTestsMessage.cs)
|
||||
it wants to execute inside of it.
|
||||
Dotnet test sends back a FileName and Arguments inside a
|
||||
TestStartInfo (https://github.com/dotnet/cli/blob/rel/1.0.0/src/dotnet/commands/dotnet-test/TestStartInfo.cs)
|
||||
payload that the adapter can use to start the runner.
|
||||
In the past, we would send the list of tests to run as part of that
|
||||
argument, but we were actually going over the command line size limit
|
||||
for some test projects.
|
||||
.IP "2." 3
|
||||
As part of the arguments, we send a port that the runner should connect
|
||||
to and for executing tests, a \-\-wait\-command flag, that indicates
|
||||
that the runner should connect to the port and wait for commands,
|
||||
instead of going ahead and executing the tests.
|
||||
.IP "3." 3
|
||||
At this point, the adapter can launch the runner (and attach to it for
|
||||
debugging if it chooses to).
|
||||
.IP "4." 3
|
||||
Once the runner starts, it sends dotnet test a TestRunner.WaitCommand
|
||||
message that indicates it is ready to receive commands, at which point
|
||||
dotnet test sends a TestRunner.Execute with the list of
|
||||
tests (https://github.com/dotnet/cli/blob/rel/1.0.0/src/Microsoft.Extensions.Testing.Abstractions/Messages/RunTestsMessage.cs)
|
||||
to run.
|
||||
This bypasses the command line size limit described above.
|
||||
.IP "5." 3
|
||||
The runner then sends dotnet test (and it passes forward to the adapter)
|
||||
a TestExecution.TestStarted for each tests as they start with the
|
||||
test (https://github.com/dotnet/cli/blob/rel/1.0.0/src/Microsoft.Extensions.Testing.Abstractions/Test.cs)
|
||||
information inside of it.
|
||||
.IP "6." 3
|
||||
The runner also sends dotnet test (and it forwards to the adapter) a
|
||||
TestExecution.TestResult for each test with the individual
|
||||
result (https://github.com/dotnet/cli/blob/rel/1.0.0/src/Microsoft.Extensions.Testing.Abstractions/TestResult.cs)
|
||||
of the test.
|
||||
.IP "7." 3
|
||||
After all tests finish, the runner sends a TestRunner.Completed message
|
||||
to dotnet test, which dotnet test sends as TestExecution.Completed to
|
||||
the adapter.
|
||||
.IP "8." 3
|
||||
Once the adapter is done, it sends dotnet test a TestSession.Terminate
|
||||
which will cause dotnet test to shutdown.
|
||||
.SS Test discovery
|
||||
.PP
|
||||
[IMAGE: alt
|
||||
tag (../../../..//Documentation/images/DotnetTestDiscoverTests.png)]
|
||||
.IP "1." 3
|
||||
After the optional version check, the adapter sends a
|
||||
TestDiscovery.Start message.
|
||||
Because in this case, the adapter does not need to attach to the
|
||||
process, dotnet test will start the runner itself.
|
||||
Also, since there is no long list of arguments to be passed to the
|
||||
runner, no \-\-wait\-command flag is needed to be passed to the runner.
|
||||
dotnet test only passes a \-\-list argument to the runner, which means
|
||||
the runner should not run the tests, just list them.
|
||||
.IP "2." 3
|
||||
The runner then sends dotnet test (and it passes forward to the adapter)
|
||||
a TestDiscovery.TestFound for each
|
||||
test (https://github.com/dotnet/cli/blob/rel/1.0.0/src/Microsoft.Extensions.Testing.Abstractions/Test.cs)
|
||||
found.
|
||||
.IP "3." 3
|
||||
After all tests are discovered, the runner sends a TestRunner.Completed
|
||||
message to dotnet test, which dotnet test sends as
|
||||
TestDiscovery.Completed to the adapter.
|
||||
.IP "4." 3
|
||||
Once the adapter is done, it sends dotnet test a TestSession.Terminate
|
||||
which will cause dotnet test to shutdown.
|
||||
.SS Dotnet test parameters
|
||||
.PP
|
||||
Any parameters not accepted by dotnet test will be forwarded to the
|
||||
runner.
|
||||
This is the list of parameters supported by dotnet test from its own
|
||||
help print out:
|
||||
.PP
|
||||
Usage: dotnet test [arguments] [options]
|
||||
.PP
|
||||
Arguments: The project to test, defaults to the current directory.
|
||||
Can be a path to a project.json or a project directory.
|
||||
.PP
|
||||
Options: \-?|\-h|\-\-help Show help information \-\-parentProcessId Used
|
||||
by IDEs to specify their process ID.
|
||||
Test will exit if the parent process does.
|
||||
\-\-port Used by IDEs to specify a port number to listen for a
|
||||
connection.
|
||||
\-c|\-\-configuration Configuration under which to build \-o|\-\-output
|
||||
Directory in which to find the binaries to be run
|
||||
\-b|\-\-build\-base\-path Directory in which to find temporary outputs
|
||||
\-f|\-\-framework Looks for test binaries for a specific framework
|
||||
\-r|\-\-runtime Look for test binaries for a for the specified runtime
|
||||
\-\-no\-build Do not build project before testing
|
||||
.SS Minimum parameters that the runner needs to support
|
||||
.IP \[bu] 2
|
||||
AssemblyUnderTest: Path to the dll that contains the tests to be run.
|
||||
.IP \[bu] 2
|
||||
\-\-port: Used by dotnet test to specify a port number that the runner
|
||||
should connect to.
|
||||
.IP \[bu] 2
|
||||
\-\-list: Indicates that the tests should only be listed and not
|
||||
executed.
|
||||
.IP \[bu] 2
|
||||
\-\-designtime: Indicates that the runner is running in design time, for
|
||||
instance, inside an adapter.
|
||||
.IP \[bu] 2
|
||||
\-\-wait\-command: Indicates that the runner should wait to receive
|
||||
commands through the TCP channel instead of running tests right away.
|
||||
We use this to get around the command line size limit.
|
||||
.SH AUTHORS
|
||||
Microsoft Corporation dotnetclifeedback\@microsoft.com.
|
||||
Loading…
Add table
Add a link
Reference in a new issue