17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
..
62
63
64
65
66
67
68
69
70
71
72
73
74
75
..
89
90
91
92
93
94
95
96
97
98
99
100
101
102
...
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
|
## goals
libk's goals are far-reaching, and suggestions are welcome. note however that libk is *not* intended to be a kitchen-sink library like libiberty. it's meant to do one thing, and to it well: to provide an easy- and pleasant-to-use foundation for modern open source projects. below is a list of some of the project's major goals.
1. **IO.** libc's basic input/output mechanisms are dreadful, built at entirely the wrong level of abstraction. libk is intended to make many more primitives available to the user, and offer a sliding scale of abstraction so libk is suitable for a wide range of needs.
2. **file manipulation.** libc's file manipulation primitives are a relic of a bygone age and in dire need of upgrading.
3. **terminal manipulation.** libc has no provision for simple output formatting, a task that requires a combination of ANSI codes and in some cases pty manipulation with POSIX APIs, both of which are somewhat dark wizardry. this situation forces many innocent coders to drag in the entire unholy bulk of the aptly named library `ncurses`, much of whose code has been utterly obsolete for the last twenty years and whose API is one of the most singularly hateful ones in existence. libk therefore should offer a simple, straightforward way to do gracefully-degrading terminal sorcery.
0. **tooling.** libk is intended as more than just a library. it's also intended to work with some basic tooling to automate tasks that current binary tooling is inadequate for -- for instance, embedding binary data into a program binary. (see module [kgraft](kgraft))
0. **modularity.** libk is not part of the C specification and it isn't always going to be practical for developers to expect the entire library to be present on the end-user's computer. so libk is designed to be usable in many different ways -- as a traditional library, as a static library, in full form or with only components needed by the developer, to be distributed either on its own or as part of a binary.
0. **compatibility.** code that links against libk should be able to compile and run on any operating system. in the ideal case (Linux or FreeBSD) it will be able to do so without touching any other system libraries; for less ideal environments like Windows, libk will when necessary abstract over system libraries or libc itself.
## naming conventions
one of the most frustrating things about libc is its complete and total *lack* of a naming convention. in C, every function and global is injected into a single global namespace, including macros. this means that every libc header you include scatters words all over that namespace, potentially clobbering your function with a macro!
libk is designed to fix this (in hindsight) glaring error.
................................................................................
* FreeBSD: `fbsd`
* NetBSD: `nbsd`
* OpenBSD: `obsd`
* Darwin/Mac OS X/iOS: `dar`
* MS-DOS: `dos`
* FreeDOS: `fdos`
* Windows: `win`
#### file extensions
* C function implementations: `*.c`
* C module headers: `*.h`
* ancillary C headers: `*.inc.h`
* assembly code: `*.s`
................................................................................
libk uses only three languages: C (\*.c, \*.h), yasm (\*.s), and make (makefile).
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.
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. when OS or architecture-specific code is needed, the file's name should be a list of one or more of the fields [arch, OS, bits, format] separated by a `.` -- for instance, the 32-bit x86 haiku version of a function called `write` defined in assembly would be named `write.x86.hai.32.s`. however, if a function has an extraordinarily large number of versions, they may instead be stored in a folder with the same name as the function.
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.
................................................................................
**libk.so** will build the dynamically linked form of libk, according to the build variables set
**libk.a** will build the statically linked form of libk, according to the build variables set
**tool** will build the executables used for modules such as `kgraft`.
there is no **clean** target. to clean the repository, simply delete the directory `out/`.
## authors
so far, this is a one-woman show. contributions are welcome however.
* lexi hale <lexi@hale.su>
|
|
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
..
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
..
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
...
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
|
## goals
libk's goals are far-reaching, and suggestions are welcome. note however that libk is *not* intended to be a kitchen-sink library like libiberty. it's meant to do one thing, and to it well: to provide an easy- and pleasant-to-use foundation for modern open source projects. below is a list of some of the project's major goals.
1. **IO.** libc's basic input/output mechanisms are dreadful, built at entirely the wrong level of abstraction. libk is intended to make many more primitives available to the user, and offer a sliding scale of abstraction so libk is suitable for a wide range of needs.
2. **file manipulation.** libc's file manipulation primitives are a relic of a bygone age and in dire need of upgrading.
3. **terminal manipulation.** libc has no provision for simple output formatting, a task that requires a combination of ANSI codes and in some cases pty manipulation with POSIX APIs, both of which are somewhat dark wizardry. this situation forces many innocent coders to drag in the entire unholy bulk of the aptly named library `ncurses`, much of whose code has been utterly obsolete for the last twenty years and whose API is one of the most singularly hateful ones in existence. libk therefore should offer a simple, straightforward way to do gracefully-degrading terminal sorcery.
4. **memory management.** the single memory management function `malloc()` provided by libc is absolutely pitiful. this is 2019. modern applications have much more exotic allocation needs, and a standard library should offer a range of allocators and management techniques, as well as abstract pointer objects so that pointers to objects of different allocation types (including static or stack allocation!) can be mixed freely and safely.
5. **intrinsic reentrancy.** because *jesus christ,* libc.
6. **interprocess communication.** libc offers no useful IPC abstractions over the paltry array of tools POSIX &co. give us to work with. we can do better.
7. **tooling.** libk is intended as more than just a library. it's also intended to work with some basic tooling to automate tasks that current binary tooling is inadequate for -- for instance, embedding binary data into a program binary. (see module [kgraft](kgraft))
8. **modularity.** libk is not part of the C specification and it isn't always going to be practical for developers to expect the entire library to be present on the end-user's computer. so libk is designed to be usable in many different ways -- as a traditional library, as a static library, in full form or with only components needed by the developer, to be distributed either on its own or as part of a binary.
9. **compatibility.** code that links against libk should be able to compile and run on any operating system. in the ideal case (Linux or FreeBSD) it will be able to do so without touching any other system libraries; for less ideal environments like Windows, libk will when necessary abstract over system libraries or libc itself.
10. **sane error-handling.** every time you type `errno` god murders a puppy.
## naming conventions
one of the most frustrating things about libc is its complete and total *lack* of a naming convention. in C, every function and global is injected into a single global namespace, including macros. this means that every libc header you include scatters words all over that namespace, potentially clobbering your function with a macro!
libk is designed to fix this (in hindsight) glaring error.
................................................................................
* FreeBSD: `fbsd`
* NetBSD: `nbsd`
* OpenBSD: `obsd`
* Darwin/Mac OS X/iOS: `dar`
* MS-DOS: `dos`
* FreeDOS: `fdos`
* Windows: `win`
* Windows MinGW: `mgw`
#### file extensions
* C function implementations: `*.c`
* C module headers: `*.h`
* ancillary C headers: `*.inc.h`
* assembly code: `*.s`
................................................................................
libk uses only three languages: C (\*.c, \*.h), yasm (\*.s), and make (makefile).
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 `make` parameters `TMP= OUT=`, but default to `tmp/` and `out/`, which are excluded from repo with fossil's `ignore-glob` setting.
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. when OS or architecture-specific code is needed, the file's name should be a list of one or more of the fields [arch, OS, bits, format] separated by a `.` -- for instance, the 32-bit x86 haiku version of a function called `write` defined in assembly would be named `write.x86.hai.32.s`. however, if a function has an extraordinarily large number of versions, they may instead be stored in a folder with the same name as the function.
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.
................................................................................
**libk.so** will build the dynamically linked form of libk, according to the build variables set
**libk.a** will build the statically linked form of libk, according to the build variables set
**tool** will build the executables used for modules such as `kgraft`.
**clean** will delete the `tmp` and `out` trees.
## authors
so far, this is a one-woman show. contributions are welcome however.
* lexi hale <lexi@hale.su>
|