libk  Diff

Differences From Artifact [d834bc0082]:

To Artifact [523e766d88]:


    17     17   ## goals
    18     18   
    19     19   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.
    20     20   
    21     21    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.
    22     22    2. **file manipulation.** libc's file manipulation primitives are a relic of a bygone age and in dire need of upgrading.
    23     23    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.
    24         - 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))
    25         - 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.
    26         - 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.
           24  + 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.
           25  + 5. **intrinsic reentrancy.** because *jesus christ,* libc.
           26  + 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.
           27  + 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))
           28  + 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.
           29  + 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.
           30  + 10. **sane error-handling.** every time you type `errno` god murders a puppy.
    27     31   
    28     32   ## naming conventions
    29     33   
    30     34   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!
    31     35   
    32     36   libk is designed to fix this (in hindsight) glaring error.
    33     37   
................................................................................
    62     66    * FreeBSD: `fbsd`
    63     67    * NetBSD: `nbsd`
    64     68    * OpenBSD: `obsd`
    65     69    * Darwin/Mac OS X/iOS: `dar`
    66     70    * MS-DOS: `dos`
    67     71    * FreeDOS: `fdos`
    68     72    * Windows: `win`
           73  + * Windows MinGW: `mgw`
    69     74   
    70     75   #### file extensions
    71     76   
    72     77    * C function implementations: `*.c`
    73     78    * C module headers: `*.h`
    74     79    * ancillary C headers: `*.inc.h`
    75     80    * assembly code: `*.s`
................................................................................
    89     94   libk uses only three languages: C (\*.c, \*.h), yasm (\*.s), and make (makefile).
    90     95   
    91     96   other assemblers will probably be necessary for the more exotic targets, however.
    92     97   
    93     98   ## repository structure
    94     99   
    95    100   libk uses a strict directory structure for code, and deviations from this structure will not be tolerated without extremely good reason.
          101  +
          102  +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.
    96    103   
    97    104   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).
    98    105   
    99    106   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.
   100    107   
   101    108   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.
   102    109   
................................................................................
   154    161   
   155    162   **libk.so** will build the dynamically linked form of libk, according to the build variables set
   156    163   
   157    164   **libk.a** will build the statically linked form of libk, according to the build variables set
   158    165   
   159    166   **tool** will build the executables used for modules such as `kgraft`.
   160    167   
   161         -there is no **clean** target. to clean the repository, simply delete the directory `out/`.
          168  +**clean** will delete the `tmp` and `out` trees.
   162    169   
   163    170   ## authors
   164    171   
   165    172   so far, this is a one-woman show. contributions are welcome however.
   166    173   
   167    174    * lexi hale <lexi@hale.su>
   168    175