minibase

 small static userspace tools for Linux.

What is this project
~~~~~~~~~~~~~~~~~~~~
This is a base system / early userspace for Linux.

The role of this project in a system is similar to that of busybox
in small custom distributions. Boot the system, load modules, mount
partitions, establish networking, provide basic services. It is aimed
primarily at personal devices running GUIs however.

The project builds into small statically-linked executables with no
external dependencies. There are no build-time library dependencies
either, not even libc. The tools can be built with any toolchain that
can build the kernel.

Supported targets: x86_64 arm aarch64 rv64 mips mips64 i386.
(anything else will not work even if toolchain is available)

This project should be mostly useful for people building their own
custom systems, distribution, or maybe even just looking for tools
to put into initrd.


Project status
~~~~~~~~~~~~~~
The project is ONGOING but not yet complete or even stable.
Components currently included in the package:

  * batch command runner / script interpreter (msh)
  * early-stage boot utils (switchroot, modprobe, mount)
  * block device locating tools (devinit, findblk)
  * block device encryption tools (passblk, dektool, deitool)
  - no fsck for any file system yet
  * system shutdown tool (reboot)

  * top-level process supervisor (svchub)

  * udev event monitor (udevmod)
  * syslog and related tools (sysklogd)

  * VT/DRI/input multiplexer (vtmux) and related tools

  * network interface monitor (ifmon)
  * Wi-Fi client and connection manager (wsupp) [WPA2-PSK only]
  * DHCP client (dhconf)
  * time synchronization (SNTP) service (timed)
  * manual/static interface setup tools (ip4cfg, ip4info) [incomplete]

  * simple interactive shell (cmd).
  * small linux-specific tools (systime, sync, dmesg etc).

  * application supervisors (apphub, ptyhub)

  * package management tools (mpac, mpkg, ctool) [incomplete]

  - no audio tools of any kind.

With everything in place, the system should boot on kernel and minibase alone
to the point where it can run X or Wayland GUI, establish internet connection
and start downloading packages.


Quick start
~~~~~~~~~~~
Bootable images for QEMU (buildroot, minibase, Xorg, Weston) along
with the build scripts are maintained in a dedicated repository:

    https://github.com/arsv/minibase-br/

Get the latest sys-plain or sys-crypt from Releases, check included
instructions. Inspect the build scripts, rootfs and initrd contents
to understand how the system boots.

The images there tend to lag behind the master branch here.
However, those images should still give a pretty good idea of how
the whole thing is supposed to work.


How to build and run the tools
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
For a proper build, run

    ./configure
    make

The final target executables will be located in ./bin.

To try the tools without setting up a VM, configure and build
the project in development mode:

    ./configure devel
    make

Most tools can be run right from their source directories.

Run `make clean` when switching between devel and regular build
to force the objects to be rebuilt with the new compiler flags.

To build only the tools from a particular directory:

    make libs
    make -C src/wsupp

This should be run after configure.


Just how small exactly?
~~~~~~~~~~~~~~~~~~~~~~~
The largest individual executable so far is `wsupp`, the WPA supplicant.
Statically linked for x86_64, it's about 25 KiB in size. Realistically
it also needs `dhconf` (12 KiB) to work, and the client tool `wifi` (16 KiB).

`msh` is about 16 KiB. `cmd` (interactive shell) is about 18 KiB.
`svchub` (pid 1 for the majority of system's uptime) is under 10 KiB.
`vtmux` (logind equivalent) is about 12 KiB.

Why bother making it small? Because it's a side effect of making it readable
and debuggable. The idea is that anyone could pick a tool from minibase,
start reading it and gain complete understanding of how it works in a very
reasonable amount of time, say hours. And if necessary, audit or debug it
down to assembly level. A major point in achieving this is making sure
there are no unnecessary wrappers, useless abstractions or dead code,
which eventually translates into small executables.


Contributing
~~~~~~~~~~~~
This is not a community project. Do not send patches or pull requests.

If there's a bug to be fixed, or a tool that you think should be in minibase,
or a target to support, open an issue.

This will probably change around 1.0 release but not earlier.


Licensing
~~~~~~~~~
GNU Public License version 3, see COPYING.
Limited closed-box license may or may not get added in the future.

The code in lib/sys, lib/bits and lib/arch constitutes the public interface
of the Linux kernel. No claims are made for that code, and it should not be
copyrightable anyway. If unsure, grab corresponding fragments from either
the kernel sources (GPLv2) or the musl libc (MIT license).

The code in lib/crypto is mostly BSD-licensed. See README there.


Credits
~~~~~~~
Dietlibc and "Writing Small and Fast Software" by Felix von Leitner.
https://www.fefe.de/dietlibc/diet.pdf

The project was heavily influenced by busybox at early stages.
Certain decision from skarnet/s6 project also played significant role.
Syscall code (static inline functions with asm volatile blocks)
follows musl, because musl folks got it right.

The Rust coreutils project provided a great deal of inspiration,
specifically by showing how not to write coreutils.


See also
~~~~~~~~
https://busybox.net/
http://www.landley.net/toybox/
http://www.fefe.de/embutils/
http://skarnet.org/software/
http://suckless.org
http://jdebp.eu/Softwares/nosh/
http://b0llix.net/perp/
http://u-root.tk/
https://swtch.com/plan9port/

https://www.gnu.org/software/coreutils/coreutils.html
https://www.kernel.org/pub/linux/utils/util-linux/
https://github.com/uutils/coreutils

https://github.com/mit-pdos/xv6-public (userspace tools)

from https://github.com/arsv/minibase