current nightly

NAME

development — operating system development instructions

SYNOPSIS

/src

DESCRIPTION

Releases come with the system source code in /src as a git(1) repository. It can be modified, compiled and installed on the current system. The source code is built with a make(1) build system. The source code can be located in any location, if so, simply substitute /src with the real location. These instructions only apply to building the operating system from within itself, those building it from another operating system needs to follow cross-development(7) instead.

If you are building a new version of the operation system where build tools have been added or changed, you first need to install the new tools. This is not needed when building the matching release. To do so, run as root:

    cd /src 
    make distclean            # fully clean build directory 
    make install-build-tools  # install new tools 
    make clean-build-tools    # clean for real build below

To build the base operating system and upgrade the current system, run as root:

    cd /src 
    make            # build new operating system in /src/sysroot 
    make sysmerge   # upgrade current operating system with /src/sysroot

The build system creates a minimal root filesystem structure in the /src/sysroot and builds each operating system component in turn, installing them into the sysroot. If the source code for ports are placed in /src/ports then they are automatically built as well. The result is a minimal system that can be turned into working system by adding important configuration such as passwd(5).

The sysmerge make target ensures a system is built in /src/sysroot and then runs the sysmerge(8) program which installs the new system files onto the existing system. It updates the system manifest as well all ports installed in the sysroot. The initrd(7) is automatically regenerated using update-initrd(8). The bootloader, if enabled in upgrade.conf(5), is reinstalled and configured as necessary. The new user-space is running on completion, though existing processes will be running the old programs. A reboot is needed to run the new kernel. If the ABI changed and the current kernel isn't able to run the new programs, then the upgrade is delayed and will be automatically completed on the next boot. The sysmerge-wait make target forces waiting until the next boot.

Root Makefile

The /src/Makefile handles the high level build of the operating system. The important targets are:

The important environment variables influencing the Makefile are:

Components

The operating systems components, such as libc and the kernel, each have their own directory by that name. It contains a makefile that can build and install that component. This allows building and installing only that component onto the current operating system.

For instance, to build and install libc, run as root:

    cd /src/libc 
    make 
    make install

System libraries are statically linked and you will have to relink programs with the new library for changes to take effect. Building the whole operating system from the root makefile ensures components are built in the right order such that all programs use fresh libraries. The root makefile invokes component makefiles with SYSROOT set to /src/sysroot to force the compiler to locate files there. Likewise when installing, it sets DESTDIR to /src/sysroot to make it install files there.

Directories

In addition to the directories for each operating system component, there are these special directories:

Build Tools

Some components are used to build the source code and must match the versions in the source code being built. These are currently:

carray
kblayout-compiler
mkinitrd
sf
tix

If the currently installed versions of those tools are older than the ones in the source code, you must update them. The clean-build-tools root makefile target cleans the applicable directories, the build-tools root makefile target builds them from the source code, and the install-build-tools root makefile target installs the new version. You must clean the compiled files from the source code afterwards because the compiled tools are intended to run on the current system, and have not been built properly using /src/sysroot.

Ports

You can place the source code for ports in srctix(7) format (has a tixbuildinfo(7) file) in the /src/ports directory and they will get built automatically when and installed into the sysroot when building the whole operating system. Installable binary packages are created in the /src/repository/$HOST directory using tix-build(8) directory and can be installed with tix-install(8). If an existing binary package exists in the repository, it is used instead of the building the port again.

Ports are currently made using cross-development(7) as not all ports can be built natively yet.

The ports system is described in detail in porting-guide(7).

Patches

The source code is managed as a git(1) repository and you can make your own changes and commit them. A good approach is to set up your own local development branch and work there:

    git checkout -b local 
    git add utils/hello.c 
    git commit -m 'Add hello(1).'

You can then easily prepare your a set of patches for upstream submission:

    git format-patch master..local

This will create a series of .patch files containing your changes. Review them and rewrite git history as needed until they are of submittable quality. You can then submit them for review at the official website.

To transfer files out of the operating system, you can either mount the local root filesystem from another operating system with networking, or you transmit the patches over the serial connection as described in serial-transfer(7).

Releases

CD-ROM release of the operating system can be built with the iso root makefile target. This will build the whole operating system, if not done already, and produce a bootable iso for the current architecture in the /src/builds directory. The sortix.iso root makefile target will do the above and place a sortix.iso file in the current directory.

The release root makefile target will run the iso target and prepare a /src/release directory with a directory structure and miscellaneous files suitable for a formal online release.