Skip to content

Commit 1d0b7a8

Browse files
omajidomajid
authored
Add documentation for packaging source-build (#1653)
1 parent a043885 commit 1d0b7a8

File tree

2 files changed

+131
-1
lines changed

2 files changed

+131
-1
lines changed

‎Documentation/README.md

Lines changed: 17 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,9 @@ The following document includes documentation for the build scripts. Over time,
44

55
## Building the .NET Core SDK
66

7-
The scripts are supported on Windows, macOS and Linux. The scripts are based on PowerShell on Windows and Bash on macOS and Linux.
7+
The scripts are supported on macOS and Linux. The scripts are based on Bash on macOS and Linux.
8+
9+
> The source-build repository doesn't currently support Windows. See [source-build#1190](https://github.com/dotnet/source-build/issues/1190).
810
911
### Syncing
1012

@@ -20,6 +22,20 @@ git submodule update --init --recursive
2022
./build.{cmd|sh}
2123
```
2224

25+
Once the build is successful, the built SDK tarball is placed at:
26+
27+
```
28+
artifacts/${ARCHITECTURE}/Release/dotnet-sdk-${SDK_VERSION}-${RUNTIME_ID}.tar.gz
29+
```
30+
31+
- `${ARCHITECTURE}` is your platform architecture (probably `x64`)
32+
- `${SDK_VERSION}` is the SDK version you are building
33+
- `${RUNTIME_ID}` is your OS name and architecture (something like `debian.9-x64` or `fedora.33-x64`)
34+
35+
For example, building a 3.1.105 SDK on an x64 (aka x86\_64) platform running Fedora 32 will produce `artifacts/x64/Release/dotnet-sdk-3.1.105-fedora.32-x64.tar.gz`.
36+
37+
If you are interested in "installing" this SDK system wide or making a Linux package out of the SDK, please see [Packaging and Installation](packaging-installation.md).
38+
2339
## Building one repo
2440

2541
By default we build the cli and its dependencies but the default root repository to build can be passed in. For example, if you just want to build the .NET Core Runtime, you would just build the `core-setup` repo and its dependencies:

‎Documentation/packaging-installation.md

Lines changed: 114 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,114 @@
1+
# .NET Core Packaging and Installation
2+
3+
This document helps you install or package a .NET Core SDK built using source-build.
4+
5+
The SDK built by source-build is generally not portable. That means it will work on the same operating system where it was built. It will not work on older operating systems. It may work on newer operating systems.
6+
7+
The built SDK is generally located at `artifacts/${ARCHITECTURE}/Release/dotnet-sdk-${SDK_VERSION}-${RUNTIME_ID}.tar.gz`.
8+
9+
## Using the SDK directly (install per-user)
10+
11+
To use the SDK directly, unpack the SDK to any directory and then use the `dotnet` executable from it.
12+
13+
You can find more details on how to manually install an SDK from a tarball at [manually installing an SDK](https://docs.microsoft.com/en-us/dotnet/core/install/linux-ubuntu#manual-install). The same steps listed should work for all Linux distributions where `bash` (or `sh`) is the default shell.
14+
15+
## Installing the SDK globally
16+
17+
If you want to install the SDK globally (and not per user), here are some suggestions.
18+
19+
1. Extract the tarball to a distribution-appropriate location such as `/usr/local/lib64/dotnet/`, `/usr/local/lib/dotnet/`, or `/usr/local/lib/x86_64-linux-gnu/dotnet/`.
20+
21+
2. Create a symlink from `/usr/local/bin/dotnet` (or an equivalent location available in `$PATH`) to the `dotnet` binary in the SDK that you installed in the previous step. For example:
22+
23+
```bash
24+
ln -s /usr/local/lib64/dotnet/dotnet /usr/local/bin/dotnet
25+
```
26+
27+
Now users can simply run `dotnet` and it will work.
28+
29+
3. Create an `/etc/dotnet/install_location` file and add the path of the SDK directory in there. The file should contain a single line like this:
30+
31+
```
32+
/usr/local/lib64/dotnet/
33+
```
34+
35+
This file is used by [.NET Core to find the SDK/Runtime location](https://github.com/dotnet/designs/blob/master/accepted/2020/install-locations.md)
36+
37+
4. Define `DOTNET_ROOT` and update `PATH` by saving the following as `/etc/profile.d/dotnet-local.sh` (or equivalent)
38+
39+
```bash
40+
# Set location for AppHost lookup
41+
[ -z "$DOTNET_ROOT" ] && export DOTNET_ROOT=/usr/local/lib64/dotnet
42+
43+
# Add dotnet tools directory to PATH
44+
DOTNET_TOOLS_PATH="$HOME/.dotnet/tools"
45+
case "$PATH" in
46+
*"$DOTNET_TOOLS_PATH"* ) true ;;
47+
* ) PATH="$PATH:$DOTNET_TOOLS_PATH" ;;
48+
esac
49+
```
50+
51+
Make sure to adjust the paths to match what you used on your system.
52+
53+
This snippet should work in `sh` (including `dash`) and `bash`. You may need to adapt it, or use something entirely different, for other shells.
54+
55+
This allows apphost-lookup to work via `DOTNET_ROOT` and allows users to easily use dotnet tools directly after a `dotnet tool install`.
56+
57+
## Creating a Linux distribution package
58+
59+
If you want to create a Linux distribution package (`rpm`, `deb`) out of the source-build SDK here are some suggestions.
60+
61+
See [.NET Core distribution packaging](https://docs.microsoft.com/en-us/dotnet/core/distribution-packaging) for information on suggested packages, subpackages, name and contents.
62+
63+
This is the minimal amount of content you need to package up:
64+
65+
1. Extract the tarball to the distribution appropriate location such as `/usr/lib64/dotnet/`, `/usr/lib/dotnet/`, or `/usr/lib/x86_64-linux-gnu/dotnet/`.
66+
67+
2. Create a symlink from `/usr/bin/dotnet` (or equivalent) to the `dotnet` binary in the SDK that you installed in the previous step. For example:
68+
69+
```bash
70+
ln -s /usr/lib64/dotnet/dotnet /usr/bin/dotnet
71+
```
72+
73+
Now users can simply run `dotnet` and it will work.
74+
75+
3. Create an `/etc/dotnet/install_location` file and add the path of the SDK directory in there. The file should contain a single line like this:
76+
77+
```bash
78+
/usr/lib64/dotnet
79+
```
80+
81+
This file is used by [.NET Core to find the SDK/Runtime location](https://github.com/dotnet/designs/blob/master/accepted/2020/install-locations.md).
82+
83+
4. Define `DOTNET_ROOT` and update `PATH` by saving the following as `/etc/profile.d/dotnet.sh` (or equivalent)
84+
85+
```bash
86+
# Set location for AppHost lookup
87+
[ -z "$DOTNET_ROOT" ] && export DOTNET_ROOT=/usr/lib64/dotnet
88+
89+
# Add dotnet tools directory to PATH
90+
DOTNET_TOOLS_PATH="$HOME/.dotnet/tools"
91+
case "$PATH" in
92+
*"$DOTNET_TOOLS_PATH"* ) true ;;
93+
* ) PATH="$PATH:$DOTNET_TOOLS_PATH" ;;
94+
esac
95+
```
96+
97+
Make sure to adjust the paths to match what the distribution policies.
98+
99+
This snippet should work in `sh` (including `dash`) and `bash`. You may need to adapt it, or use something entirely different, for other shells.
100+
101+
This allows apphost-lookup to work via `DOTNET_ROOT` and allows users to easily use dotnet tools directly after a `dotnet tool install`.
102+
103+
There are other optional things you can do:
104+
105+
- .NET Core source repositories include man pages. You can search for them and package them up: `find -iname '*.1' -exec cp {} /usr/share/man/man1/ \;`
106+
107+
- .NET Core includes [bash-completion](https://github.com/dotnet/cli/blob/master/scripts/register-completions.bash) and [zsh-completion](https://github.com/dotnet/cli/blob/master/scripts/register-completions.zsh) scripts. The copies in the source code you used to build the SDK should be the latest version. See [how to enable tab completion for .NET Core cli](https://docs.microsoft.com/en-us/dotnet/core/tools/enable-tab-autocomplete) for more information.
108+
109+
## Resources and references
110+
111+
- [.NET Core distribution packaging](https://docs.microsoft.com/en-us/dotnet/core/distribution-packaging)
112+
- [Fedora .NET Core 3.1 package](https://src.fedoraproject.org/rpms/dotnet3.1/tree/master)
113+
- [.NET Core - ArchWiki](https://wiki.archlinux.org/index.php/.NET_Core)
114+
- [State of .NET Core on Arch - a discussion between a few distribution package maintainers](https://www.reddit.com/r/archlinux/comments/cx64r5/the_state_of_net_core_on_arch/)

0 commit comments

Comments
 (0)