Merge pull request #197 from blackdwarf/master

Add MD files per command and documentation directory

README.md

@@ -1,5 +1,7 @@
 # .NET Command Line Interface
 
+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. 
+
 Build Status
 ------------
 
@@ -16,28 +18,12 @@ Installers
 |**Installers**|[Download Debian Package](https://dotnetcli.blob.core.windows.net/dotnet/dev/Installers/Latest/dotnet-linux-x64.latest.deb)|[Download Msi](https://dotnetcli.blob.core.windows.net/dotnet/dev/Installers/Latest/dotnet-win-x64.latest.msi)|[Download Pkg](https://dotnetcli.blob.core.windows.net/dotnet/dev/Installers/Latest/dotnet-osx-x64.latest.pkg) |
 |**Binaries**|[Download tar file](https://dotnetcli.blob.core.windows.net/dotnet/dev/Binaries/Latest/dotnet-linux-x64.latest.tar.gz)|[Download zip file](https://dotnetcli.blob.core.windows.net/dotnet/dev/Binaries/Latest/dotnet-win-x64.latest.zip)|[Download tar file](https://dotnetcli.blob.core.windows.net/dotnet/dev/Binaries/Latest/dotnet-osx-x64.latest.tar.gz) |
 
-## Prerequisites
+Docker
+------
 
-In order to build dotnet-cli, you need the following installed on you machine
+You can also use our Docker base images found on http://github.com/dotnet/dotnet-docker to set up your dev or testing environment for usage.  
 
-### For Windows
+Questions & Comments
+--------------------
 
-1. Visual Studio 2015 with Web Development Tools
-  * Beta8 is available here and should work: http://www.microsoft.com/en-us/download/details.aspx?id=49442
-    * Install `WebToolsExtensionsVS14.msi` and `DotNetVersionManager-x64.msi`
-2. CMake (available from https://cmake.org/) is required to build the native host `corehost`. Make sure to add it to the PATH.
-
-## Building/Running
-
-1. Run `build.cmd` or `build.sh` from the root
-2. Use `artifacts/{os}-{arch}/stage2/dotnet` to try out the `dotnet` command. You can also add `artifacts/{os}-{arch}/stage2` to the PATH if you want to run `dotnet` from anywhere.
-
-
-## Visual Studio Code
-
-* You can also use Visual Studo code https://code.visualstudio.com/
-
-## A simple test
-
-1. `cd test\TestApp`
-2. `dotnet run`
+For any and all feedback, please use the Issues on this repository. 

documentation/Contributing.md

@@ -0,0 +1,9 @@
+Contributing to .NET Command Line Interface
+===========================================
+
+The .NET Core  team maintains several guidelines for contributing to the .NET Core and associated repos, which are provided [on this link](https://github.com/dotnet/coreclr/blob/master/Documentation/project-docs/contributing.md). Many of these are straightforward, while others may seem subjective. A .NET Core team member will be happy to explain why a guideline is defined as it is.
+
+Developers
+==========
+
+See the [README.md](readme.md) file in this directory for more details on how to get started developing on the .NET Command Line Interface. 

documentation/README.md

@@ -0,0 +1,50 @@
+
+# Start developing on .NET Command Line Interface
+## Prerequisites
+
+In order to build .NET Command Line Interface, you need the following installed on you machine.
+
+### For Windows
+
+1. Visual Studio 2015 with Web Development Tools
+  * Beta8 is available here and should work: http://www.microsoft.com/en-us/download/details.aspx?id=49442
+    * Install `WebToolsExtensionsVS14.msi` and `DotNetVersionManager-x64.msi`
+2. CMake (available from https://cmake.org/) is required to build the native host `corehost`. Make sure to add it to the PATH.
+
+### For Linux
+
+You need CMake in your path. 
+
+### For OS X
+
+[TODO]
+
+## Building/Running
+
+1. Run `build.cmd` or `build.sh` from the root depending on your OS.
+2. Use `artifacts/{os}-{arch}/stage2/dotnet` to try out the `dotnet` command. You can also add `artifacts/{os}-{arch}/stage2` to the PATH if you want to run `dotnet` from anywhere.
+
+
+# Tools 
+
+## Visual Studio
+
+* You can use Visual Studio 2015 to work on these bits. 
+
+## Visual Studio Code
+
+* You can also use Visual Studo code https://code.visualstudio.com/ to contribute to this project. 
+
+## A simple test
+
+1. `cd test\TestApp`
+2. `dotnet run`
+
+## Contributing to the repo
+
+Once you are set up with requirements and you want to start, please review our [contribution guidelines](Contributing.md) to get up to speed with the process. 
+
+
+# I just want to use this toolchain
+
+If you just want to use the .NET Command Line Interface, your best bet would be to use the installers provided on the [main README file](../README.md). You can also follow the above guide for building from source to get the lastest (bleeding edge) bits. 

src/Microsoft.DotNet.Cli/README.md

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

src/Microsoft.DotNet.Tools.Compiler.Csc/README.md

@@ -0,0 +1,49 @@
+dotnet-compile
+===========
+
+**NAME** 
+dotnet-compile -- Compiles source files to a binary format and saves to a target file.
+
+**SYNOPSIS**
+dotnet compile [options]
+
+**DESCRIPTION**
+The compile command compiles source files to a binary file, either IL byte code or native machine code, depending on the options provided. The default option is compilation to IL byte code, but may change to native compilation as that toolchain matures.
+
+The default IL [--il] output is a PE32 exe [exe], with the default extension of ".exe" on all OSes. The exe must include a static main entry point, or it is an error. The dll [dll] output option has the default extension of ".dll".
+
+The IL exe output type needs a runtime host to execute. The IL exe output type also copies a host to the output directory. The host is renamed to the name of the exe. For example, if the file is intended to be "foo" (`-o foo`), then the host will be called foo, with the appropriate default native file extension fo the OS (see the native file extensions, below). The PE32 exe will be called "[filename]"-app.exe". In this case, it would be called "foo-app.exe".
+
+The default native [--native] output is a native exe that conforms to the architecture of the underlying operating system (i.e. running on 64-bit OS will produce a native 64-bit exe). This can be overriden via the --arch switch and specifying the wanted architecture. The executable has a default extension of "" on Linux and OS X and ".exe" on Windows. The source must include a static void main entry point, or it is an error, unless otherwise specified in the project.json. The dynamic library [dylib] output option has the default extension of ".so" on Linux/UNIX, ".dynlib" on OS X and ".dll" on Windows. The static library [staticlib] option has the default extension of ".a" on Linux, UNIX and OS X and ".lib" on Windows.
+
+This command relies on the following artifacts: source files, project.json project file, restore.json temporary file and restored NuGet dependencies. In the case that an app depends on only the .NET Standard Library, then the project.json and restore.json file can be inferred and no additional NuGet dependencies are required. Other cases where these files are not provided or they do not match (more on that later) are error states.
+
+The project.json file represents and describes the project. It can contain several setting, which are described in the [Build](https://docs.asp.net/en/latest/dnx/projects.html#building). The most important information in the project.json file are the root (not transitive) NuGet dependencies and the files to be compiled. By default, this is a wildcard -- "*.cs". It supports both inclusion and exclusion semantics.
+
+The restore.json file is expanded form of the project.json file. It includes the transitive closure of the project, per framework. It is produced by a NuGet client, typically by using the `dotnet restore` command. The restore.json file can be used by tools to safely determine the closure of dependencies, without having to manually calculate them. This file is only intended for tools, is temporary and should not be checked into source control. It should be present in .gitignore files.
+
+It is important to know that a restore.json is invalid given that a project.json has been changed. The restore.json has enough information to determine this state given a project.json. The compile command validates this state and will error if the restore.json is invalid.
+
+The compile command relies on NuGet dependencies for compilation, as references. These are expected to be found in the user-local NuGet cache (typically location here). It is an error state if a given NuGet package is not found.
+
+Output files, including temporary files, are written to the child `bin` folder, which will be created if it doesn't exist. Files will be overwritten as needed.
+
+**Options**
+
+-n, --native [exe | dynlib | lib]
+Compiles source to native machine code, for the local machine. The default is a native executable. The default exe extension is no extension and ".exe" on Windows. The default dynlib extension is ".a", ".dynlib" on OS X and ".dll" on Windows.
+
+-a, --arch [x86 | x64]
+Determines the architecture of the binary that --native produces. Valid values are x86 for 32-bit and x64 for 64-bit. 
+
+--il [exe | dll]
+Compiles source to IL byte code, which is (typically) portable across machine types. The default output is a PE32 exe, with the default extension of ".exe" on all OSes. The exe must include a static main entry point, or it is an error. The DLL output option has the default extension of ".dll".
+
+-o, --output filename
+Specifies the filename to be used. It is an error not to specify an output filename. If no extension is provided, the default one is provided for the output type.
+
+-r, --restore
+Restores the project before attempting to compile the project.
+
+-v, --verbose
+Prints verbose logging information, to follow the flow of execution of the command.

src/Microsoft.DotNet.Tools.Compiler/README.md

@@ -0,0 +1,49 @@
+dotnet-compile
+===========
+
+**NAME** 
+dotnet-compile -- Compiles source files to a binary format and saves to a target file.
+
+**SYNOPSIS**
+dotnet compile [options]
+
+**DESCRIPTION**
+The compile command compiles source files to a binary file, either IL byte code or native machine code, depending on the options provided. The default option is compilation to IL byte code, but may change to native compilation as that toolchain matures.
+
+The default IL [--il] output is a PE32 exe [exe], with the default extension of ".exe" on all OSes. The exe must include a static main entry point, or it is an error. The dll [dll] output option has the default extension of ".dll".
+
+The IL exe output type needs a runtime host to execute. The IL exe output type also copies a host to the output directory. The host is renamed to the name of the exe. For example, if the file is intended to be "foo" (`-o foo`), then the host will be called foo, with the appropriate default native file extension fo the OS (see the native file extensions, below). The PE32 exe will be called "[filename]"-app.exe". In this case, it would be called "foo-app.exe".
+
+The default native [--native] output is a native exe that conforms to the architecture of the underlying operating system (i.e. running on 64-bit OS will produce a native 64-bit exe). This can be overriden via the --arch switch and specifying the wanted architecture. The executable has a default extension of "" on Linux and OS X and ".exe" on Windows. The source must include a static void main entry point, or it is an error, unless otherwise specified in the project.json. The dynamic library [dylib] output option has the default extension of ".so" on Linux/UNIX, ".dynlib" on OS X and ".dll" on Windows. The static library [staticlib] option has the default extension of ".a" on Linux, UNIX and OS X and ".lib" on Windows.
+
+This command relies on the following artifacts: source files, project.json project file, restore.json temporary file and restored NuGet dependencies. In the case that an app depends on only the .NET Standard Library, then the project.json and restore.json file can be inferred and no additional NuGet dependencies are required. Other cases where these files are not provided or they do not match (more on that later) are error states.
+
+The project.json file represents and describes the project. It can contain several setting, which are described in the [Build](https://docs.asp.net/en/latest/dnx/projects.html#building). The most important information in the project.json file are the root (not transitive) NuGet dependencies and the files to be compiled. By default, this is a wildcard -- "*.cs". It supports both inclusion and exclusion semantics.
+
+The restore.json file is expanded form of the project.json file. It includes the transitive closure of the project, per framework. It is produced by a NuGet client, typically by using the `dotnet restore` command. The restore.json file can be used by tools to safely determine the closure of dependencies, without having to manually calculate them. This file is only intended for tools, is temporary and should not be checked into source control. It should be present in .gitignore files.
+
+It is important to know that a restore.json is invalid given that a project.json has been changed. The restore.json has enough information to determine this state given a project.json. The compile command validates this state and will error if the restore.json is invalid.
+
+The compile command relies on NuGet dependencies for compilation, as references. These are expected to be found in the user-local NuGet cache (typically location here). It is an error state if a given NuGet package is not found.
+
+Output files, including temporary files, are written to the child `bin` folder, which will be created if it doesn't exist. Files will be overwritten as needed.
+
+**Options**
+
+-n, --native [exe | dynlib | lib]
+Compiles source to native machine code, for the local machine. The default is a native executable. The default exe extension is no extension and ".exe" on Windows. The default dynlib extension is ".a", ".dynlib" on OS X and ".dll" on Windows.
+
+-a, --arch [x86 | x64]
+Determines the architecture of the binary that --native produces. Valid values are x86 for 32-bit and x64 for 64-bit. 
+
+--il [exe | dll]
+Compiles source to IL byte code, which is (typically) portable across machine types. The default output is a PE32 exe, with the default extension of ".exe" on all OSes. The exe must include a static main entry point, or it is an error. The DLL output option has the default extension of ".dll".
+
+-o, --output filename
+Specifies the filename to be used. It is an error not to specify an output filename. If no extension is provided, the default one is provided for the output type.
+
+-r, --restore
+Restores the project before attempting to compile the project.
+
+-v, --verbose
+Prints verbose logging information, to follow the flow of execution of the command.

src/Microsoft.DotNet.Tools.Publish/README.md

@@ -0,0 +1,50 @@
+dotnet-publish
+==============
+
+**NAME**
+
+dotnet-publish -- packs the application and all of its dependencies into a folder getting it ready for publishing
+
+**SYNOPSIS**
+
+dotnet-publish [options] [project]
+
+**DESCRIPTION**
+dotnet-publish will compile the application, read through its dependencies specified in project.json and publish the resulting set of files to a directory. This directory contains the assemblies, the runtime as well as the runnable version of the application. This directory can then be moved to a different machine and the application will be able to be ran regardless of existence of any other runtime.  
+
+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. 
+
+The command also requires information on the targeted framework and runtime, both of which can be specified on the command line. If the runtime is not specified, the command will default to the runtime for the current operating system. If the framework is not specified, the command will read the information from the project.json file. In case of no valid framework found, the command will error out. In case of multiple valid frameworks found, the command will publish for all valid frameworks. 
+
+
+**Options**
+
+-f, --framework [FID]
+Publish the application for a given framework identifier (FID). If not specified, FID is read from project.json
+
+-r, --runtime [RID]
+Publish the application for a given runtime. If not specified, will default to the current operating system. 
+
+-o, --output
+Specify the path where to place the directory. If not specified, will default to ./bin/[configuration]/[framework]/[runtime]/
+
+-c, --configuration [Debug|Release]
+Configuration to use when publishing. If not specified, will default to "Debug".
+
+  
+
+**EXAMPLES**
+dotnet-publish 
+	Publish the current application using the project.json framework and runtime for the current operating system. 
+
+dotnet-publish ~/projects/app1/project.json  
+	Publish the application using the specified project.json; also use framework specified withing and runtime for the current operating system. 
+	
+dotnet-publish --framework dnxcore50
+	Publish the current application using the dnxcore50 framework and runtime for the current operating system. 
+	
+dotnet-publish --framework dnxcore50 --runtime osx.10.10-x64
+	Publish the current application using the dnxcore50 framework and runtime for OS X 10.10  
+	
+**SEE ALSO**
+dotnet-restore

src/Microsoft.DotNet.Tools.Run/README.md

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