README

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
~~~~~~~~~~~~~~
Dead-end experimentation.

This project started as an experiment in making a better userspace for Linux,
with a different (compared to mainline) way of running applications. No SUID,
different approach to shells, better isolation. In a way, it was about making
Linux a better OS that it was meant to be.

Back when it started, the Linux kernel was still a decent choice to build
such a project on. Not great, it's definitely not the style of kernel
I would prefer given the choice, but it was acceptable, and there was not
much choice anyway.

Then, Linux (the kernel) took a nosedive.

In its current state, this project only makes sense if the underlying kernel
is worth spending time on. The Linux kernel isn't anymore. The loss of a viable
kernel effectively left the development hanging.

The real next step, would be a lightweight kernel better suited for running
the applications the right way. I might still push this project for some kind
of completion, but only with a much reduced scope, as a no-dependencies toolbox
for small embedded Linux systems I might need to work with.


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)