libk  Artifact [ff246e5f85]

Artifact ff246e5f85c494a065608a2819e78e6518e6be129d6c088808b29192da96027b:

Wiki page [porting] by lexi on 2020-03-04 16:50:19.
D 2020-03-04T16:50:19.162
L porting
N text/x-markdown
P 9748237be19799fdc22140fc22ba9d8a8f29d79393574fdd0da7444f23f67331
U lexi
W 2566
# porting libk
libk is a highly modular library that relies on several layers of abstractions to make porting as easy as possible. porting it to new architectures should be relatively simple, potentially even doable by a single person. porting it to new non-POSIX operating systems is a much more complex task.

## new architectures
the process of porting libk to a new architecture is straightforward. libk relies on a small amount of architecture-specific assembly code to provide the syscall apparatus and basic C runtime. this sounds complicated, but on linux, the files are only a handful of lines long.

the architecture-specific code is in `/mod/kcore`, with various support macros and headers in the `/arch` directory. the file names are structured on the pattern `name.role.arch.os[.bits].s`; this pattern is used by the build script to select the appropriate assembly file for the build target. role must be either "fn" or "rt"; "fn" files are assembled into the shared library while ones marked "rt" are placed into `kboot.o`, the libk version of `crt0.o` which must be statically linked into the program. the fn/rt distinction is not relevant for the `libk.a` static target, and is only used when generating the shared library.

please note that the use of inline assembly is not permitted in libk code as it is an extension, rather than part of the standardized language — not to mention that it's near-unreadable and has poor support for macros or intel syntax, which is used exclusively by libk.

## new operating systems
porting to a new operating system is relatively easy if it's a UNIX system. all that should be required is adding a syscall function for that system's syscall ABI. non-UNIX systems are a different story.

the first step in porting libk to a new operating system is porting its build script. this may be a non-issue on certain partially-POSIX systems like Haiku, which support the bash shell and gcc toolchain in spite of not being a UNIX. systems like Windows will require a full port, however.

once the new build system is in place, you will have to add OS-specific code to all low-level functions that invoke the OS directly, such as `kmheapa()` or `kiosend()`. the header `<k/def.h>` (generated from `/mod/kcore/def.h.m`) provides defines that may be used to detect the current system. to locate system-specific code, simply run the build script — if written correctly, this will generate compile errors from every file that contains system-specific code (via the `Knoimpl()` macro defined in `<k/def.h>`).
Z d0956c76c61955e060c99f261166294c