From c1fafc40d7b33a0950cc2ffff83ed6fbf5668b5e Mon Sep 17 00:00:00 2001 From: blackdwarf Date: Fri, 22 May 2015 12:51:56 -0700 Subject: [PATCH 1/2] Documentation for installing .NET Core & Desktop Added processes for installing .NET Core and .NET Desktop framework on all supported OS-es. --- .../getting-started/installing-core-linux.rst | 171 +++++++++++++++++- .../installing-core-macosx.rst | 154 +++++++++++++++- .../installing-core-windows.rst | 136 +++++++++++++- docs/getting-started/installing-desktop.rst | 26 ++- 4 files changed, 472 insertions(+), 15 deletions(-) diff --git a/docs/getting-started/installing-core-linux.rst b/docs/getting-started/installing-core-linux.rst index 4e561567da8a8..25053c2b9befd 100644 --- a/docs/getting-started/installing-core-linux.rst +++ b/docs/getting-started/installing-core-linux.rst @@ -1,7 +1,172 @@ .. include:: /stub-topic.txt -|stub-icon| Installing .NET Core on Linux +Installing .NET Core on Linux ========================================= -.. include:: /stub-notice.txt - +These instructions will lead you through acquiring the .NET Core DNX SDK +via the `.NET Version Manager (DNVM) `__ +and running a "Hello World" demo on Linux. + +.NET Core NuGet packages and the .NET Core DNX SDKs are available on the +`ASP.NET 'vnext' myget feed `__, +which you can more easily view on +`gallery `__ for the feed. + +Setting up the environment +-------------------------- + +These instructions have been written and tested on Ubuntu 14.04 LTS, since that is the main Linux distribution the .NET Core team uses. These instructions may succeed on other distributions as well. We are always accepting new pull requests on `our GitHub repo `_ that address running on other Linux distributions. The only requirement is that they do not break the ability to use Ubuntu 14.04 LTS. + +Installing the required packages +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Install the ``libunwind8``, ``libssl-dev`` and ``unzip`` packages: + +:: + + sudo apt-get install libunwind8 libssl-dev unzip + +You also need a latest version of Mono, which is required for DNX tooling. This is a temporary requirement, and will not be required in the future. + +:: + + sudo apt-key adv --keyserver keyserver.ubuntu.com --recv-keys 3FA7E0328081BFF6A14DA29AA6A19B38D3D831EF + echo "deb http://download.mono-project.com/repo/debian wheezy main" | sudo tee /etc/apt/sources.list.d/mono-xamarin.list + sudo apt-get update + sudo apt-get install mono-complete + +Certificates +^^^^^^^^^^^^ + +You need to import trusted root certificates in order to restore NuGet packages. You can do that with the ``mozroots`` tool. + +:: + + mozroots --import --sync + +Installing DNVM +--------------- + +You need DNVM as a starting point. DNVM enables you to acquire one or multiple .NET Execution Environments (DNX). DNVM is a shell script and does not require .NET. You can use the below command to install it. + +:: + + curl -sSL https://raw.githubusercontent.com/aspnet/Home/dev/dnvminstall.sh | DNX_BRANCH=dev sh && source ~/.dnx/dnvm/dnvm.sh + +Installing the .NET Core DNX +---------------------------- + +You first need to acquire the Mono DNX. It doesn't include Mono, but is +needed to use the DNX tools on top of Mono. In particular, the DNU +command is not yet supported on .NET Core, requiring us to use Mono for +this purpose (until DNU runs on .NET Core). Mono is the default DNX, so +you can acquire it via ``dnvnm upgrade``. + +:: + + dnvm upgrade -u + +Next, acquire the .NET Core DNX SDK. + +:: + + dnvm install latest -r coreclr -u + +You can see the currently installed DNX versions with ``dnvm list``. + +:: + + dnvm list + +:: + + Active Version Runtime Arch Location Alias + ------ ------- ------- ---- -------- ----- + * 1.0.0-beta5-11649 coreclr x64 ~/.dnx/runtimes + 1.0.0-beta5-11649 mono ~/.dnx/runtimes default + +Using a specific runtime +------------------------ + +You can choose which of the installed DNXs you want to use with ``dnvm use``, specifying arguments that are similar to the ones used when installing a runtime. + +:: + + dnvm use -r coreclr -arch x86 1.0.0-beta5-11649 + Adding ~/.dnx/runtimes/dnx-coreclr-win-x86.1.0.0-beta5-11649/bin + to process PATH + + dnvm list + + Active Version Runtime Arch Location Alias + ------ ------- ------- ---- -------- ----- + * 1.0.0-beta5-11649 coreclr x64 ~/.dnx/runtimes + 1.0.0-beta5-11649 mono ~/.dnx/runtimes default + +See the asterisk in the listing above? It's purpose is to tell you which runtime is now active. "Active" here means that all of the interaction with your projects and .NET Core will use this runtime. + +That's it! You now have the .NET Core runtime installed on your machine and it is time to take it for a spin. + +Write your App +-------------- + +his being an introduction-level document, it seems fitting to start with a "Hello World" app. Here's a very simple one you can copy and paste into a CS file in a directory. + +.. code:: csharp + + using System; + + public class Program + { + public static void Main (string[] args) + { + Console.WriteLine("Hello, Linux"); + Console.WriteLine("Love from CoreCLR."); + } + } + +A more ambitious example is available on the `corefxlab repo `_ that will print out a pretty picture based on the argument you provide at runtime. If you wish to use this example, simply save the `C# file `_ to a directory somewhere on your machine. + +The next thing you will need is a ``project.json`` file that will outline the dependencies of an app, so you can **actually** run it. Use the contents below, it will work for both examples above. Save this file in a directory next to the CS file that contains your code. + +:: + + { + "version": "1.0.0-*", + "dependencies": { + }, + "frameworks" : { + "dnx451" : { }, + "dnxcore50" : { + "dependencies": { + "System.Console": "4.0.0-beta-*" + } + } + } + } + +Run your App +------------ + +You need to restore packages for your app, based on your project.json, +with ``dnu restore``. You will need to run this command under the Mono +DNX. The first command switches the active runtime to the Mono one. + +:: + + dnvm use 1.0.0-beta5-11649 -r mono + dnu restore + +You are now ready to run your app under .NET Core. As you can guess, however, before you do that you first need to switch to the .NET Core runtime. The first command below does exactly that. + +:: + + dnvm use 1.0.0-beta5-11649 -r coreclr + dnx . run + + Hello, Linux + Love from CoreCLR. + +Building .NET Core from source +------------------------------ +.NET Core is an open source project that is hosted on GitHub. This means that you can, at any given time, clone the repository and build .NET Core from source. This is a more advanced scenario that is usually used when you want to add features to the .NET runtime or the BCL or if you are a contributor to these projects. The detailed instruction on how to build .NET Core windows can be found in the `.NET Core OS X build instructions `_ on GitHub. diff --git a/docs/getting-started/installing-core-macosx.rst b/docs/getting-started/installing-core-macosx.rst index 926bdebfa17a9..609535dfba82b 100644 --- a/docs/getting-started/installing-core-macosx.rst +++ b/docs/getting-started/installing-core-macosx.rst @@ -1,7 +1,153 @@ .. include:: /stub-topic.txt -|stub-icon| Installing .NET Core on MacOSX -========================================== +Installing .NET Core on MacOSX +============================== -.. include:: /stub-notice.txt - +These instructions will lead you through acquiring the .NET Core DNX SDK +via the `.NET Version Manager (DNVM) `__ +and running a "Hello World" demo on OS X. + +.NET Core NuGet packages and the .NET Core DNX SDKs are available on the +`ASP.NET 'vnext' myget feed `__, +which you can more easily view on +`gallery `__ for the feed. + + +Installing DNVM +--------------- + +You need DNVM as a starting point. DNVM enables you to acquire one or +multiple .NET Execution Environments (DNX). DNVM is simply a script, +which doesn't depend on .NET. On OS X the best way to get DNVM is to use `Homebrew `__. If +you don't have Homebrew installed then follow the `Homebrew installation +instructions `__. Once you have Homebrew up and running you can use the the following commands: + +:: + + brew tap aspnet/dnx + brew update + brew install dnvm + +You will likely need to register the dnvm command: + +:: + + source dnvm.sh + +Installing the .NET Core DNX +---------------------------- + +Since .NET Core is still a work in progress, you will need to make use of `Mono `_ to run certain parts of the DNX tooling. On non-Windows operating systems, Mono is the default DNX, so you can use a simple ``dnvm upgrade`` command to install it. + +:: + + dnvm upgrade -u + +Next, acquire the .NET Core DNX SDK. + +:: + + dnvm install latest -r coreclr -u + +You can see the currently installed DNX versions with ``dnvm list``. + +:: + + dnvm list + +:: + + Active Version Runtime Arch Location Alias + ------ ------- ------- ---- -------- ----- + * 1.0.0-beta5-11649 coreclr x64 ~/.dnx/runtimes + 1.0.0-beta5-11649 mono ~/.dnx/runtimes default + +.. note:: + The version numbers above can and will change when you run the commands, which is normal. Don't forget to use the proper numbers when further interacting with DNVM in the below samples. + +Using a specific runtime +------------------------ + +You can choose which of the installed DNXs you want to use with ``dnvm use``, specifying arguments that are similar to the ones used when installing a runtime. + +:: + + dnvm use -r coreclr -arch x64 1.0.0-beta5-11649 + Adding ~/.dnx/runtimes/dnx-coreclr-win-x86.1.0.0-beta5-11649/bin + to process PATH + + dnvm list + + Active Version Runtime Arch Location Alias + ------ ------- ------- ---- -------- ----- + * 1.0.0-beta5-11649 coreclr x64 ~/.dnx/runtimes + 1.0.0-beta5-11649 mono ~/.dnx/runtimes default + +See the asterisk in the listing above? It's purpose is to tell you which runtime is now active. "Active" here means that all of the interaction with your projects and .NET Core will use this runtime. + +That's it! You now have the .NET Core runtime installed on your machine and it is time to take it for a spin. + + +Write your App +-------------- + +This being an introduction-level document, it seems fitting to start with a "Hello World" app. Here's a very simple one you can copy and paste into a CS file in a directory. + +.. code:: csharp + + using System; + + public class Program + { + public static void Main (string[] args) + { + Console.WriteLine("Hello, OS X"); + Console.WriteLine("Love from CoreCLR."); + } + } + +A more ambitious example is available on the `corefxlab repo `_ that will print out a pretty picture based on the argument you provide at runtime. If you wish to use this example, simply save the `C# file `_ to a directory somewhere on your machine. + +The next thing you will need is a ``project.json`` file that will outline the dependencies of an app, so you can **actually** run it. Use the contents below, it will work for both examples above. Save this file in a directory next to the CS file that contains your code. + +:: + + { + "version": "1.0.0-*", + "dependencies": { + }, + "frameworks" : { + "dnx451" : { }, + "dnxcore50" : { + "dependencies": { + "System.Console": "4.0.0-beta-*" + } + } + } + } + +Run your App +------------ + +You need to restore packages for your app, based on your project.json, +with ``dnu restore``. You will need to run this command under the Mono +DNX. The first command switches the active runtime to the Mono one. + +:: + + dnvm use 1.0.0-beta5-11649 -r mono + dnu restore + +You are now ready to run your app under .NET Core. As you can guess, however, before you do that you first need to switch to the .NET Core runtime. The first command below does exactly that. + +:: + + dnvm use 1.0.0-beta5-11649 -r coreclr + dnx . run + + Hello, OSX + Love from CoreCLR. + +Building .NET Core from source +------------------------------ +.NET Core is an open source project that is hosted on GitHub. This means that you can, at any given time, clone the repository and build .NET Core from source. This is a more advanced scenario that is usually used when you want to add features to the .NET runtime or the BCL or if you are a contributor to these projects. The detailed instruction on how to build .NET Core windows can be found in the `.NET Core OS X build instructions `_ on GitHub. diff --git a/docs/getting-started/installing-core-windows.rst b/docs/getting-started/installing-core-windows.rst index b198d49183aa1..fadcdea210014 100644 --- a/docs/getting-started/installing-core-windows.rst +++ b/docs/getting-started/installing-core-windows.rst @@ -1,7 +1,135 @@ .. include:: /stub-topic.txt -|stub-icon| Installing .NET Core on Windows -=========================================== +Installing .NET Core on Windows +=============================== -.. include:: /stub-notice.txt - +This document will lead you through acquiring the .NET Core DNX SDK via the `.NET Version Manager (DNVM) `_ and running a "Hello World" demo on Windows. + +.NET Core NuGet packages and the .NET Core DNX SDKs are available on the `ASP.NET 'vnext' myget feed `__, which you can more easily view on `gallery `__ for the feed. + +Installing DNVM +--------------- + +You need DNVM as a starting point. DNVM enables you to acquire one or +multiple .NET Execution Environments (DNX). DNVM is simply a script, +which doesn't depend on .NET. You can install it via a PowerShell +command from a command prompt window. You can find alternate DNVM install instructions at the +`ASP.NET Home repo `__. + +:: + + @powershell -NoProfile -ExecutionPolicy unrestricted -Command "&{$Branch='dev';iex ((new-object net.webclient).DownloadString('https://raw.githubusercontent.com/aspnet/Home/dev/dnvminstall.ps1'))}" + +The script will set several global environment variables to make using DNVM easier in the future. In order for these to kick in, you need to restart your command shell session. + +Installing a .NET Core DNX +-------------------------- + +It's easy to install the latest .NET Core-based DNX, using the ``dnvm install`` command. + +:: + + dnvm install -r coreclr latest -u + +This will install the 32-bit version of .NET Core. If you want the 64-bit version, you can specify processor architecture. + +:: + + dnvm install -r coreclr -arch x64 latest -u + +You can see the currently installed DNX versions with ``dnvm list``. + +:: + + dnvm list + + Active Version Runtime Architecture Location Alias + ------ ------- ------- ------------ -------- ----- + * 1.0.0-beta5-11649 coreclr x64 C:\Users\[user]\.dnx\runtimes + 1.0.0-beta5-11649 coreclr x86 C:\Users\[user]\.dnx\runtimes default + + +.. note:: + The version numbers above can and will change when you run the commands, which is normal. Don't forget to use the proper numbers when further interacting with DNVM in the below samples. + +Using a specific runtime +------------------------ + +You can choose which of the installed DNXs you want to use with ``dnvm use``, specifying arguments that are similar to the ones used when installing a runtime. + +:: + + dnvm use -r coreclr -arch x86 1.0.0-beta5-11649 + Adding C:\Users\[user]\.dnx\runtimes\dnx-coreclr-win-x86.1.0.0-beta5-11649\bin + to process PATH + + dnvm list + + Active Version Runtime Architecture Location Alias + ------ ------- ------- ------------ -------- ----- + 1.0.0-beta5-11649 coreclr x64 C:\Users\[user]\.dnx\runtimes + * 1.0.0-beta5-11649 coreclr x86 C:\Users\[user]\.dnx\runtimes default + +See the asterisk in the listing above? It's purpose is to tell you which runtime is now active. "Active" here means that all of the interaction with your projects and .NET Core will use this runtime. + +That's it! You now have the .NET Core runtime installed on your machine and it is time to take it for a spin. + +Write your App +-------------- + +This being an introduction-level document, it seems fitting to start with a "Hello World" app. Here's a very simple one you can copy and paste into a CS file in a directory. + +.. code:: csharp + + using System; + + public class Program + { + public static void Main (string[] args) + { + Console.WriteLine("Hello, Windows"); + Console.WriteLine("Love from CoreCLR."); + } + } + +A more ambitious example is available on the `corefxlab repo `_ that will print out a pretty picture based on the argument you provide at runtime. If you wish to use this example, simply save the `C# file `_ to a directory somewhere on your machine. + +The next thing you will need is a ``project.json`` file that will outline the dependencies of an app, so you can **actually** run it. Use the contents below, it will work for both examples above. Save this file in a directory next to the CS file that contains your code. + +:: + + { + "version": "1.0.0-*", + "dependencies": { + }, + "frameworks" : { + "dnx451" : { }, + "dnxcore50" : { + "dependencies": { + "System.Console": "4.0.0-beta-*" + } + } + } + } + +Run your App +------------ + +You need to restore packages for your app, based on your project.json, +with ``dnu restore``. + +:: + + dnu restore + +You can run your app with the DNX command. + +:: + + dnx . run + +This will instruct the currently active DNX to run your app. Note that you didn't need to actually build the code; DNX will take care of this for you. + +Building .NET Core from source +------------------------------ +.NET Core is an open source project that is hosted on GitHub. This means that you can, at any given time, clone the repository and build .NET Core from source. This is a more advanced scenario that is usually used when you want to add features to the .NET runtime or the BCL or if you are a contributor to these projects. The detailed instruction on how to build .NET Core windows can be found in the `.NET Core Windows build instructions `_ on GitHub. diff --git a/docs/getting-started/installing-desktop.rst b/docs/getting-started/installing-desktop.rst index 818b078debace..c847aa05824a7 100644 --- a/docs/getting-started/installing-desktop.rst +++ b/docs/getting-started/installing-desktop.rst @@ -1,7 +1,25 @@ .. include:: /stub-topic.txt -|stub-icon| Installing .NET Framework -===================================== +Installing .NET Desktop Framework +================================= +.. note:: + The .NET Desktop Framework is supported only on Windows. -.. include:: /stub-notice.txt - +Installing the .NET Desktop Framework is very easy, and it might not even be required! If you have Windows installed, you more than likely already have the runtime installed with it. This will allow you to run programs written to run on .NET Framework, but it will not be enough for you to develop programs on your own. For this, you will need to install some SDKs and tools. + +If you happen to not have the Framework already installed, there are two main ways to get it: + +* Via a dedicated installer +* Via Windows Update + +Getting the installer +--------------------- +You can get the links to installers for various .NET versions on `MSDN `_. Simply pick the version you are interested in, click the link and follow the instructions. + +Getting the framework via Windows Update +---------------------------------------- +There is nothing special to do here, except run Windows update and view optional updates, selecting and letting WU do its work. + +Getting the SDKs +---------------- +When you've installed the actual Framework, you can check out `Visual Studio `_ to enable you to get started building .NET applications. From 6683cc22d4c3097d4d9e0338546300de1e385747 Mon Sep 17 00:00:00 2001 From: blackdwarf Date: Wed, 27 May 2015 16:33:09 -0700 Subject: [PATCH 2/2] Fix PR comments Fix PR #2 --- docs/getting-started/index.rst | 4 +-- .../installing-core-macosx.rst | 2 +- docs/getting-started/installing-desktop.rst | 25 ------------------- 3 files changed, 2 insertions(+), 29 deletions(-) delete mode 100644 docs/getting-started/installing-desktop.rst diff --git a/docs/getting-started/index.rst b/docs/getting-started/index.rst index aa6df810cc42f..1ca47df842768 100644 --- a/docs/getting-started/index.rst +++ b/docs/getting-started/index.rst @@ -3,10 +3,8 @@ Getting started .. toctree:: :titlesonly: - + overview - installing-desktop installing-core-windows installing-core-linux installing-core-macosx - \ No newline at end of file diff --git a/docs/getting-started/installing-core-macosx.rst b/docs/getting-started/installing-core-macosx.rst index 609535dfba82b..5b493790f5950 100644 --- a/docs/getting-started/installing-core-macosx.rst +++ b/docs/getting-started/installing-core-macosx.rst @@ -1,6 +1,6 @@ .. include:: /stub-topic.txt -Installing .NET Core on MacOSX +Installing .NET Core on OS X ============================== These instructions will lead you through acquiring the .NET Core DNX SDK diff --git a/docs/getting-started/installing-desktop.rst b/docs/getting-started/installing-desktop.rst deleted file mode 100644 index c847aa05824a7..0000000000000 --- a/docs/getting-started/installing-desktop.rst +++ /dev/null @@ -1,25 +0,0 @@ -.. include:: /stub-topic.txt - -Installing .NET Desktop Framework -================================= -.. note:: - The .NET Desktop Framework is supported only on Windows. - -Installing the .NET Desktop Framework is very easy, and it might not even be required! If you have Windows installed, you more than likely already have the runtime installed with it. This will allow you to run programs written to run on .NET Framework, but it will not be enough for you to develop programs on your own. For this, you will need to install some SDKs and tools. - -If you happen to not have the Framework already installed, there are two main ways to get it: - -* Via a dedicated installer -* Via Windows Update - -Getting the installer ---------------------- -You can get the links to installers for various .NET versions on `MSDN `_. Simply pick the version you are interested in, click the link and follow the instructions. - -Getting the framework via Windows Update ----------------------------------------- -There is nothing special to do here, except run Windows update and view optional updates, selecting and letting WU do its work. - -Getting the SDKs ----------------- -When you've installed the actual Framework, you can check out `Visual Studio `_ to enable you to get started building .NET applications.