libk  Changes To porting

Initial version of "porting"

            1  +# porting libk
            2  +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.
            3  +
            4  +## new architectures
            5  +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.
            6  +
            7  +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 assembeld into the shared library while ones marked "rt" are placed into "boot.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.
            8  +
            9  +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.
           10  +
           11  +## new operating systems
           12  +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.
           13  +
           14  +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.
           15  +
           16  +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>`).