Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

[doc] Update doc with cross-rs and musl builds #2621

Merged
merged 1 commit into from
Jan 11, 2024
Merged

[doc] Update doc with cross-rs and musl builds #2621

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
57 changes: 44 additions & 13 deletions docs/src/user/basic_setup.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,16 +6,35 @@ Youki currently only supports Linux Platform, and to use it on other platform yo

Also note that Youki currently only supports and expects systemd as init system, and would not work on other systems. There is currently work on-going to put systemd dependent features behind a feature flag, but till then you will need a systemd enabled system to work with Youki.

## Requirements
## Build Requirements

As Youki is written in Rust, you will need to install and setup Rust toolchain to compile it. The instructions for that can be found on Rust's official site [here](https://www.rust-lang.org/tools/install).
If you installed it using rustup, the correct compiler version will be setup automatically from `rust-toolchain.toml` in the repo root.

You can use Youki by itself to start and run containers, but it can be a little tedious, as it is a low-level container runtime. You can use a High-level container runtime, with its runtime set to Youki, so that it will be easier to use. Both of these are explained in the [Basic Usage](./basic_usage.md). For using it along with an high-level runtime, you will to install one such as Docker or Podman. This documentation uses Docker in its examples, which can be installed from [here](https://docs.docker.com/engine/install).
### Build with cross-rs

You can compile youki using [cross-rs](https://github.com/cross-rs/cross), which provides:
* Seamless compilation for different architectures (see `Cross.toml` in the repo root for the list of supported targets)
* No build time dependencies (compilation runs in a container)
* No runtime dependencies when building static binaries (musl targets)

The only build dependency is [cross-rs](https://github.com/cross-rs/cross?tab=readme-ov-file#installation) and its [dependencies](https://github.com/cross-rs/cross?tab=readme-ov-file#dependencies) (rustup and docker or podman).


```console
$ CARGO=cross TARGET=musl just youki-dev # or youki-release
```

### Build without cross-rs

To compile and run, Youki itself depends on some underlying libraries being installed. You can install them using your respective package manager as shown below.
Install the build dependencies and then run:
```console
$ just youki-dev # or youki-release
```

### Debian, Ubuntu and related distributions
Install the build dependencies using your distribution's package manger

#### Debian, Ubuntu and related distributions
```console
$ sudo apt-get install \
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not sure that we need all these dependencies.
IIUC we don't need neither of libsystemd-dev, libelf-dev, libclang-dev or libssl-dev.
Are they needed by any of the tests?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good point. I often forget to update the dependencies. A good way to check is to delete them from there and attempt our CI. When all CI are passed, it means they aren't necessary.
https://github.com/containers/youki/blob/656ccc3f69329c2ed10129e046d0474e6c3dee13/justfile#L153-L160

pkg-config \
Expand All @@ -27,8 +46,7 @@ $ sudo apt-get install \
libssl-dev
```

### Fedora, CentOS, RHEL and related distributions

#### Fedora, CentOS, RHEL and related distributions
```console
$ sudo dnf install \
pkg-config \
Expand All @@ -39,20 +57,33 @@ $ sudo dnf install \
openssl-devel
```

## Runtime requirements

The static binary (musl) builds of youki have no additional runtime requirements. Otherwise you need to install the runtime requirements using your distribution's package manager:

#### Debian, Ubuntu and related distributions
```console
$ sudo apt-get install libseccomp2
```

#### Fedora, CentOS, RHEL and related distributions
```console
$ sudo dnf install libseccomp
```

## Running youki

You can use Youki by itself to start and run containers, but it can be a little tedious, as it is a low-level container runtime. You can use a High-level container runtime, with its runtime set to Youki, so that it will be easier to use. Both of these are explained in the [Basic Usage](./basic_usage.md). For using it along with an high-level runtime, you will to install one such as Docker or Podman. This documentation uses Docker in its examples, which can be installed from [here](https://docs.docker.com/engine/install).

---

## Quick install

Install from the GitHub release.
Note that this way also requires the aforementioned installation.
Install from the GitHub release as root:

<!--youki release begin-->
```console
$ wget -qO youki-0.3.1.tar.gz https://github.com/containers/youki/releases/download/v0.3.1/youki-0.3.1-$(uname -m).tar.gz
$ tar -zxvf youki-0.3.1.tar.gz youki
# Maybe you need root privileges.
$ mv youki /usr/local/bin/youki
$ rm youki-0.3.1.tar.gz
# curl -sSfL https://github.com/containers/youki/releases/download/v0.3.1/youki-0.3.1-$(uname -m)-musl.tar.gz | tar -xzvC /usr/bin/ youki
```
<!--youki release end-->

Expand Down
16 changes: 16 additions & 0 deletions scripts/build.sh
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -42,6 +42,22 @@ if [ "${VERSION}" = release ]; then
OPTION="--release"
fi

# expand target shortcuts
case "$TARGET" in
musl)
TARGET="$(uname -m)-unknown-linux-musl"
;;
gnu|glibc)
TARGET="$(uname -m)-unknown-linux-gnu"
;;
arm64|aarch64)
TARGET="aarch64-unknown-linux-musl"
;;
amd64|x86_64)
TARGET="x86_64-unknown-linux-musl"
;;
esac

FEATURES=()
if [ -n "${features}" ]; then
FEATURES=("--features=${features}")
Expand Down
6 changes: 1 addition & 5 deletions scripts/release_tag.sh
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,11 +13,7 @@ END_MARKER="<!--youki release end-->"


echo "\`\`\`console
\$ wget -qO youki-${VERSION}.tar.gz https://github.com/containers/youki/releases/download/v${VERSION}/youki-${VERSION}-\$(uname -m).tar.gz
\$ tar -zxvf youki-${VERSION}.tar.gz youki
# Maybe you need root privileges.
\$ mv youki /usr/local/bin/youki
\$ rm youki-${VERSION}.tar.gz
# curl -sSfL https://github.com/containers/youki/releases/download/v${VERSION}/youki-${VERSION}-\$(uname -m)-musl.tar.gz | tar -xzvC /usr/bin/ youki
\`\`\`" > replace_content.txt

awk -v start="$START_MARKER" -v end="$END_MARKER" -v newfile="replace_content.txt" '
Expand Down
Loading