What is this project
~~~~~~~~~~~~~~~~~~~~
This is an alternative 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, more like systemd.

The project builds into small statically-linked executables with no
external dependencies. There are no build-time library dependencies
either, not even libc. It 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 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

  * process supervision suite (svhub, reboot)

  * udev event monitor (udevmod)
  * syslog and related tools (sysklogd)
  * non-privileged mount service (mountd, pmount)
  * controlled privilege escalation service (suhub, sudo)

  * VT/DRI/input multiplexer (vtmux)
  * simple non-graphical greeter (ctrlvt)

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

  * simple interactive shell (cmd).
  * basic command line tools (cat, ls, du, df etc).
  * small linux-specific tools (systime, sync, dmesg etc).

  - no package manager / download tool yet.
  - 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.


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

    ./configure
    make
    make install     # default DESTDIR is ./out

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 -C src/wifi
    make -C src/wifi install

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.
`svhub` (pid 1 for the majority of system's uptime) is about 10 KiB.
`vtmux` (logind equivalent) is about 12 KiB.

Why bother making it small? Because it's a side effect of making it readable.
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 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)