Skip to content

INSTALL.md

Latest commit

 

History

History
145 lines (105 loc) · 4.57 KB

INSTALL.md

File metadata and controls

145 lines (105 loc) · 4.57 KB

Quick Install with Cargo

A quick installation of the stg binary may be performed with cargo:

$ cargo install --path=.

The above will install the stg executable to ~/.cargo/bin, by default. The --root option, CARGO_INSTALL_ROOT environment variable, or install.root Cargo config value may be used to change where StGit is installed.

The --locked option may be passed to cargo install to used the specific dependency versions from the Cargo.lock file, otherwise the latest semver-compatible versions of StGit's dependencies will be used.

Full Installation

A more comprehensive installation of StGit, including man pages, shell completions, and html documentation may be achieved using various Makefile targets.

To install the stg binary and man pages:

$ make install install-man

By default, StGit is installed to the $HOME/.local/{bin,share} directories, as specified by the systemd file-hierarchy and XDG Base Directory specs. To install elsewhere, the prefix variable can be set:

# make prefix=/usr/local install install-man

Shell completions may be installed with the install-completion target and html documentation with the install-html target. The install-all target installs the executable, man pages, html documentation, and shell completions.

In addition to prefix, the DESTDIR variable may be used to re-root the installation to another directory. Using DESTDIR is most applicable when building StGit in the context of a packaging system (e.g. a Debian or RPM package).

An example of a complete installation of StGit:

$ make DESTDIR=/tmp/stgit-build prefix=/usr install-all

AsciiDoc and AsciiDoctor

In addition to the Rust toolchain to build the stg executable, to build and install the documentation, AsciiDoc or AsciiDoctor along with xmlto is required.

By default the documentation is built using asciidoc, but asciidoctor is also supported and may be enabled by using the USE_ASCIIDOCTOR make variable.

$ make USE_ASCIIDOCTOR=1 install-man

Debian and RPM Packages

The top-level Makefile has targets for building Debian and RPM packages. None of the distributions that use Debian and RPM packaging provide StGit 2.x (or 1.x) packages. The deb and rpm packages built from the StGit repository are meant to fill that gap.

These StGit-provided packages do not necessarily conform to all of the packaging standards of those distributions. That said, an effort is made to properly install man pages, shell completions, and vim files in addition to the stg executable.

In order to be maximally portable, the stg executable in these packages is statically linked using musl.

The following Makefile targets are available to build packages:

  • packages: build deb and rpm packages for all supported architectures
  • debs: build deb packages for all supported architectures
  • rpms: build rpm packages for all supported architectures
  • deb-i686: build stgit_x.y.z_i386.deb
  • deb-x86_64: build stgit_x.y.z_amd64.deb
  • deb-aarch64: build stgit_x.y.z_arm64.deb
  • deb-riscv64: build stgit_x.y.z_riscv64.deb
  • rpm-i686: build stgit-x.y.z-w.i686.rpm
  • rpm-x86_64: build stgit-x.y.z-w.x86_64.rpm
  • rpm-aarch64: build stgit-x.y.z-w.aarch64.rpm
  • rpm-riscv64: build stgit-x.y.z-w.riscv64.rpm

The generated package files are output to target/pkg/.

Rust Dependencies

To build these packages, rust needs to be setup for some additional targets:

  • aarch64-unknown-linux-musl
  • riscv64gc-unknown-linux-musl
  • i686-unknown-linux-musl
  • x86_64-unknown-linux-musl

If using rustup, these targets can be added by with rustup target add.

Cargo Dependencies

The cargo-deb and cargo-generate-rpm crates are used to generate the deb and rpm packages, respectively. These may be installed using cargo install.

Linker Setup

When cross-compiling, e.g. when building aarch64 or riscv64 targets from an x86_64 host, the cross compiler linker needs to be installed and configured.

On Arch Linux, install aarch64-linux-gnu-gcc and riscv64-linux-gnu-gcc.

In Debian/Ubuntu environments, install the gcc-aarch64-linux-gnu and gcc-riscv64-linux-gnu packages.

To configure, add the following to your ~/.cargo/config.toml file:

[target.aarch64-unknown-linux-musl]
linker = "aarch64-linux-gnu-gcc"

[target.riscv64gc-unknown-linux-musl]
linker = "riscv64-linux-gnu-gcc"