Differences From
Artifact [a1a4077789]:
122 122
123 123 other assemblers will probably be necessary for the more exotic targets, however.
124 124
125 125 # repository structure
126 126
127 127 libk uses a strict directory structure for code, and deviations from this structure will not be tolerated without extremely good reason.
128 128
129 -total segregation is maintained between source code, temporary files, and output objects. source is found in module directories (`k*/`). the destination for temporary files and output objects are retargetable via the environment variables `gen= out=`, but default to `gen/` and `out/`, which are excluded from repo with fossil's `ignore-glob` settingapproval of the maintainer herself.
129 +total segregation is maintained between source code, temporary files, and output objects. source is found in module directories (`k*/`). the destination for temporary files and output objects are retargetable via the environment variables `gen= to=`, but default to `gen/` and `out/`, which are excluded from repo with fossil's `ignore-glob` settingapproval of the maintainer herself.
130 130
131 131 all libk code is dispersed into modules: `kcore` for internals, `kio` for I/O, `kgraft` for binary packing, etc. each module has a folder in the root directory. (libk does not have submodules.) inside each module's directory should be a header with the same name as the module (see **naming conventions** above).
132 132
133 133 each function should be kept in a separate file within its module's directory. the file's name should consist of the dot-separated fields [name, class, "c"] for C sources, or [name, class, arch, OS, bits, format, "s"] for assembly sources, where "name" is the name of the function without the module prefix and "class" is `rt` if the file is part of the libk runtime, or `fn` otherwise. this distinction is necessary because while the static library `libk.a` can include runtime objects, the shared library `libk.so` cannot. examples:
134 134
135 135 * a C file in the module `kstr` named `kscomp` would be named `kstr/comp.fn.c`
136 136 * a runtime assembly file called `boot` in the module `kcore` for x86-64 linux would be named `kcore/boot.rt.x86.lin.64.s`
137 137 * the 32-bit x86 haiku version of a function called `kiowrite` defined in assembly would be named `kio/write.fn.x86.hai.32.s`.
138 138
139 139 each module should have a header named the same thing as the module except without the `k` prefix. (e.g. the header for `kio` is `kio/io.h`) located in its folder. this is the header that the end-user will be importing, and should handle any user-defined flags to present the API the user has selected.
140 140
141 141 each module should contain a markdown file. this file's name should be the name of the parent directory suffixed with `.md`; for instance, `kterm` should contain the file `kterm/kterm.md`. this file should document the module as thoroughly as possible
142 142
143 -each module may contain any number of files of the name `*.exe.c`. this files will be treated as *tools* by the build system and compiled as executables, rather than libraries. they should be compiled to `out/$module.$tool`
143 +each module may contain any number of files of the name `*.exe.c`. this files will be treated as *tools* by the build system and compiled as executables, rather than libraries. they should be compiled to `$to/$module.$tool`
144 144
145 145 the repository root and each module may also contain the directory `misc`. this directory may be used to store miscellaneous data such as ABI references, developer discussions, and roadmaps. if the `misc` directory is deleted, this must not affect the library or build system's function in any way - that is, nothing outside a `misc` folder may reference a `misc` folder or anything inside it, including documentation. the `misc` directory should be removed when its contents are no longer needed. in most cases, the repository wiki and forum should be used instead of the `misc` folder.
146 146
147 147 the folder `arch` in the root of the repository contains syscall tables and ABI implementations for various architectures.
148 148
149 149 # build system
150 150
................................................................................
164 164
165 165 * `os={atom}` - an atom representing the operating system you are building libk for
166 166 * `arch={atom}` - an atom representing the processor architecture you are building libk for
167 167 * `bits={atom}` - if your processor has multiple variants with different word lengths (such as x86-32 vs. x86-64), specify the word length in this variable; otherwise, leave it unset.
168 168
169 169 further optional variables may be set to control the build process and determine what targets it produces.
170 170 * `library=static {static|shared|both}` - this variable controls whether the build process will produce `libk.a`, `libk.so`, or both.
171 - * `out=out {path}` - an alternate path to store build artifacts in
171 + * `to=out {path}` - an alternate path to store build artifacts in
172 172 * `gen=gen {path}` - an alternate path to store generated source in
173 173 * `cc=<autodetect> {executable}` - the compiler to compile C sources with
174 174 * `m4=<autodetect> {executable}` - the m4 binary to compile the macro sources with
175 175 * `asm=<autodetect> {executable}` - the assembler to assemble the assembly listings with. it must take Intel-syntax input and handle nasm-style macros. only `yasm` and `nasm` are likely to be viable.
176 176 * `doc=yes {yes|no}` - whether to typeset the documentation (very slow with all three formats set to "yes")
177 177 * `doc_html=yes {yes|no}` - enable or disable html output of the documentation
178 178 * `doc_pdf=yes {yes|no}` - enable or disable pdf output of the documentation