# microlibs **Repository Path**: ACleverDisguise/microlibs ## Basic Information - **Project Name**: microlibs - **Description**: Some single-header libraries that may or may not do useful things. - **Primary Language**: Unknown - **License**: WTFPL - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 1 - **Forks**: 0 - **Created**: 2025-07-28 - **Last Updated**: 2026-02-15 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # _microlibs_ The _microlibs_ collection is a series of single-file libraries modelled after the famous [stb](https://github.com/nothings/stb) libraries. Each library consists of a single header (`.h`) file and a paired source (`.c`) file that is used for testing and as a demonstration of usage only. The source file contains none of the library implementation and is not needed. Most (but not all) of these libraries are intended for use in embedded space. As a result they are as small and as simple as they can possibly be while still being useful. ## Library Licensing ![WTFPL Badge](images/wtfpl-badge-1.png) All _microlibs_ in this repository are licensed under the **WTFPL2** (DO WHAT THE FUCK YOU WANT TO PUBLIC LICENSE Version 2). This means you can use, modify, and distribute the code however you like, no strings attached. For the full license text, see [LICENSE](LICENSE). ### Disclaimer These _microlibs_ are provided **as-is**, with the only guarantee being that they might occupy space on your storage device, cloud space, or whatever. If they work, hey great! If they break, sucks to be you, but at least you get to keep all the pieces. If they break, but you pushed out untested code and this leads to your project failing and costing you billions of dollars, and as a result you're really angry with me, you need to (re?)learn the fundamentals of software engineering. If you're a lawyer nervous about something licenced with the word "FUCK" in the very license name, you probably need to attend some remedial English classes since the solution is clearly spelled out in the license. #### Payment If you really love any element of this library because it saved you literally MINUTES of work (maybe even TWO DIGITS minutes!) feel free to gift me with some small-distillery, strong-scented baijiu. If you don't want to (or don't know what any of that even means) that's cool too. I'm not doing this for the money, and I can buy my own booze at need. ## Project Structure The project structure is straightforward. In the root directory is the documentation `README.md` (which you are currently reading so its presence is likely already known to you), the `Makefile`, the `LICENSE` file (which was already mentioned above), the `images` directory, the `makelib` directory, and the `libs` directory. There may also be a `marker` file (for which c.f. the `Makefile` to see what it's for). In addition, since the test suites are going to be migrated toward using the [acutest](https://github.com/mity/acutest) single-header test suite, an additional `include` directory will be provided for purposes of putting common headers (currently one) into the test programs. ### Makefile The Makefile is designed to be as simple to use as possible. Typing `make` gets a list of available user-facing targets with a brief explanation of what each is for. The targets most likely to be useful are `build`, `grind`, and `clean`. ### images This project dumps any image files it needs (e.g. for the documentation) here to keep the root directory from being cluttered. I mean it's already got three files and three directories. I really don't want to add more stuff to confuse my users! ### makelib This project makes use of [bmakelib](https://github.com/bahmanm/bmakelib) whose `.mk` files have been provided in this directory. In addition compiler options, etc. are provided in this directory in the file `config.mk`. ### libs The actual libraries live here: one subdirectory per library. ## Library Structure and Naming Conventions The first convention is that each library is in its own directory, named by project, under the libs directory. The second convention is that the library is placed into a header file by with the project name plus `.h` appended. The third convention is that the test/demonstration source file is placed into a source file named by the project name plus `_test.c` appended. If there are data files, etc. needed by the `_test.c` file the naming will be ad hoc, but ideally all tests should be self-contained in that single file. So as an example, if there is a library named `foo`, there would be the following directory and files added: * `./libs/foo` -- the containing directory * `./libs/foo.h` -- the implementation file for the library * `./libs/foo_test.c` -- the combination test and demonstration program using the library ## Using the _microlibs_ Each _microlib_ is presented in a single `.h` file for ease of use. The _microlib_ is can be included anywhere it is used in your application, but in **one** _**single**_ file it **must** have a macro defined before it is included. For example, presuming a _microlib_ called `foo`, in any file that uses `foo` you would only need to do this: 

  #include "foo.h"
In one file, however, an implementation macro must first be defined: 

  #define FOO_IMPLEMENTATION
  #include "foo.h"
Doing this also includes the function implementation into the project, thus guaranteeing functions are only defined in one place, but declared wherever they are needed. Failure to define the `*_IMPLEMENTATION` macro at all in your project will make your linker whine about missing symbols. Defining it in more than one file will have it whining instead about duplicate definitions. Both are bad. ## Current Libraries Several libraries are currently in working order and ready for use. ### [at_cmd](libs/at_cmd/at_cmd.h) This library provides a simple, easily-used approach to supply AT-style command processing to projects. AT commands were introduced by Hayes way back in the modem days and are still frequently used in embedded systems for communications with peripherals, particularly things like Bluetooth or GSM adapters or the like. The library is fully documented in its `.h` file. ### [balloc](libs/balloc/balloc.h) A multi-arena bump allocator system for quick and efficient allocation of small bits and pieces of incrementally-allocated values which are then batch-recovered at the end. For example if building up an array of strings, you need to repeatedly allocate the strings' space. You would then use said array of strings, but at the end you would simply want to destroy all the strings at once. Using traditional `malloc()`/`realloc()`/`free()` calls leaves you vulnerable to fragmentation and inefficient use of memory. In addition you waste CPU both in allocation and in walking the deallocation chain. Using `balloc` you have a faster, more efficient, easier, and safer approach. ### [cobs](libs/cobs/cobs.h) An implementation of Consistent Overhead Byte Stuffing, a useful tool for designing and implementing communication protocols. It encodes arbitrary binary data in a way that eliminates any zero bytes with minimal overhead. For example a 2KB buffer will add only 7 additional bytes to the encoding. ### [cycle_sort](libs/cycle_sort/cycle_sort.h) This unusual sort is used in situations where writes are expensive (such as disk files or Flash memory or the like). It makes the absolute theoretical minimum number of memory writes while sorting in-place. While it is O(N^2) in complexity, for the target environment (embedded systems) this is fine since the cost of writing values is far higher than the cost of high complexity given the small data sets that tend to be involved. As it currently exists there will need to be some modification to deal with the vagaries of different memory systems. ### [gnome_sort](libs/gnome_sort/gnome_sort.h) This implements the infamous Gnome Sort, often considered a pathological sort. In the world of embedded software, however, there is no pathology. Data sets are small, so the O(N^2) complexity is a non-issue. Its ability to very quickly short-circuit mostly-sorted data is useful, and its memory footprint cannot be beat. (The entire code can often be fit into a single cache line with room to spare.) In space-tight systems, `gnome_sort` can be a life-saver! ### [gray](libs/gray/gray.h) A simple Gray Code codec: one function encodes, the other decodes. Implementation and usage are both trivial, though still documented well in the `.h` file because I am not a barbarian. ### [opalloc](libs/opalloc/oppalloc.h) An object pool allocator intended for use in embedded systems where multiple objects of the same size get allocated and freed in ways that would generate massive fragmentation. This allocator resists fragmentation (with four possible configurations that increasingly trade waste for less fragmentation) while being easy to use. ### [ringbuf](libs/ringbuf/ringbuf.h) A simple ring buffer. For flexibility values can be pushed to the front (default) or rear of the ring and values can be pulled from the front or the rear (default). Using the defaults you have a basic circular queue. Being able to push or pull from either end gives you something that can be used as a stack (push and pull from the front) or even a queue with a temporary stack used for calculating interim values by pushing to the front and doing stack operations on the back. ## Possible future members; works in progress ### [houyi](libs/houyi/houyi.h) A Robin Hood hash table implementation. ### [mengce](libs/mengce/mengce.h) A single-header test suite library in C. Acutest is fine for now, but it's missing a few things I'd like including the test-suite-case hierarchy I favour from Lua testing suites like lester. I'll be using it but with an eye toward studying its pain points for later enhancement as mengce. ### [var](libs/var/var.h) An attempt at a variant type library in C. Very speculative.