From 4686202f2eb055f1039d3b9a21646567cd597f0d Mon Sep 17 00:00:00 2001 From: Zlatko Knezevic Date: Fri, 27 Nov 2015 09:02:31 -0800 Subject: [PATCH 1/2] Additions to the intro document --- Documentation/intro-to-cli.md | 36 ++++++++++++++++++++++++++++++++++- README.md | 8 +++++++- 2 files changed, 42 insertions(+), 2 deletions(-) diff --git a/Documentation/intro-to-cli.md b/Documentation/intro-to-cli.md index 9a0fda218..c92b68755 100644 --- a/Documentation/intro-to-cli.md +++ b/Documentation/intro-to-cli.md @@ -47,7 +47,41 @@ You can get a sense of using the tools from the examples below. Design ====== -More content here. +There are 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 the commands and give users basic information about usage. + +The way `dotnet` driver finds the command it is instructed to run using `dotnet {command}` is via convention; any exectuable 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 a command called `dotnet-compile` in your PATH; when you run `dotnet compile`, the driver will run `dotnet-compile`. All of the arguments are passed to the command being invoked. + +This is also the basics of the current extensibility model of the toolchain. Any executable found in the PATH named in this way 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`, `compile`, `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 + +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 is provided in t + +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 appropriatelly. + +Guidances on how to write a command +=================================== +How do you write a given command depends largely on whether you are trying to add it to the CLI project or are writing an addition outside of it. + +In the first case, the [developer guide](developer-guide.md) has all of the details on the styles and the infrastructure that is provided and that you can (and need) to use to implement new commands. + +If you are adding a command on your own machine(s), then any model of doing things is available to you. However, since your users will be using the local commands through `dotnet` driver, it would be preferable to keep the style consistent to the one described in the deisgn section above. + diff --git a/README.md b/README.md index 8907f6d1d..876bbea2c 100644 --- a/README.md +++ b/README.md @@ -67,10 +67,16 @@ On Mac OSX, we currently support the C++ Codegenerator (as shown below) and supp dotnet compile --native --cpp -This will drop a native single binary in `./bin/[configuration]/[framework]/native/[binary name]` that you can run. +This will drop a native single binary in `./bin/[configuration]/[framework]/native/[binary name]` that you can run. For more details, please refer to the [documentation](https://github.com/dotnet/corert/tree/master/Documentation). +Building from source +-------------------- + +If you are building from source, take note that the build depends on NuGet packages hosted on Myget, so if it is down, the build may fail. If that happens, you can always see the [Myget status page](http://status.myget.org/) for more info. + + Questions & Comments -------------------- From 1a893f34811b8dc4881ad1c601cc4e7ec241c8b5 Mon Sep 17 00:00:00 2001 From: Zlatko Knezevic Date: Sun, 29 Nov 2015 00:01:04 -0800 Subject: [PATCH 2/2] PR feedback --- Documentation/intro-to-cli.md | 37 +++++++++++++++++++++++++---------- 1 file changed, 27 insertions(+), 10 deletions(-) diff --git a/Documentation/intro-to-cli.md b/Documentation/intro-to-cli.md index c92b68755..4e2be836e 100644 --- a/Documentation/intro-to-cli.md +++ b/Documentation/intro-to-cli.md @@ -47,40 +47,57 @@ You can get a sense of using the tools from the examples below. Design ====== -There are couple of moving pieces that you make up the general design of the .NET Core CLI: +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 the commands and give users basic information about usage. +The `dotnet` driver is very simple and its primary role is to run commands and give users basic information about usage. -The way `dotnet` driver finds the command it is instructed to run using `dotnet {command}` is via convention; any exectuable 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 a command called `dotnet-compile` in your PATH; when you run `dotnet compile`, the driver will run `dotnet-compile`. All of the arguments are passed to the command being invoked. +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-compile` in your PATH; when you run `dotnet compile`, the driver will run the `dotnet-compile` executable. All of the arguments following the command are passed to the command being invoked. So, in the invocation of `dotnet compile --native`, the `--native` switch will be passed to `dotnet-compile` 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 will be invoked by the `dotnet` driver. +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`, `compile`, `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 +* 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 is provided in t +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 appropriatelly. +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 compile` 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. + +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 do you write a given command depends largely on whether you are trying to add it to the CLI project or are writing an addition outside of it. +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. -In the first case, the [developer guide](developer-guide.md) has all of the details on the styles and the infrastructure that is provided and that you can (and need) to use to implement new commands. +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 any model of doing things is available to you. However, since your users will be using the local commands through `dotnet` driver, it would be preferable to keep the style consistent to the one described in the deisgn section above. +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.