From 520a33462a6df865f08467d505ede955cdfd96a2 Mon Sep 17 00:00:00 2001 From: Krzysztof Wicher Date: Wed, 2 Mar 2016 14:26:52 -0800 Subject: [PATCH] add installation-scenarios.md spec --- Documentation/specs/installation-scenarios.md | 248 ++++++++++++++++++ 1 file changed, 248 insertions(+) create mode 100644 Documentation/specs/installation-scenarios.md diff --git a/Documentation/specs/installation-scenarios.md b/Documentation/specs/installation-scenarios.md new file mode 100644 index 000000000..1c1d79ac5 --- /dev/null +++ b/Documentation/specs/installation-scenarios.md @@ -0,0 +1,248 @@ +# Notes +This section describes placeholders used inside this spec. + +| Placeholder | Description | +| ---: | :--- | +| `` | `(future|preview|production)`. [See more info](#channels) | +| `` | 4-part-number version | +| `` | `(win|ubuntu|rhel|osx|debian)` - code for OS name | +| `` | Lowest supported OS Version | +| `` | Processor architecture related to binaries produced | +| `` | File extension. This will be described in more details later for each OS separately. | +| `` | Abbreviation for: `.`. [See more info](#osid) | +| `` | `(latest|lkg)` | +| `` | Executable extension including dot specific to OS (can be empty string) | +| `` | Commit hash related to state of repository from where build with specific `` was build | +| `` | Name of the debian package. [See more info](#debian-feed-relation) | + +# Build Output +Each official, successful build should create and upload packages to location described by following URLs: +``` +https://dotnetcli.blob.core.windows.net/dotnet///dotnet... + +Currently: +https://dotnetcli.blob.core.windows.net/dotnet//Binaries//dotnet-sharedframework--..zip +https://dotnetcli.blob.core.windows.net/dotnet//Binaries//dotnet-host--..zip +https://dotnetcli.blob.core.windows.net/dotnet//Binaries//dotnet--..zip +``` +Content of the package should contain binaries which layout will be described later. + +Additionally each build should update `latest` [version descriptors](#version-descriptors) + +## Windows output + +Nuget - WIP, this should include versioning scheme + +| `` | Description | +| --- | :--- | +| exe | Installer bundle. It should be used by end customers | +| zip | Packed binaries. Used by [installation script](#installation-scripts) | +| symbols.zip | Packed binaries with included symbols. See [symbol packages](#symbol-packages) | + +### Including dotnet cli installer as part of your bundle + +In order to install dotnet cli with other installer you need an MSI package. To get MSI, download exe bundle and extract it using `dark` tool which is part of [WiX Toolset](http://wixtoolset.org): +``` +dark.exe -x +``` + +## OSX output + +| `` | Description | +| --- | :--- | +| pkg | WIP | +| tar.gz | Packed binaries. Used by [installation script](#installation-scripts) | +| symbols.tar.gz | Packed binaries with included symbols. See [symbol packages](#symbol-packages) | + +## Ubuntu output + +| `` | Description | +| --- | :--- | +| deb | Debian package. This package is being pushed to a [debian feed](#debian-feed) | +| tar.gz | Packed binaries. Used by [installation script](#installation-scripts) | +| symbols.tar.gz | Packed binaries with included symbols. See [symbol packages](#symbol-packages) | + +## RedHat/CentOS output + +| `` | Description | +| --- | :--- | +| tar.gz | Packed binaries. Used by [installation script](#installation-scripts) | +| symbols.tar.gz | Packed binaries with included symbols. See [symbol packages](#symbol-packages) | + +## Debian output + +| `` | Description | +| --- | :--- | +| tar.gz | Packed binaries. Used by [installation script](#installation-scripts) | +| symbols.tar.gz | Packed binaries with included symbols. See [symbol packages](#symbol-packages) | + +## Example build output links +WIP + +## Questions +- Should include channel name to avoid situation where you have two files on your computer and latest file might have lower version than the newest? + +# Obtaining dotnet + +## Installation scripts + +Installation script is a shell script which lets customers install dotnet. + +For Windows we are using PowerShell script (install-dotnet.ps1). +For any other OS we are using bash script (install-dotnet.sh) + +WIP: Exact script action description. + +### Script arguments description + +| PowerShell script | Bash script | Default | Description | +| --- | --- | --- | --- | +| -Channel | --channel | production | Which [channel](#channels) to install from. Possible values: `future`, `preview`, `production` | +| -Version | --version | `global.json` or `latest` | | +| -InstallDir | --prefix | Windows: `%LocalAppData%\Microsoft\.dotnet` | Path to where install dotnet. Note that binaries will be placed directly in a given directory. | +| -Architecture | ~~--architecture~~ | auto | Possible values: `auto`, `x64`, `x86`. `auto` refers to currently running OS architecture. This switch is currently not supported in bash scripts. | +| -DebugSymbols | --debug-symbols | `` | If switch present, installation will include debug symbol | +| -DryRun | --dry-run | `` | If switch present, installation will not be performed and instead deterministic invocation with specific version and zip location will be displayed. | +| -NoPath | --no-path | `` | If switch present the script will not set PATH environmental variable for the current process. | +| -Verbose | --verbose | `` | If switch present displays diagnostics information. | +| -AzureFeed | --azure-feed | See description | Azure feed URL, default: `https://dotnetcli.blob.core.windows.net/dotnet` | + +### Script location +WIP: permanent link for obtaining latest version +WIP: versioning description +Newest version of the scripts can be found in the repository under following directory: +``` +https://github.com/dotnet/cli/tree/rel/1.0.0/scripts/obtain +``` + +Older version of the script can be obtained using: +``` +https://github.com/dotnet/cli/blob//scripts/obtain +``` + +## Getting started page +WIP + +## Repo landing page +WIP + +# Version descriptors +## Version pointers +Version pointers represent URLs to the latest and Last Known Good (LKG) builds. +Specific URLs TBD. This will be something similar to following: +``` +/dotnet//..version +``` + +`` TBD + +## Version files +Version files can be found in multiple places: +- Package: relative path inside the package ./.version +- Latest/LKG version file: WIP + +URL: +``` +https://dotnetcli.blob.core.windows.net/dotnet//..version +``` + +### File content +Each version file contains two lines describing the build: +``` + + +``` + +## Version badge +Version badge (SVG) is an image with textual representation of ``. It can be found under following URL: +``` +https://dotnetcli.blob.core.windows.net/dotnet//..svg +``` + +## Questions/gaps +- Version Pointer links should be permanent and hosted on a separate domain + +# Package content +Currently package is required to contain two files: +- .version - [version file](#version-file) +- dotnet - entry point for all dotnet commands + +## Disk Layout +``` +.\ + .version + bin\ + dotnet +``` + +# Channels +Currently we have 3 channels which gives us idea about stability and quality of our product. + +| Channel name | Description | +| :---: | :--- | +| future | This channel can contain new features which may not be fully complete. This is usually most unstable channel. | +| preview | This channel is in the process of stablization. Most of the bugs and gaps are known. No new features expected. | +| production | This is the most stable channel. Features and gaps are known. No breaking changes can be expected. This channel will only be producing new versions on hotfixes. | + +## Github branches relation + +Each branch on each successful build produces packages described in [build output](#build-output). Mapping between branches and channel name can be found in the table below: + +| Channel name | Github branch | +| :---: | :--- | +| future | master | +| preview | rel/1.0.0 | +| production | N/A, prod? | + +## Debian feed relation + +After each successful build package is being pushed to the debian feed. More information on debian feed can be found [here](#debian-feed). + +| Channel name | `` | +| :---: | :--- | +| future | dotnet-future | +| preview | dotnet-preview | +| production | dotnet | + +## Nuget semantic version suffix relation +WIP + +## Questions +- What is the bar for triggering hotfix? + +# OSID + +OSID represents abbreviation for: +``` +. +``` +This naming scheme gives us flexibility to easily create new binaries when OS makes a breaking change without creating confusing names. + +In example, we currently put `api-ms-*.dll` files in our binaries. Those files are not needed on Windows 8 and higher. When using name `win7.x64` we can easily decide to get rid of `api-ms-*.dll` in the newest packages and simply call new version `win8.x64` which would mean that from Windows 8 forward those are recommended binaries (there is currently no issue with those files and this should be only treated as an example). + +# Debian feed + +Newest binaries in debian feed may be delayed due to external issues by up to 24h. + +## Obtaining binaries + +Add debian feed: +``` +sudo sh -c 'echo "deb [arch=amd64] http://apt-mo.trafficmanager.net/repos/dotnet/ trusty main" > /etc/apt/sources.list.d/dotnetdev.list' + +sudo apt-key adv --keyserver apt-mo.trafficmanager.net --recv-keys 417A0893 + +sudo apt-get update +``` + +Install: +``` +sudo apt-get install = +``` + +## Questions +- Is debian version compatible with `` or does it require additional revision number, i.e.: `1.0.0.001598-1`? +- How to differentiate between Debian package for Debian and Debian package for Ubuntu? +- +# Symbol packages +WIP