Merge pull request #1397 from revlucio/rel/1.0.0
Fixed spelling mistakes in documentation
This commit is contained in:
Zlatko Knezevic
commit
f81ba05a7c
6 changed files with 23 additions and 28 deletions
|
|
@ -1,7 +1,7 @@
|
|||
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).
|
||||
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.
|
||||
|
||||
|
|
@ -9,7 +9,7 @@ The following represent warning codes printed by CLI when the project structure
|
|||
|
||||
- __[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.
|
||||
- __[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.
|
||||
|
|
|
|||
|
|
@ -41,7 +41,7 @@ In order to build .NET Command Line Interface, you need the following installed
|
|||
|
||||
The dotnet CLI considers any executable on the path named `dotnet-{commandName}` to be a command it can call out to. `dotnet publish`, for example, is added to the path as an executable called `dotnet-publish`. To add a new command we must create the executable and then add it to the distribution packages for installation.
|
||||
|
||||
0. Create an issue on https://github.com/dotnet/cli and get consensus on the need for and behavior of the command.
|
||||
0. Create an issue on https://github.com/dotnet/cli and get consensus on the need for and behaviour of the command.
|
||||
1. Add a new project for the command.
|
||||
2. Add the project to Microsoft.DotNet.Cli.sln
|
||||
3. Create a Readme.md for the command.
|
||||
|
|
@ -51,7 +51,7 @@ The dotnet CLI considers any executable on the path named `dotnet-{commandName}`
|
|||
#### Add a new command project
|
||||
Start by copying an existing command, like /src/dotnet-new.
|
||||
Update the Name property in project.json as well, and use the `dotnet-{command}` syntax here.
|
||||
Make sure to use the System.CommandLine parser so behavior is consistant across commands.
|
||||
Make sure to use the System.CommandLine parser so behaviour is consistent across commands.
|
||||
|
||||
#### Add a Readme.md
|
||||
Each command's project root should contain a manpage-style Readme.md that describes the usage of the command. See other commands for reference.
|
||||
|
|
@ -68,4 +68,4 @@ Each command's project root should contain a manpage-style Readme.md that descri
|
|||
- Update the `$Projects` property in `packaging/osx/scripts/postinstall`
|
||||
|
||||
#### Things to Know
|
||||
- Any added commands are usually invoked through `dotnet {command}`. As a result of this, stdout and stderr are redirected through the driver (`dotnet`) and buffered by line. As a result of this, child commands should use Console.WriteLine in any cases where they expect output to be written immediately. Any uses of Console.Write should be followed by Console.WriteLine to ensure the output is written.
|
||||
- Any added commands are usually invoked through `dotnet {command}`. As a result of this, stdout and stderr are redirected through the driver (`dotnet`) and buffered by line. As a result of this, child commands should use Console.WriteLine in any cases where they expect output to be written immediately. Any uses of Console.Write should be followed by Console.WriteLine to ensure the output is written.
|
||||
|
|
|
|||
|
|
@ -10,7 +10,7 @@ Goals:
|
|||
- Runtime agnostic.
|
||||
- Simple extensibility and layering - "you had one job!"
|
||||
- Cross-platform - support and personality.
|
||||
- Outside-in philosphy - higher-level tools drive the CLI.
|
||||
- Outside-in philosophy - higher-level tools drive the CLI.
|
||||
|
||||
Historical Context - DNX
|
||||
========================
|
||||
|
|
@ -42,7 +42,7 @@ You can get a sense of using the tools from the examples below.
|
|||
|
||||
`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 runable assets by copying an executable host to make the IL binary runable. The host relies on a shared framework for dependencies, including a runtime.
|
||||
`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
|
||||
======
|
||||
|
|
@ -74,7 +74,7 @@ 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 mimick `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 directores. A trivial example, but it should work.
|
||||
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
|
||||
|
|
@ -97,9 +97,4 @@ How you write a given command depends largely on whether you are trying to add i
|
|||
|
||||
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 outlned above in the [design section](#design) to have an unified user experience for your users.
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
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.
|
||||
|
|
|
|||
|
|
@ -27,10 +27,10 @@ These scenarios are focused on console applications and libraries.
|
|||
All of the scenarios below assume that the CLI tools have been acquired in some way. The acquisition of the CLI tools is explained in detail in a [separate specification](cli-install-experience.md). This document only contains a very short summary of that document.
|
||||
|
||||
There are two main ways to acquire the CLI toolset:
|
||||
1. Using targeted platform's native installers - this approach is used by developers who want to get stable bits on their development machines and don't mind the system-wide installation and need for elevated priviliges.
|
||||
1. Using targeted platform's native installers - this approach is used by developers who want to get stable bits on their development machines and don't mind the system-wide installation and need for elevated privileges.
|
||||
2. Using a local install (a zip/tarball) - this approach is used by developers who want to enable their build servers to use CLI toolset or who want to have multiple, side-by-side installs.
|
||||
|
||||
The bits that are gotten are same modulo potential differences in stability of the bits, however, the smoothness of the experience is not. With native installers the installers themselves do as much as possible to set up a working environment (installing dependencies where possible, setting needed envioronment variables etc.). Local installs require all of the work to be done by developers after dropping bits on the machine.
|
||||
The bits that are gotten are same modulo potential differences in stability of the bits, however, the smoothness of the experience is not. With native installers the installers themselves do as much as possible to set up a working environment (installing dependencies where possible, setting needed environment variables etc.). Local installs require all of the work to be done by developers after dropping bits on the machine.
|
||||
|
||||
The below scenarios must work regardless of the way used to acquire the tools.
|
||||
|
||||
|
|
@ -38,7 +38,7 @@ The below scenarios must work regardless of the way used to acquire the tools.
|
|||
|
||||
# Starting a new console application
|
||||
|
||||
## Narative
|
||||
## Narrative
|
||||
The developer would like to kick the tires on .NET Core by writing a console application. She would like to use the new .NET Core CLI tooling to help her get started, manage dependencies and quickly test out the console application by running it from source. She would then like to try building the code and running it using the shared host that is installed with the CLI toolset.
|
||||
|
||||
## Steps
|
||||
|
|
@ -110,7 +110,7 @@ Hello World!
|
|||
# Starting a new class library
|
||||
|
||||
## Narrative
|
||||
Once started, the developer wants to also include a class library in order to have a place to share common code. She wants to use the CLI toolset to boostrap this effort as well.
|
||||
Once started, the developer wants to also include a class library in order to have a place to share common code. She wants to use the CLI toolset to bootstrap this effort as well.
|
||||
|
||||
## Steps
|
||||
|
||||
|
|
@ -170,7 +170,7 @@ Creating a "mylib" class library in "mylib"
|
|||
# Adding 3rd party dependencies to the projects
|
||||
|
||||
## Narrative
|
||||
Working towards a complete application, the developer realizes she needs to add good JSON parsing support. Searching across the internet, she finds JSON.NET to be the most reccomended choice. She now uses the CLI tooling to install a dependency off of NuGet.
|
||||
Working towards a complete application, the developer realizes she needs to add good JSON parsing support. Searching across the internet, she finds JSON.NET to be the most recommended choice. She now uses the CLI tooling to install a dependency off of NuGet.
|
||||
|
||||
>**NOTE:** the shape of the commands used in this scenario is still being discussed.
|
||||
|
||||
|
|
@ -308,9 +308,9 @@ Coding away on the application has proven worthwhile and our developer wants to
|
|||
# Publishing a self-contained console application for all platforms
|
||||
|
||||
## Narrative
|
||||
After getting feedback from her collegaue developer, our developer decides to test on another machine. However, this machine doesn't have the shared host installed and she cannot get it installed. Luckily, she realizes that .NET Core has support for self-contained applications
|
||||
After getting feedback from her colleague developer, our developer decides to test on another machine. However, this machine doesn't have the shared host installed and she cannot get it installed. Luckily, she realizes that .NET Core has support for self-contained applications
|
||||
|
||||
**NOTE**: some of the behaviors in this scenario are still being discussed with the relevant stakeholders.
|
||||
**NOTE**: some of the behaviours in this scenario are still being discussed with the relevant stakeholders.
|
||||
|
||||
## Steps
|
||||
|
||||
|
|
@ -327,7 +327,7 @@ After getting feedback from her collegaue developer, our developer decides to te
|
|||
}
|
||||
```
|
||||
|
||||
2. Restore the project's dependencies again to ensure the platform-specific depdendencies for the specified runtimes are acquired:
|
||||
2. Restore the project's dependencies again to ensure the platform-specific dependencies for the specified runtimes are acquired:
|
||||
```
|
||||
/myapp> dotnet restore
|
||||
|
||||
|
|
@ -382,7 +382,7 @@ After getting feedback from her collegaue developer, our developer decides to te
|
|||
|
||||
# Packaging a class library
|
||||
|
||||
## Narative
|
||||
## Narrative
|
||||
The developer wants to take the library she built and package it up as a NuGet package in order to share it with the rest of the ecosystem. Again, she would like to use the CLI toolset to achieve this. Since she wants to be sure that all her code is in a pristine condition, she will also build it one more time, run tests and then package it.
|
||||
|
||||
## Steps
|
||||
|
|
@ -405,7 +405,7 @@ The developer wants to take the library she built and package it up as a NuGet p
|
|||
2. Switch to the test project and run unit tests
|
||||
|
||||
```console
|
||||
[switch to the directory containg unit tests]
|
||||
[switch to the directory containing unit tests]
|
||||
/mytests> dotnet test
|
||||
|
||||
[info about tests flies around]
|
||||
|
|
|
|||
|
|
@ -41,8 +41,8 @@ Any file with the suffix `.dll` in the same folder as the managed application be
|
|||
|
||||
Only assemblies listed in the dependencies file can be resolved from a package cache. To resolve those assemblies, two environment variables are used:
|
||||
|
||||
* `DOTNET_PACKAGES` - The primary package cache. If not set, defaults to `$HOME/.nuget/packages` on Unix or `%LOCALAPPDATA%\NuGet\Packages` (TBD) on Windows. **NOTE**: Currently the host uses different folders as we are still coordinating with NuGet to get the directories right (there are compat considerations). Currently we always use `$HOME/.dnx/packages`(Unix)/`%USERPROFILE%\.dnx\packages`(Win).
|
||||
* `DOTNET_PACKAGES_CACHE` - The secondary cache. This is used by shared hosters (such as Azure) to provide a cache of pre-downloaded common packages on a faster disk. If not set, it is not used.
|
||||
* `DOTNET_PACKAGES` - The primary package cache. If not set, defaults to `$HOME/.nuget/packages` on Unix or `%LOCALAPPDATA%\NuGet\Packages` (TBD) on Windows. **NOTE**: Currently the host uses different folders as we are still coordinating with NuGet to get the directories right (there are compatability considerations). Currently we always use `$HOME/.dnx/packages`(Unix)/`%USERPROFILE%\.dnx\packages`(Win).
|
||||
* `DOTNET_PACKAGES_CACHE` - The secondary cache. This is used by shared hosts (such as Azure) to provide a cache of pre-downloaded common packages on a faster disk. If not set, it is not used.
|
||||
|
||||
Given the Package ID, Package Version, Package Hash and Asset Relative Path provided in the runtime configuration file, **and the assembly is not serviced** (see the full resolution algorithm below) resolution proceeds as follows (Unix-style paths will be used for convenience but these variables and paths all apply to Windows as well):
|
||||
|
||||
|
|
@ -56,7 +56,7 @@ During host start-up, the host identifies if a runtime configuration file is pre
|
|||
|
||||
A runtime configuration file is **not** required to successfully launch an application, but without it, all the dependent assemblies must be located within the same folder as the application. Also, since servicing is performed on the basis of packages, an application without a runtime configuration file file cannot use the servicing index to override the location of assemblies.
|
||||
|
||||
The host looks for the `.deps` file in the Application Base with the file name `[AssemblyName].deps`. The path to the deps file can be overriden by specifying `--depsfile:{path to deps file}` as the first parameter to the application.
|
||||
The host looks for the `.deps` file in the Application Base with the file name `[AssemblyName].deps`. The path to the deps file can be overridden by specifying `--depsfile:{path to deps file}` as the first parameter to the application.
|
||||
|
||||
Given the set of assembly names, the host performs the following resolution. In some steps, the Package ID/Version/Relative Path data is required. This is only available if the assembly was listed in the deps file. If the assembly comes from the app-local folder, these resolution steps are skipped.
|
||||
|
||||
|
|
|
|||
|
|
@ -194,7 +194,7 @@ Only dependencies with a `type` value of `package` will have asset lists (`compi
|
|||
|
||||
### `libraries` Section (`.deps.json`)
|
||||
|
||||
This section contains a union of all the dependencies found in the various targets, and contains common metadata for them. Specifically, it contains the `type`, as well as a boolean indicating if the library can be serviced (`servicable`, only for `package`-typed libraries) and a SHA-512 hash of the package file (`sha512`, only for `package`-typed libraries.
|
||||
This section contains a union of all the dependencies found in the various targets, and contains common metadata for them. Specifically, it contains the `type`, as well as a boolean indicating if the library can be serviced (`serviceable`, only for `package`-typed libraries) and a SHA-512 hash of the package file (`sha512`, only for `package`-typed libraries.
|
||||
|
||||
**Open Question**: We could probably exclude projects from this set in order to reduce duplication. The main reason this is a separate section is because that's how the lock file is formatted and we want to try an keep this format the same if possible.
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue