Preface

What is this?

HitchHiker Linux is a general purpose Linux distribution that has been carefully assembled to give a more traditional, Unix-like experience. HitchHiker provides, out of the box, all development tools and libraries to rebuild itself from source code as well as being a solid base from which to create whatever system is desired.

Introduction

#!/don't/panic
man 42

HitchHiker Linux is a very Unix-like distribution of Linux with a focus on simplicity, elegance and providing a solid base that the end user can turn into whatever they see fit.

Core Principles:

  • The default installation should include the bare minimum required software to provide a solid base.
  • Complexity should be discouraged in favor of code elegance, security and maintainability.
  • End users should not be discouraged from tinkering with their system.
  • The distribution should make as few assumptions as possible regarding end use.
  • While newer releases of software often eliminate bugs and vulnerabilities, newer software packages are not by default more secure than stable, mature packages (newer is not always better).
  • Any changes to the core system functionality, especially those which change expected functionality, must be well justified and well vetted before deployment.
  • The base installation should include everything required to rebuild itself from source.
  • The distribution should make as few changes to the upstream software as possible, delivering it as intended by the original author.
  • Patching of sources should only be done to fix bugs or vulnerabilities.

HHL was born of a desire to harness the greater hardware support of Linux while paying respect to the Unix systems from which Linux was born. The author was a long time user of FreeBSD who migrated to Arch for several years, but has become increasingly frustrated with Systemd, Gnome, RedHat and Ubuntu dominance. It is believed that there is a need for a distribution that does not pander to ease of use for casual users at the expense of putting up roadblocks for experienced Unix veterans.

Architectures

HHL is running on the following processor architectures:

  • x86 (minimum i486)
  • x86_64
  • armv7l
  • aarch64
  • riscv64

Target Audience

My first computer was a Tandy TRS-80 handed down from an uncle. The interface consisted of a blinking cursor on a monochrome screen, and it had no storage beyond RAM and ROM. Whatever you could type into memory before shutting it off and run with the included Basic interpretor was the extent of the software that ran on that computer. As limited as it was, it was fascinating to me.

In this day and age an interface consisting of a blinking cursor without wallaper, icons, notifications and voice input is bewildering to the average human. Nevertheless, that is the interface that a fresh installation of HItchHiker will always present to the user. Therefore, it can be reasoned that the target audience will consist of individuals who either are comfortable with using a command line interface or are eager to learn. Some proficiency using Linux or Unix is helpful, but not 100% necessary given an ability and willingness to read the documentation and get used to being "close to the machine".

Indeed, HitchHiker will not do any kind of hand holding while you are installing and using your new system. You will be expected to learn the hows and whys of what makes a computer work. Most operating systems, including the majority of Linux distributions, will gladly install, configure, and run 100s of programs without your ever being aware that they are doing it. By the time you have achived proficiency with HitchHiker, you will know what every running process is for and why it is needed.

What's Included

  • A full C and C++ development environment including compiler, headers and libraries.
  • Up to date versions of kernel, base libraries and toolchain components.
  • Where possible, BSD and historical Unix utilities have been incorporated.
  • Full documentation is included for all included software.
  • The HitchHiker build system is capable of bootstrapping itself from another Linux distro or from HitchHiker itself, and is available for x86, Arm and RiscV architectures.

What's Missing

  • Systemd - HitchHiker uses the S6 supervision suite and a minimal init.
  • No installer - HitchHiker is installed using Unix command line tools present on any Linux distribution.
  • No apt, rpm, dnf, pacman, etc. HitchHiker uses NetBSD Pkgsrc for installing extra software.
  • No daemons beyond what is required to provide a functional command prompt are started by default.
  • No extra configuration is done to provide a "consistent look and feel" or any such crap. The Linux world is full of choices. Unfortunately, among the hundreds of installable offerings the vast majority are "vanity distros" which are just a remix of another distribution, with a different set of installed packages and a few cool wallpapers.

HitchHiker on the other hand is not based on any other distribution of Linux. It is a fully independent offering which tracks the most recent releases of the Linux kernel, Glibc, GCC etc. It's smaller userland utilities have been mostly ported from BSD or implemented from scratch. It's source tree can compile the entire operating system with a single command using Makefiles. We strive for an active and independent presence and want to push open source into new and exciting frontiers, such as RiscV, while paying homage to classic Unix. While there are other offerings that cover some of the same territory (Arch, Gentoo) we felt that there was space for something different.

Installation

Binary

Downloading Hitch Hiker Linux binary tarballs

x86

The x86 platform includes all 32-bit Intel and Intel compatible processors ranging from i386 to i786 processors. For the purposes of installation, the x86_64 architecture, including all AMD64 and Intel 64-bit processors, is identical in function and included in this page.

NOTE:

Please note that the minimum supported processor is i486. This is not a limitation specific to HitchHiker, but a limitation of the Linux Kernel itself and Glibc. Should you have a computer of this vintage, and wish to get it running, you have the choice of installing an older and likely unsupported distribution, or installing an operating system descended from 4.4BSD (FreeBSD, NetBSD, and OpenBSD).

Arm

Raspberry Pi

Riscv

Qemu

BeagleV

Source

The Build Process

This section describes the steps that the HitchHiker build tree takes when building itself from source. Note that this is not a list of the commands that must be run by the user, those are actually quite simple. Rather, this page is here because it is both useful and reasshuring to understand what is being done when one does run the commands.

It is expected that certain programs are available on the host system, ie the system that HitchHiker is being built on. In the case that certain programs do not exist, those programs are compiled in the 'bootstrap' portion of the build. HitchHiker puposely keeps this part light and prefers to use the native tools of the host.

In the second half of the bootstrap phase, a sysroot compiler and linker is built and installed under /toolchain. This toolchain may or may not be a cross toolchain, but in either case is of the same version of gcc and binutils as are to be used in the finished system and are built in such a way that they search for headers and libraries under /src/build rather than /.

In the case that we are compiling for an architecture that is different than the one which is being used to build the system, this toolchain is what is known as a cross toolchain. What this means is that the compiler and linker run on our build machine (the machine performing the build) but produce machine code that runs on our host machine (the machine the finished system will in fact run on).

The actual build of the sysroot compiler takes place in several steps:

  1. The binutils package, which contains our linker and assembler.
  2. A temporary and minimally capable gcc compiler is built, which is only capable of building our C library.
  3. The linux kernel headers are installed into our sysroot.
  4. The temporary gcc and binutils built in step 1 are used to build glibc, which is installed into our sysroot.
  5. The final sysroot gcc compiler is built, which is a fully capable C and C++ compiler for our final system.

We then use the toolchain and bootstrap tools that we have built to compile the rest of the final system and install it into our sysroot.

Downloading the Hitch Hiker Linux source

The Hitch Hiker Linux source code is available as an xz compressed tarball from the hitchhiker-linux.org website, or can alternatively be cloned from the main git repository.

The current stable source tarball can be fetched using wget:

wget -c https://hitchhiker-linux.org/pub/stable/src/src.tar.xz
tar -xJf src.tar.xz

Alternatively, should one wish to build the most recent development version of HitchHiker, the source can be checked out via git over https.

git clone https://git.hitchhiker-linux.org/hitchhiker/src.git

NOTE:

Currently, the build tree expects to be located in the top level directory /src, and it is therefore necessary to either cd / prior to running the previous commands, or else to bind mount the actual source directory onto /src prior to building. This requirement may be changed in the future in order to increase flexibility.

Preparing to Build

If Hitch Hiker is being built on a Linux system other than itself, the following software is expected to be present:

  • Binutils - version 2.25 or greater
  • Bison - version 2.7 or greater
  • a functional bzip2 and bunzip2 command
  • a functional diff command
  • a functional find command
  • Gcc - version 6.2 or greater
  • a functional grep command
  • a functional gzip and gunzip command
  • Linux kernel version 3.2 or greater
  • M4 - version 1.4.10 or greater
  • GNU make
  • a functional patch command
  • GNU sed is required to build the Linux kernel
  • a functional tar command
  • Texinfo - version 4.7 or greater
  • a functional xz and unxz command Change directory to /src and create your config.mk file by copying config.mk.sample and editing it appropriately. The comments in the sample explain what each variable does.
cd /src
cp config.mk.sample
vi config.mk

As a final step before building, it is neccessary to prepare the environment in which we are going to build Hitch Hiker. There is a script provided for this purpose which cleans up some environment variables and sets one MAKEFLAG in order to let make find our include files.

source scripts/setenv.sh

Building HitchHiker

Post Install Configuration

Adding a User Account

Setting up Networking

Managing Processes

Installing Third Party Software

Hitch Hiker uses the pkgsrc framework for installing extra software on top of the base system. Contrary to what is common in the world of Linux, there is a clear distinction between the base system and all third party packages. This, in turn, allows for more developer focus on the base system and less time packaging software. This is the model followed by all of the various BSD systems, where the base system and packages are considered to be separate projects.

What is Pkgsrc

Pkgsrc is a cross platform framework for packaging and installing third party software which is developed and maintained by the NetBSD project. Currently it works on all BSD systems, Minix, Darwin,MacOS X, and Linux to name a few, across multiple architectures.

Further Reading

In addition to this chapter you are highly encouraged to read The pkgsrc guide and keep it handy as reference, as a full reference to pkgsrc is beyond the scope of this chapter.

Getting Pkgsrc

The current stable pkgsrc can be downloaded from this link. It should then be extracted to /usr/pkgsrc.

wget -c http://cdn.netbsd.org/pub/pkgsrc/stable/pkgsrc.tar.bz2
tar -xjf pkgsrc.tar.bz2 -C /usr

Bootstrapping Pkgsrc

Before installing packages from source or from binary, it is necessary to bootstrap pkgsrc. This is neccessary in order to build the tools that pkgsrc requires which are not a part of the Hitch Hiker base system.

cd /usr/pkgsrc/bootstrap
./bootstrap

Once this is done it is necessary to either reload the shell startup files or log out and back in again, in order to add /usr/pkg/bin and /usr/pkg/sbin to our $PATH.

exec zsh --login

As a final step, it is neccessary to add /usr/pkg/lib to the default linker path. This path is configured in /etc/ld.so.conf and can be extended with files placed in /etc/ld.so.conf.d. Finally, after configuring the linker paths, we run ldconfig to update the linker's cache of shared libraries.

install -d /etc/ld.so.conf.d
echo '/usr/pkg/lib' > /etc/ld.so.conf.d/pkgsrc.conf
ldconfig

NOTE:

Ordinarily the preceding command would be run as the root user. It is, however, possible to install packages as an unprivileged user by first making the package prefix directory writable by that user. In the case of a normal installation this would entail creating /usr/pkg and transferring ownership of it using the chown command before bootstrapping pkgsrc. It is also possible to bootstrap pkgsrc in one's own home directory. However, as this will break compatability with any provided binary packages it is therefore discouraged.

Installing Binary Packages

It is entirely possible to skip this step if one wishes to build all software from source. However, should one wish to work with binary packages provided by Hitch Hiker, it is recommended that the first package built be the pkgin package manager.

zaphod@magrathea% cd /usr/pkgsrc/pkgtools/pkgin
zaphod@magrathea% bmake install clean clean-depends

To configure pkgin, edit the file /usr/pkg/etc/pkgin/repositories.conf to point towards the package repository appropriate for your architecture and version of Hitch Hiker. The hitchhiker-linux.org server is structures as follows:

pub
└── 2021q2              # Release version
    ├── src             # Source tree
    ├── aarch64         # Architecture
    │   ├── packages
    │   │   └── All     # Package repository
    │   ├── release     # Release tarballs

Therefore, if the Hitch Hiker release was 2021q2 and the architecture of your machine was riscv64, the repository can be added with the following command:

zaphod@magrathea% echo 'http://hitchhiker-linux.org/pub/2021q2/riscv64/packages/All' \
  >> /usr/pkg/etc/pkgin/repositories.conf

Once pkgin is installed and configured it functions similarly to any good package manager one might have previously used under Linux, such as apt or pacman. To see the list of possible operations just run the pkgin command without arguments:

zaphod@magrathea% pkgin
Usage: pkgin [-cdfhlnPtvVy] command [package ...]

Commands and shortcuts:
list                (ls  ) - List installed local packages
avail               (av  ) - List all available remote packages
search              (se  ) - Search for a remote package
install             (in  ) - Install or upgrade packages
update              (up  ) - Refresh local and remote package lists
upgrade             (ug  ) - Upgrade all packages
full-upgrade        (fug ) - Upgrade all packages (deprecated)
remove              (rm  ) - Remove packages and any dependent packages
keep                (ke  ) - Mark packages that should be kept
unkeep              (uk  ) - Mark packages that can be autoremoved
export              (ex  ) - Display PKGPATH for all keep packages
import              (im  ) - Import keep package list from file
show-keep           (sk  ) - Display keep packages
show-no-keep        (snk ) - Display autoremovable packages
autoremove          (ar  ) - Remove orphaned dependencies
clean               (cl  ) - Remove downloaded package files
show-deps           (sd  ) - List remote package direct dependencies
show-full-deps      (sfd ) - List remote package full dependencies
show-rev-deps       (srd ) - List local package reverse dependencies
provides            (prov) - Show which shared libraries a package provides
requires            (req ) - Show which shared libraries a package requires
show-category       (sc  ) - List all packages belonging to a category
show-pkg-category   (spc ) - Show categories a package belongs to
show-all-categories (sac ) - List all known categories
pkg-content         (pc  ) - Show remote package content
pkg-descr           (pd  ) - Show remote package long-description
pkg-build-defs      (pbd ) - Show remote package build definitions
stats               (st  ) - Show local and remote package statistics
zaphod@magrathea%

Building Source Packages

The first step in building a package is to locate the directory within the pkgsrc tree that contains that package, and then entering that directory. There is a provided search utility called pkglocate which can be used to do a keyword search. However, in practice pkglocate is not a very effective search tool.

A much better search tool can be found at pkgtools/pkgfind. To install it:

cd /usr/pkgsrc/pkgtools/pkgfind
bmake install clean clean-depends

Now running pkgfind <searchterm> should return a much better list of search results.

NOTE:

It is good practice to always run the clean and clean-depends targets after running bmake install, to avoid leaving old work directories all over the tree As demonstrated by our installation of pkgfind, the general procedure to build a package using pkgsrc is to:

  1. Locate the directory containing the package we wish to install.
  2. cd into that directory
  3. Run bmake install in that directory.

NOTE:

We run bmake as opposed to just make because pkgsrc uses the NetBSD version of the make utility, which supports somewhat different Makefile syntax than GNU make.

Extending Pkgsrc

While pkgsrc contains an extensive collection of software out of the box, there are times when there are packages that have not yet been packaged or have build failures on Hitch Hiker. For those feeling somewhat adventurous, here are two ways to extend the available packages, providing software not in the default distribution or alternative packages with Hitch Hiker specific bug fixes.

pkgsrc-wip

The pkgsrc-wip project is a collection of work in progress packages which for one reason or another have not yet been accepted into the main distribution. Much of the time these packages are perfectly functional, but might not work on every OS that pkgsrc supports. The pkgsrc-wip repository is managed via git, and due to the main pkgsrc framework being managed under CVS it is safe to clone pkgsrc-wip right into pkgsrc.

cd /usr/pkgsrc
git clone https://pkgsrc.org/wip/ wip

This will put all of pkgsrc-wip right inside pkgsrc at /usr/pkgsrc/wip. Once there, using wip is exactly the same as using the rest of pkgsrc.

pkgsrc-hhl

The pkgsrc-hhl project is and extension to pkgsrc containing packages that are intended specifically for Hitch Hiker. These packages may add functionality not available in pkgsrc, fix build issues, or integrate packages from pkgsrc better with Hitch Hiker. Installation and usage of pkgsrc-hhl is similar to pkgsrc-wip.

cd /usr/pkgsrc
git clone https://git.hitchhiker-linux.org/hitchhiker/pkgsrc-hhl.git hhl

Updating HitchHiker Linux

From Binary Sets

From Source