Sortix nightly manual
This manual documents Sortix nightly, a development build that has not been officially released. You can instead view this document in the latest official manual.
DEVELOPMENT(7) | Miscellaneous Information Manual | DEVELOPMENT(7) |
NAME
development
—
operating system development instructions
SYNOPSIS
/srcDESCRIPTION
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
cd /src make # build new operating system in /src/sysroot make sysmerge # upgrade current operating system with /src/sysroot
Root Makefile
The /src/Makefile handles the high level build of the operating system. The important targets are:- all
- (default) Build each component in turn and install them into the sysroot.
- available-ports
- Search for newer available versions of ports.
- build-tools
- Make all build tools.
- clean
- Clean the component directories and the port source code. (clean-core, clean-ports)
- clean-build-tools
- Clean the directories of all build tools.
- clean-cross-compiler
- Clean the directories for the cross-compiler.
- clean-cross-toolchain
- Clean the directories for the build tools and cross-compiler. (clean-build-tools, clean-cross-compiler)
- distclean
- Run every clean target such that the source code is ready for distribution. (clean-builds, clean-core, clean-mirror, clean-release, clean-repository, clean-sysroot, distclean-ports, clean-cross-compiler)
- distclean-ports
- Remove the port source code extractions.
- extract-ports
- Extract the upstream release for each port(5) in /src/ports and apply the appropriate patches.
- install-build-tools
- Install all build tools after making them.
- install-cross-compiler
- Install the cross-compiler after making it.
- install-cross-toolchain
- Install the build tools and cross-compiler after making them. (install-build-tools, install-cross-compiler)
- iso
- Create a release iso in the /src/builds directory after making all.
- mirror
- Download the upstream release for each
port(5) in
/src/ports from
SORTIX_PORTS_MIRROR
into the /src/mirror directory. The operating system can be built without network connectivity once the mirror is populated. The local mirror has the same structure as the remote mirror and can be used as a remote mirror. - mostlyclean
- Clean everything except binary packages and the mirror of upstream releases. (clean-builds, clean-ports, clean-release, clean-sysroot, distclean-ports, clean-cross-compiler)
- presubmit
- Verify the port configuration (verify-ports), the coding style is followed (verify-coding-style), the manual pages does not have lints (verify-manual), the build tools compile (verify-build-tools), that everything compiles without warnings on all architectures (verify-build), and the system headers works in all supported configurations (verify-headers).
- release
- Make iso and construct release directory tree in /src/release suitable for online publishing.
- sortix.iso
- Make iso and place it in the current directory as sortix.iso.
- sysmerge
- Upgrade the current operating system using the sysroot after making the all target.
- sysmerge-full
- Like sysmerge but do a full operating system
upgrade that uninstalls ports not present in the sysroot using
--full
. - sysmerge-full-wait
- The combination of sysmerge-full and sysmerge-full-wait.
- sysmerge-wait
- Like sysmerge but delay the upgrade until the
next boot using
--wait
. - sysroot-base-headers
- Create the sysroot and install only the headers of the standard library and kernel into it. This is useful when bootstrapping the runtime libraries of the compiler that need to know about libc prior to building libc.
- upgrade-ports
- Search for newer available versions of ports and update the VERSION variable in the port(5) and switch it into development mode.
BUILD
- The platform of the current operating system. This defaults to the current machine and operating system.
HOST
- Specifies platform on which the compiled code will run. This defaults to
the current machine and operating system. This is used when
cross-compiling the operating system. When cross-compiling the operating
system, it must be set to one of i686-sortix
and x86_64-sortix. This must be unset when
building the build tools as they run on the current operating system. The
compiler tools are prefixed with this variable if it does not match
BUILD.
OPTLEVEL
- Specifies compiler optimization options that gets added to
CFLAGS
andCXXFLAGS
. PACKAGES
- Specifies which ports to build, or all ports if unset. Suffixing a port with a ‘!’ includes its mandatory dependencies, and suffixing it with ‘!!’ includes the optional dependencies as well. The sets of ports defined in /src/build-aux/ports.conf can be specified as well. For instance PACKAGES=minimal! builds all the minimal ports with no optional dependencies.
SORTIX_INCLUDE_SOURCE
- Specifies whether the source code is included in the sysroot. This must be one of no, yes or git and defaults to git if git(1) is installed and yes otherwise.
SORTIX_ISO_COMPRESSION
- Specifies the compression algorithm used in iso files. This must be one of none, gzip or xz and defaults to xz.
SORTIX_PORTS_MIRROR
- Upstream releases of ports are downloaded from this mirror, defaulting to the official mirror, and falling back to the upstream release site if the mirror failed.
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
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:- /src/builds
- The build artifacts produced when building the operating system.
- /src/mirror
- The upstream releases of ports are downloaded on the first use and cached inside this mirror directory.
- /src/ports
- Each subdirectory contains a
port(5) which is
automatically built along with the operating system per the
PACKAGES
environment variable. - /src/release
- The release root makefile target creates this directory and populates it with a directory structure suitable for online publishing of a release.
- /src/repository
- This directory stores the binary packages and is created when they are built. This works as a cache so ports don't have to be rebuilt every time the operating system is. Packages are also copied from here rather than the sysroot when making releases.
- /src/sysroot
- This directory is made when building the operating system and the freshly made files are installed here. The build system uses this as the system root which forces the compiler to look here for headers and libraries. This ensures a clean bootstrap where files from the current operating system do not leak into the new system.
- /src/sysroot-overlay
- If this directory exists, it is added to the initrd of the produced iso and can contain additional system files.
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
Ports
Each port(5) in the /src/ports directory 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-port(8) and can be installed with tix-install(8). If an existing binary package with the right version exists in the repository, it is used instead of the building the port again. The ports system workflow is described in porting(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).'
git format-patch master..local
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.Following Development
The following-development(7) manual page documents what needs to be done to stay updated with the latest developments. You will need to read the new version of that document whenever you update the source code.SEE ALSO
git(1), make(1), port(5), cross-development(7), following-development(7), installation(7), porting(7), serial-transfer(7), upgrade(7), sysinstall(8), sysmerge(8), update-initrd(8)December 29, 2015 | Debian |