Cleaning up the documentation folder (#5928)
* Cleaning up the documentation folder This change cleans up the documentation folder in the CLI repo. The changes are the following: * Delete old content that is invalid moving forward. * Move cli-installation-scenarios to the `specs` sub-folder. * Add a sub-folder for documentation that deals with working with the repo * Add a general sub-folder * Finally, change the README.md to reflect this. Also, this change adds a document that covers CLI UX guidelines for authors of new commands. * Firt round of PR feedback changes
This commit is contained in:
Zlatko Knezevic
GitHub
parent
890676ad87
commit
09b6be5990
15 changed files with 267 additions and 201 deletions
|
|
@ -1,6 +1,27 @@
|
|||
Documents Index
|
||||
===============
|
||||
|
||||
- [Developer Guide](developer-guide.md)
|
||||
## Overview and general information
|
||||
|
||||
- [Intro to .NET Core CLI](intro-to-cli.md)
|
||||
- [Addressing Incremental Compilation Warnings](addressing-incremental-compilation-warnings.md)
|
||||
- [CLI UX Guidelines](cli-ux-guidelines.md)
|
||||
- [.NET Core native pre-requisities document](https://github.com/dotnet/core/blob/master/Documentation/prereqs.md)
|
||||
- [Roadmap and OS support](https://github.com/dotnet/core/blob/master/roadmap.md)
|
||||
- [Comprehensive CLI documentation](https://docs.microsoft.com/en-us/dotnet/articles/core/preview3/tools/)
|
||||
|
||||
## Working with the CLI repo
|
||||
|
||||
- [Developer Guide](project-docs/developer-guide.md)
|
||||
- [How to file issues](project-docs/issue-filing.guide.md)
|
||||
|
||||
## Troubleshooting and issues reporting
|
||||
|
||||
- [CLI Known Issues](https://github.com/dotnet/core/blob/master/cli/known-issues.md)
|
||||
- [Filing migration issues](migration-issues.md)
|
||||
|
||||
## Specifications
|
||||
|
||||
- [CLI installation scenarios](specs/cli-installation-scenarios.md)
|
||||
- [Corehost specification](specs/corehost.md)
|
||||
- [Runtime configuration file specification](specs/runtime-configuration-file.md)
|
||||
|
||||
|
|
|
|||
|
|
@ -1,17 +0,0 @@
|
|||
Addressing Incremental Compilation Warnings
|
||||
===========================================
|
||||
|
||||
Incremental compilation is unsafe when compilation relies on tools with potential side effects (tools that can cause data races or modify the state of other projects that have been deemed safe to skip compilation. Or tools that integrate timestamps or GUIDs into the build output).
|
||||
|
||||
The presence of such cases will turn off incremental compilation.
|
||||
|
||||
The following represent warning codes printed by CLI when the project structure is unsafe for incremental build and advice on how to address them:
|
||||
|
||||
- __[Pre / Post scripts]__: Scripts that run before and after each compiler invocation can introduce side effects that could cause incremental compilation to output corrupt builds (not building when it should have built) or to over-build. Consider modifying the project structure to run these scripts before / after the entire compile process, not between compiler invocations.
|
||||
|
||||
- __[PATH probing]__: Resolving tool names from PATH is problematic. First, we cannot detect when PATH tools change (which would to trigger re-compilation of sources). Second, it adds machine specific dependencies which would cause the build to succeed on some machines and fail on others. Consider using NuGet packages instead of PATH resolved tools. Thus there would be no machine specific dependencies and we would be able track when NuGet packages change and therefore trigger re-compilation.
|
||||
|
||||
- __[Unknown Compiler]__: csc, vbc, and fsc have known side effects (which files and directories they read, write, and what they are not reading/writing).
|
||||
We don’t know this for other compilers. So we choose to be safe and disable incremental compilation for now. We are planning to enable specification of tool side effects in a future version, so that they can participate in incremental compilation as well.
|
||||
|
||||
- __[Forced Unsafe]__: The build was not incremental because the `--no-incremental` flag was used. Remove this flag to enable incremental compilation.
|
||||
|
|
@ -1,4 +0,0 @@
|
|||
CLI native prerequisites
|
||||
=========================
|
||||
|
||||
This document now lives in the [.NET Core native pre-requisities document](https://github.com/dotnet/core/blob/master/Documentation/prereqs.md) in the dotnet/core repository.
|
||||
|
|
@ -1,44 +0,0 @@
|
|||
dotnet-test communication protocol
|
||||
===================================
|
||||
|
||||
## Introduction
|
||||
Anytime you pass a port to dotnet test, the command will run in design time. That means that dotnet test will connect to that port
|
||||
using TCP and will then exchange an established set of messages with whatever else is connected to that port. When this happens, the runner
|
||||
also receives a new port 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. The
|
||||
command needs to send the adapter structure messages containing the results of the test execution.
|
||||
|
||||
### Communication protocol at design time.
|
||||
|
||||
1. 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.
|
||||
2. Once dotnet test starts, it sends a TestSession.Connected message to the adapter indicating that it is ready to receive messages.
|
||||
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.
|
||||
|
||||
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 serialize/deseralize the information in the description of the protocol.
|
||||
|
||||
#### Test Execution
|
||||
|
||||
|
||||
1. 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.
|
||||
1. 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.
|
||||
2. At this point, the adapter can launch the runner (and attach to it for debugging if it chooses to).
|
||||
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.
|
||||
4. 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.
|
||||
5. 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.
|
||||
6. After all tests finish, the runner sends a TestRunner.Completed message to dotnet test, which dotnet test sends as TestExecution.Completed to the adapter.
|
||||
7. Once the adapter is done, it sends dotnet test a TestSession.Terminate which will cause dotnet test to shutdown.
|
||||
|
||||
#### Test discovery
|
||||
|
||||
|
||||
1. 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.
|
||||
2. 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.
|
||||
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.
|
||||
4. Once the adapter is done, it sends dotnet test a TestSession.Terminate which will cause dotnet test to shutdown.
|
||||
157
Documentation/general/cli-ux-guidelines.md
Normal file
157
Documentation/general/cli-ux-guidelines.md
Normal file
|
|
@ -0,0 +1,157 @@
|
|||
.NET Core Command-Line Tools UX Guidelines
|
||||
-------------------------------------------
|
||||
|
||||
This document outlines the User Experience (UX) of the .NET Core command lline tools (CLI).These guideliens are intended for anyone that wants to add a new command to the CLI.
|
||||
|
||||
The guidelines presented in this document have been adopted to provide a clear and concise
|
||||
command line syntax that is easy to learn, remember and work with, and that has an added benefit
|
||||
of being familiar to people who have used other command-line interfaces as well as existing
|
||||
Visual Studio users.
|
||||
|
||||
## Naming the commands
|
||||
|
||||
In the .NET Core CLI, commands should be **verbs**. This rule was adopted
|
||||
because most of the commands do *something*.
|
||||
|
||||
Sub-commands are supported in the CLI, and they are usually nouns. A good
|
||||
example of this is the “dotnet add reference” command. If there is a need to add
|
||||
a subcommand, that subcommand should usually specialize what the parent command
|
||||
does.
|
||||
|
||||
## Create/Read/Update/Delete (CRUD) commands
|
||||
New CRUD commands should be named according to the following logic:
|
||||
|
||||
- Does the command work on data in the project (either properties or
|
||||
items)? If yes, then it should be added as a noun to the “dotnet
|
||||
add/list/remove/update”, e.g. “dotnet add foo”.
|
||||
|
||||
- Does the command work on the solution (SLN) file? If yes, then it should be
|
||||
added as a verb to the “dotnet sln” command.
|
||||
|
||||
- Does the command work on a completely new artifact (e.g. a new metadata file
|
||||
that is added in the future)? If yes, it should be created as a top level
|
||||
noun with all of the underlying operations defined as sub-commands.
|
||||
|
||||
- If the command adds a new artifact to the project, it should become an item
|
||||
template that is dropped with “dotnet new” command.
|
||||
|
||||
|
||||
If none of the above applies, the proposal should clearly outline why none of
|
||||
the above applies and suggest an alternative naming that will be decided on
|
||||
during the process described above.
|
||||
|
||||
If the command works on the project or solution, it must also accept an optional
|
||||
argument that specifies which project or solution to work on. The current
|
||||
convention is for that argument to follow the verb in the CRUD command. For
|
||||
example:
|
||||
|
||||
> dotnet add \<PROJECT\> reference \<REFERENCE\>
|
||||
|
||||
All the existing CRUD commands have this argument defined and it will be passed
|
||||
to the sub-command as part of the overall options. The sub-command is expected
|
||||
to consider this optional argument.
|
||||
|
||||
## Options
|
||||
CLI follows the [GNU convention](https://www.gnu.org/prep/standards/html_node/Command_002dLine-Interfaces.html) for options’ format, which is based on the POSIX
|
||||
standard. The summary is:
|
||||
|
||||
- Command can have both short and long options.
|
||||
|
||||
- The short format starts with a single dash (“-“), and has **exactly** one
|
||||
letter. The letter is usually the start letter of the longer form of the
|
||||
option, e.g. “-o” for “--output” or any of its words. This provides a good
|
||||
mnemonic.
|
||||
|
||||
- **Example:** “dotnet build -o path/to/where/to/put/output”
|
||||
|
||||
- The long format starts with double dashes (“--“) and can have one or more
|
||||
words. Multiple words are separated by a single dash (“-“).
|
||||
|
||||
- **Example:** “dotnet test --test-case-filter”
|
||||
|
||||
- The double dashes (“--“) on their own mark the **argument separator**.
|
||||
Anything after this option is passed verbatim to whatever the command starts
|
||||
as a sub-process.
|
||||
|
||||
- **Example:** “dotnet run -- --app-arg-1”
|
||||
|
||||
- Windows-style forward slash options (e.g. “/p”) are supported **only for
|
||||
MSBuild parameters.**
|
||||
|
||||
- PowerShell-style single dashes with a word (e.g. “-Filter”) are **not
|
||||
supported**.
|
||||
|
||||
- Help options are predefined as “-h \| --help” and those should be used.
|
||||
|
||||
There are common options in the CLI that are reserved for certain concepts. The
|
||||
table below outlines those common options. If a command needs to accept the same
|
||||
options, it should use these and it must not replace their semantics (e.g. use
|
||||
“--output” to mean something different or redefine what “-f” means for just that
|
||||
command).
|
||||
|
||||
| Long option | Short option | Description |
|
||||
|------------------|--------------|--------------------------------------------------------------|
|
||||
| \--framework | \-f | Specifies which framework (target) to use in the invocation. |
|
||||
| \--output | \-o | Specifies where the output of the command should be placed. |
|
||||
| \--runtime | \-r | Specifies the runtime ID (RID) to use in the invocation. |
|
||||
| \--configuration | \-c | Specifies the configuration to use in the invocation. |
|
||||
| \--verbosity | \-v | Specifies the verbosity level of the command. |
|
||||
| \--help | \-h | Shows the help for the command. |
|
||||
|
||||
One special area is interacting with MSBuild. If a command has the need to do
|
||||
that, there are two additional requirements with regards to options:
|
||||
|
||||
1. The commands need to be able to take “/p” parameters in addition to whatever
|
||||
other properties they require.
|
||||
|
||||
2. If the command invokes a predefined MSBuild target, it needs to block
|
||||
“/t:\<target\>” and “/target:\<target\>” options and throw an error that is
|
||||
pre-defined in the CLI.
|
||||
|
||||
It is important to note that commands that invoke user-specified targets
|
||||
should not be submitted to the CLI, since the CLI comes with “dotnet msbuild”
|
||||
command that does precisely that.
|
||||
|
||||
## Arguments
|
||||
Arguments can have any name that authors of the commands being added need. We do have predefined
|
||||
argument names for the SLN file and project file. They are defined in the CLI
|
||||
source code and should be used if the command has the need to use those two
|
||||
arguments.
|
||||
|
||||
## Help messages
|
||||
Help messages are automatically generated based on the arguments, options and
|
||||
command name. No other work should be required here apart from setting up the
|
||||
above mentioned and their descriptions.
|
||||
|
||||
## Output
|
||||
For commands that are invoking MSBuild, the output will be controlled by MSBuild
|
||||
itself.
|
||||
|
||||
In case of a long running operation, the command needs to provide a feedback
|
||||
mechanism to the user to help the user reason about whether the command has
|
||||
crashed or is just waiting for I/O. The feedback mechanism guidelines are below:
|
||||
|
||||
1. Feedback should not require fonts with special glyphs for display.
|
||||
2. Pure text is acceptable (e.g. `Running background process...`) as a feedback mechanism.
|
||||
3. Spinners that conform to rule \#1 above are also acceptable.
|
||||
|
||||
|
||||
### Verbosity
|
||||
If the command interacts with MSBuild, it is required that it can accept a
|
||||
“--verbosity \| -v” argument and pass it to MSBuild verbatim.
|
||||
|
||||
If the command’s verbosity levels cannot fit naturally in [MSBuild’s verbosity levels](https://docs.microsoft.com/en-us/visualstudio/msbuild/msbuild-command-line-reference) or the command does not interact with MSBuild but still has an option to set the verbosity, it
|
||||
is the job of the command to map them in the most appropriate way. This way, the
|
||||
verbosity levels will be uniform across all commands which brings consistency to
|
||||
the toolset.
|
||||
|
||||
#### Example
|
||||
As an example, let us consider a “dotnet configure” command. It doesn’t interact
|
||||
with MSBuild. I wish to have verbosity on it, but it really has only two levels:
|
||||
quiet (just successes or errors) and verbose (every operation) that I've defined for the command. To satisfy the
|
||||
above-mentioned requirement, in my command I would define the “--verbosity \|
|
||||
-v” option and would map the arguments in the following way:
|
||||
|
||||
- “Quiet” gets mapped naturally to “quiet”
|
||||
|
||||
- “Minimal”, “Normal” and “Diagnostic” get mapped into “verbose”
|
||||
62
Documentation/general/intro-to-cli.md
Normal file
62
Documentation/general/intro-to-cli.md
Normal file
|
|
@ -0,0 +1,62 @@
|
|||
Introduction to .NET Core CLI
|
||||
=============================
|
||||
|
||||
The .NET Core CLI is a simple, extensible and standalone set of tools for building, managing and otherwise operating on .NET projects. It will or already includes commands such as compilation, NuGet package management and launching a debugger session. It is intended to be fully featured, enabling extensive library and app development functionality appropriate at the command-line. It should provide everything you'd need to develop an app in an SSH session! It is also intended to be a fundamental building block for building finished experiences in tools such as Visual Studio.
|
||||
|
||||
Goals:
|
||||
|
||||
- Language agnostic - embrace "common language runtime".
|
||||
- Target agnostic - multi-targets.
|
||||
- Simple extensibility and layering - "you had one job!"
|
||||
- Cross-platform - support and personality.
|
||||
- Semantic user interface over [MSBuild](https://github.com/Microsoft/msbuild).
|
||||
|
||||
Experience
|
||||
==========
|
||||
|
||||
The [.NET Core command-line tools](https://github.com/dotnet/cli) present the "dotnet" tool as the entry-point tool. It provides higher-level commands, often using multiple tools together to complete a task. It's a convenience wrapper over the other tools, which can also be used directly. "dotnet" isn't magical at all, but a very simple aggregator of other tools.
|
||||
|
||||
You can get a sense of using the tools from the examples below.
|
||||
|
||||
**dotnet restore**
|
||||
|
||||
`dotnet restore` restores dependent package from a given NuGet feed (e.g. NuGet.org) for the project in scope.
|
||||
|
||||
**dotnet run**
|
||||
|
||||
`dotnet run` compiles and runs your app with one step.
|
||||
|
||||
**dotnet build**
|
||||
|
||||
`dotnet build` compiles your app or library as an IL binary.
|
||||
|
||||
Design
|
||||
======
|
||||
|
||||
There are a couple of moving pieces that you make up the general design of the .NET Core CLI:
|
||||
|
||||
* The `dotnet` driver
|
||||
* Specific commands that are part of the package
|
||||
|
||||
The `dotnet` driver is very simple and its primary role is to run commands and give users basic information about usage.
|
||||
|
||||
The way the `dotnet` driver finds the command it is instructed to run using `dotnet {command}` is via a convention; any executable that is placed in the PATH and is named `dotnet-{command}` will be available to the driver. For example, when you install the CLI toolchain there will be an executable called `dotnet-build` in your PATH; when you run `dotnet build`, the driver will run the `dotnet-build` executable. All of the arguments following the command are passed to the command being invoked. So, in the invocation of `dotnet build --native`, the `--native` switch will be passed to `dotnet-build` executable that will do some action based on it (in this case, produce a single native binary).
|
||||
|
||||
Adding a new command to the .NET Core CLI
|
||||
=========================================
|
||||
|
||||
If you want to contribute to the actual .NET Core CLI by adding a new command that you think would be useful, please refer to the [developer guide](developer-guide.md) in this directory. It contains all of the guidance on both the process as well as the infrastructure that you need to adhere to when adding a new command to the CLI toolchain.
|
||||
|
||||
After you familiarize yourself with the process of working with the source code in the repo, please consult the [CLI UX guidelines](cli-ux-guidelines.md) to get to know the user experience tenants the CLI has.
|
||||
|
||||
Adding a new command locally
|
||||
============================
|
||||
If you wish to extend the CLI, you can read more about supported extensibility models in the [official extensibility document](https://docs.microsoft.com/en-us/dotnet/articles/core/tools/extensibility)/.
|
||||
|
||||
Guidance on how to write a command
|
||||
==================================
|
||||
How you write a given command depends largely on whether you are trying to add it to the CLI project or want to add the command locally, that is on your machine or server.
|
||||
|
||||
For the former case, the [developer guide](developer-guide.md) has all of the details that you will need to get going.
|
||||
|
||||
If you are adding a command on your own machine(s), then there is really no special model to keep in mind. However, since your users will be using the local commands through the `dotnet` driver, we strongly suggest to keep to the principles outlined in the [CLI UX guidelines](cli-ux-guidelines.md) to have an unified user experience for your users.
|
||||
Binary file not shown.
|
Before Width: | Height: | Size: 14 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 20 KiB |
|
|
@ -1,100 +0,0 @@
|
|||
Intro to .NET Core CLI
|
||||
======================
|
||||
|
||||
The .NET Core CLI is a simple, extensible and standalone set of tools for building, managing and otherwise operating on .NET projects. It will or already includes commands such as compilation, NuGet package management and launching a debugger session. It is intended to be fully featured, enabling extensive library and app development functionality appropriate at the command-line. It should provide everything you'd need to develop an app in an SSH session! It is also intended to be a fundamental building block for building finished experiences in tools such as Visual Studio.
|
||||
|
||||
Goals:
|
||||
|
||||
- Language agnostic - embrace "common language runtime".
|
||||
- Target agnostic - multi-targets.
|
||||
- Runtime agnostic.
|
||||
- Simple extensibility and layering - "you had one job!"
|
||||
- Cross-platform - support and personality.
|
||||
- Outside-in philosophy - higher-level tools drive the CLI.
|
||||
|
||||
Historical Context - DNX
|
||||
========================
|
||||
|
||||
We've been using [DNX](http://blogs.msdn.com/b/dotnet/archive/2015/04/29/net-announcements-at-build-2015.aspx#dnx) for all .NET Core scenarios for nearly two years. It provides a lot of great experiences, but doesn't have great "pay for play" characteristics. DNX is a big leap from building the [CoreCLR](https://github.com/dotnet/coreclr) and [CoreFX](https://github.com/dotnet/corefx) repos and wanting to build an app with a simple environment. In fact, one of the open source contributors to CoreCLR said: "I can build CoreCLR, but I don't know how to build 'Hello World'." We cannot have that!
|
||||
|
||||
.NET Core includes three new components: a set of standalone command-line (CLI) tools, a shared framework and a set of runtime services. These components will replace DNX and are essentially DNX split in three parts.
|
||||
|
||||
The DNX services will be offered as a hosting option available to apps. You can opt to use a host that offers one or more of these services, like file change watching or NuGet package servicing. You can also opt to use a shared framework, to ease deployment of dependencies and for performance reasons. Some of this is still being designed and isn't yet implemented.
|
||||
|
||||
ASP.NET 5 will transition to the new tools for RC2. This is already in progress. There will be a smooth transition from DNX to these new .NET Core components.
|
||||
|
||||
Experience
|
||||
==========
|
||||
|
||||
The [CLI tools](https://github.com/dotnet/cli) present the "dotnet" tool as the entry-point tool. It provides higher-level commands, often using multiple tools together to complete a task. It's a convenience wrapper over the other tools, which can also be used directly. "dotnet" isn't magical at all, but a very simple aggregator of other tools.
|
||||
|
||||
You can get a sense of using the tools from the examples below.
|
||||
|
||||
**dotnet restore**
|
||||
|
||||
`dotnet restore` restores dependent package from a given NuGet feed (e.g. NuGet.org) for the project in scope.
|
||||
|
||||
**dotnet run**
|
||||
|
||||
`dotnet run` compiles and runs your app with one step. Same as `dnx run`.
|
||||
|
||||
**dotnet build**
|
||||
|
||||
`dotnet build --native` native compiles your app into a single executable file.
|
||||
|
||||
`dotnet build` compiles your app or library as an IL binary. In the case of an app, `build` generates runnable assets by copying an executable host to make the IL binary runable. The host relies on a shared framework for dependencies, including a runtime.
|
||||
|
||||
Design
|
||||
======
|
||||
|
||||
There are a couple of moving pieces that you make up the general design of the .NET Core CLI:
|
||||
|
||||
* The `dotnet` driver
|
||||
* Specific commands that are part of the package
|
||||
|
||||
The `dotnet` driver is very simple and its primary role is to run commands and give users basic information about usage.
|
||||
|
||||
The way the `dotnet` driver finds the command it is instructed to run using `dotnet {command}` is via a convention; any executable that is placed in the PATH and is named `dotnet-{command}` will be available to the driver. For example, when you install the CLI toolchain there will be an executable called `dotnet-build` in your PATH; when you run `dotnet build`, the driver will run the `dotnet-build` executable. All of the arguments following the command are passed to the command being invoked. So, in the invocation of `dotnet build --native`, the `--native` switch will be passed to `dotnet-build` executable that will do some action based on it (in this case, produce a single native binary).
|
||||
|
||||
This is also the basics of the current extensibility model of the toolchain. Any executable found in the PATH named in this way, that is as `dotnet-{command}`, will be invoked by the `dotnet` driver.
|
||||
|
||||
There are some principles that we are using when adding new commands:
|
||||
|
||||
* Each command is represented by a verb (`run`, `build`, `publish`, `restore` etc.)
|
||||
* We support the short and the long form of switches for most commands
|
||||
* The switches have the same format on all supported platforms (so, no /-style switches on Windows for example)
|
||||
* Each command has a help that can be viewed by running `dotnet [command] --help`
|
||||
|
||||
Adding a new command to the .NET Core CLI
|
||||
=========================================
|
||||
|
||||
If you want to contribute to the actual .NET Core CLI by adding a new command that you think would be useful, please refer to the [developer guide](developer-guide.md) in this directory. It contains all of the guidance on both the process as well as the infrastructure that you need to adhere to when adding a new command to the CLI toolchain.
|
||||
|
||||
Adding a new command locally
|
||||
============================
|
||||
Given the extensibility model described above, it is very easy to add a command that can be invoked with the `dotnet` driver. Just add any executable in a PATH and name it as per the instructions above.
|
||||
|
||||
As an example, let's say we want to add a local command that will mimic `dotnet clean`. By convention, `dotnet build` will drop binaries in two directories `./bin` and `./obj`. A clean command thus will need to delete these two directories. A trivial example, but it should work.
|
||||
|
||||
On *nix OS-es, we will write a very simple shell script to help us with this:
|
||||
```shell
|
||||
#!/bin/bash
|
||||
|
||||
rm -rf bin/ obj/
|
||||
```
|
||||
|
||||
We then do the following to make it be a command in the CLI toolchain
|
||||
|
||||
* Name it as `dotnet-clean`
|
||||
* Set the executable bit on: `chmod +X dotnet-clean`
|
||||
* Copy it over somewhere in the $PATH: `sudo cp dotnet-clean /usr/local/bin`
|
||||
|
||||
After this, the command ready to be invoked via the `dotnet` driver.
|
||||
|
||||
Guidances on how to write a command
|
||||
===================================
|
||||
How you write a given command depends largely on whether you are trying to add it to the CLI project or want to add the command locally, i.e. on your machine or server.
|
||||
|
||||
For the former case, the [developer guide](developer-guide.md) has all of the details that you will need to get going.
|
||||
|
||||
If you are adding a command on your own machine(s), then there is really no special model to keep in mind. However, since your users will be using the local commands through the `dotnet` driver, we strongly suggest to keep to the principles outlined above in the [design section](#design) to have an unified user experience for your users.
|
||||
|
|
@ -1,4 +0,0 @@
|
|||
Known issues & workarounds
|
||||
==========================
|
||||
|
||||
This document now lives in the [known issues document](https://github.com/dotnet/core/blob/master/cli/known-issues.md) in the dotnet/core repository.
|
||||
|
|
@ -126,8 +126,8 @@ Below table shows the mapping between the channels, branches and feeds for the D
|
|||
| Channel | Branch | Debian feed | Debian package name | NuGet version | NuGet feed |
|
||||
|------------ |----------- |------------- |--------------------- |--------------- |--------------------------------------- |
|
||||
| Future | master | Development | dotnet-future | 1.0.0-dev-* | https://dotnet.myget.org/f/dotnet-cli |
|
||||
| Preview | rel/<ver> | Development | dotnet | 1.0.0-beta-* | https://dotnet.myget.org/f/dotnet-cli |
|
||||
| Production | production/<ver> | Production | dotnet | 1.0.0 | https://api.nuget.org/v3/index.json |
|
||||
| Preview | rel/<ver> | Development | dotnet-dev-<version> | 1.0.0-beta-* | https://dotnet.myget.org/f/dotnet-cli |
|
||||
| Production | rel/<ver> | Production | dotnet-dev-<version> | 1.0.0 | https://api.nuget.org/v3/index.json |
|
||||
|
||||
|
||||
## Funnels and discovery mechanisms for CLI bits
|
||||
|
|
@ -203,20 +203,29 @@ The features the script needs to support/have are:
|
|||
* Support specifying whether the debug package needs to be downloaded
|
||||
* Automatically add the install to $PATH unless --no-path/-NoPath is present
|
||||
|
||||
The installation script exists in this repo under `scripts/obtain` path. However, for most users it is reccomended to use the stable version that is hosted on [.NET Core main website](https://dot.net). The direct path to the scripts are:
|
||||
|
||||
* https://dot.net/v1/dotnet-install.sh (bash, UNIX)
|
||||
* https://dot.net/v1/dotnet-install.ps1 (powershell, Windows)
|
||||
|
||||
|
||||
#### Installation script features
|
||||
The following arguments are needed for the installation script:
|
||||
|
||||
| dotnet-install.sh arg (Linux, OSX) | dotnet-install.ps1 arg (Windows) | Defaults | Description |
|
||||
|-------------------------------------- |------------------------------------ |----------------------- |----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| --channel | -Channel | "preview" | Which channel (i.e. "Future", "preview", "production", "release/1.1.0") to install from. |
|
||||
| --version | -Version | global.json or Latest | Which version of CLI to install; you need to specify the version as 3-part version (i.e. 1.0.0-13232). If omitted, it will default to the first global.json that contains the sdkVersion property; if that is not present it will use Latest. |
|
||||
| --install-dir | -InstallDir | .dotnet | Path to where to install the CLI bundle. The directory is created if it doesn't exist. On Linux/OSX this directory is created in the user home directory (`$HOME`). On Windows, this directory is created in `%LocalAppData%`. |
|
||||
| --debug | -Debug | false | Whether to use the "fat" packages that contain debugging symbols or not. |
|
||||
| --no-path | -NoPath | false | Do not export the installdir to the path for the current session. This makes CLI tools available immediately after install. |
|
||||
| --shared-runtime | -SharedRuntime | false | Install just the shared runtime bits, not the entire SDK. |
|
||||
| dotnet-install.sh arg (Linux, OSX) | dotnet-install.ps1 arg (Windows) | Defaults | Description |
|
||||
|------------------------------------|----------------------------------|-----------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|
||||
| --channel | -Channel | "production" | Which channel (i.e. "Future", "preview", "production", "release/1.1.0") to install from. |
|
||||
| --version | -Version | Latest | Which version of CLI to install; you need to specify the version as 3-part version (i.e. 1.0.0-13232). If omitted, it will default to Latest for that channel. |
|
||||
| --install-dir | -InstallDir | .dotnet | Path to where to install the CLI bundle. The directory is created if it doesn't exist. On Linux/OSX this directory is created in the user home directory (`$HOME`). On Windows, this directory is created in `%LocalAppData%`. |
|
||||
| --debug-symbols | -DebugSymbols | false | Whether to use the "fat" packages that contain debugging symbols or not. |
|
||||
| --no-path | -NoPath | false | Do not export the installdir to the path for the current session. This makes CLI tools available immediately after install. |
|
||||
| --shared-runtime | -SharedRuntime | false | Install just the shared runtime bits, not the entire SDK. |
|
||||
| --architecture | -Architecture | Current OS (`<auto>`) | Architecture to install. The possible values are `<auto>`, `x64` and `x86`. |
|
||||
| --dry-run | -DryRun | false | If set, it will not perform the installation but will show, on standard output, what the invocation of the script will do with the options selected. |
|
||||
| --verbose | -Verbose | false | Display diagnostic information. |
|
||||
| N/A | -ProxyAddress | "" | If set, the installer will use the specified proxy server for all of its invocations. |
|
||||
|
||||
Note: Powershell arg naming convention is supported on Windows and non-Windows platforms. Non-Windows platforms do additionally support convention specific to their platform.
|
||||
> Note: Powershell arg naming convention is supported on Windows and non-Windows platforms. Non-Windows platforms do additionally support convention specific to their platform.
|
||||
|
||||
##### Install the 1.1.0 of the shared runtime
|
||||
|
||||
|
|
@ -1,4 +0,0 @@
|
|||
Supported OS Matrix for CLI
|
||||
===========================
|
||||
|
||||
The supported matrix now lives in the [roadmap document](https://github.com/dotnet/core/blob/master/roadmap.md) in the dotnet/core repository.
|
||||
20
README.md
20
README.md
|
|
@ -4,22 +4,12 @@
|
|||
|
||||
This repo contains the source code for cross-platform [.NET Core](http://github.com/dotnet/core) command line toolchain. It contains the implementation of each command, the native packages for various supported platforms as well as documentation.
|
||||
|
||||
RC 4 release - MSBuild based tools
|
||||
---------------------------------------
|
||||
As was outlined in the ["Changes to project.json" blog post](https://blogs.msdn.microsoft.com/dotnet/2016/05/23/changes-to-project-json/), we have started work to move away from project.json to csproj and MSBuild. All the new `latest` releases from this repo (from `rel/1.0.0` branch) are MSBuild-enabled tools.
|
||||
Looking for V1 of the .NET Core tooling?
|
||||
----------------------------------------
|
||||
If you are looking for the v1.0.1 release of the .NET Core tools (CLI, MSBuild and the new csproj), head over to https://dot.net/core and download!
|
||||
|
||||
The current official release of the csproj-enabled CLI tools is **CLI RC 4**.
|
||||
|
||||
There are a couple of things to keep in mind:
|
||||
|
||||
* RC 4 CLI bits are still **in development** so some rough edges are to be expected.
|
||||
* RC 4 bits **do not support** project.json so you will have to either keep Preview 2 tools around or migrate your project or add a global.json file to your project to target preview2. You can find more information on this using the [project.json to csproj instructions](https://github.com/dotnet/cli/blob/rel/1.0.0/Documentation/ProjectJsonToCSProj.md).
|
||||
* RC 4 refers to the **CLI tools only** and does not cover Visual Studio, VS Code or Visual Studio for Mac.
|
||||
* We welcome any and all issues that relate to MSBuild-based tools, so feel free to try them out and leave comments and file any bugs/problems.
|
||||
|
||||
### Download links
|
||||
* Instructions and links for download: [RC3 download links](https://github.com/dotnet/core/blob/master/release-notes/rc3-download.md).
|
||||
* Directory for future Preview release notes: [.NET Core release notes](https://github.com/dotnet/core/tree/master/release-notes).
|
||||
> **Note:** the master branch of the CLI repo is based on the upcoming v2 of .NET Core and is considered pre-release. For production-level usage, please use the
|
||||
> v1 of the tools.
|
||||
|
||||
Found an issue?
|
||||
---------------
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue