122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
...
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
|
other assemblers will probably be necessary for the more exotic targets, however.
# repository structure
libk uses a strict directory structure for code, and deviations from this structure will not be tolerated without extremely good reason.
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.
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).
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:
* a C file in the module `kstr` named `kscomp` would be named `kstr/comp.fn.c`
* a runtime assembly file called `boot` in the module `kcore` for x86-64 linux would be named `kcore/boot.rt.x86.lin.64.s`
* the 32-bit x86 haiku version of a function called `kiowrite` defined in assembly would be named `kio/write.fn.x86.hai.32.s`.
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.
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
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`
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.
the folder `arch` in the root of the repository contains syscall tables and ABI implementations for various architectures.
# build system
................................................................................
* `os={atom}` - an atom representing the operating system you are building libk for
* `arch={atom}` - an atom representing the processor architecture you are building libk for
* `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.
further optional variables may be set to control the build process and determine what targets it produces.
* `library=static {static|shared|both}` - this variable controls whether the build process will produce `libk.a`, `libk.so`, or both.
* `out=out {path}` - an alternate path to store build artifacts in
* `gen=gen {path}` - an alternate path to store generated source in
* `cc=<autodetect> {executable}` - the compiler to compile C sources with
* `m4=<autodetect> {executable}` - the m4 binary to compile the macro sources with
* `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.
* `doc=yes {yes|no}` - whether to typeset the documentation (very slow with all three formats set to "yes")
* `doc_html=yes {yes|no}` - enable or disable html output of the documentation
* `doc_pdf=yes {yes|no}` - enable or disable pdf output of the documentation
|
|
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
...
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
|
other assemblers will probably be necessary for the more exotic targets, however.
# repository structure
libk uses a strict directory structure for code, and deviations from this structure will not be tolerated without extremely good reason.
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.
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).
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:
* a C file in the module `kstr` named `kscomp` would be named `kstr/comp.fn.c`
* a runtime assembly file called `boot` in the module `kcore` for x86-64 linux would be named `kcore/boot.rt.x86.lin.64.s`
* the 32-bit x86 haiku version of a function called `kiowrite` defined in assembly would be named `kio/write.fn.x86.hai.32.s`.
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.
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
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`
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.
the folder `arch` in the root of the repository contains syscall tables and ABI implementations for various architectures.
# build system
................................................................................
* `os={atom}` - an atom representing the operating system you are building libk for
* `arch={atom}` - an atom representing the processor architecture you are building libk for
* `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.
further optional variables may be set to control the build process and determine what targets it produces.
* `library=static {static|shared|both}` - this variable controls whether the build process will produce `libk.a`, `libk.so`, or both.
* `to=out {path}` - an alternate path to store build artifacts in
* `gen=gen {path}` - an alternate path to store generated source in
* `cc=<autodetect> {executable}` - the compiler to compile C sources with
* `m4=<autodetect> {executable}` - the m4 binary to compile the macro sources with
* `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.
* `doc=yes {yes|no}` - whether to typeset the documentation (very slow with all three formats set to "yes")
* `doc_html=yes {yes|no}` - enable or disable html output of the documentation
* `doc_pdf=yes {yes|no}` - enable or disable pdf output of the documentation
|