begriffs open source - libderp/blob - README.md

   1 ## libderp, yet another C collection library
   2
   3 Why you might use it
   4
   5 * builds with any variant of make, any C99 compiler
   6 * a proper library that you can link against
   7 * no abuse of translation units, no weird macros
   8 * includes proper man pages (TODO)
   9 * shared and static library
  10 * pkg-config interface
  11 * developer friendly ISC license
  12
  13 Why you might avoid it
  14
  15 * containers use void pointers, e.g. no vector of ints
  16 * pedestrian algorithms, not cutting edge
  17 * not (yet) thread safe
  18
  19 ### Installation
  20
  21 Compile the shared and static libraries:
  22
  23 ```sh
  24 # detect proper way to generate shared library
  25 ./configure
  26
  27 # create static and shared libs in build/release
  28 make
  29 ```
  30
  31 #### Installing development assets (for the linker)
  32
  33 To install libraries that an application would link with, along with headers,
  34 and pkg-config specifications, use the `install-dev.sh` script:
  35
  36 ```sh
  37 # (if path is omitted, it defaults to /opt)
  38 ./install-dev.sh /path
  39 ```
  40
  41 The result will be a folder structure like this:
  42
  43 ```
  44 /path/libderp-dev.x.y.z
  45 ├── libderp.pc
  46 ├── libderp-static.pc
  47 ├── include
  48 │   └── derp
  49 │       ├── ...
  50 │       └── ...
  51 ├── lib
  52 │   ├── libderp.so (or dylib or dll)
  53 │   └── static
  54 │       └── libderp.a
  55 └── man
  56     ├── ...
  57     └── ...
  58 ```
  59
  60 The easiest way to build against these files is to use pkg-config, which will
  61 provide the correct compiler/linker flags.
  62
  63 ```sh
  64 # make desired libderp version visible to pkg-config
  65 export PKG_CONFIG_PATH="$PKG_CONFIG_PATH:/path/libderp.x.y.z"
  66
  67 # compile foo.c and link with libderp
  68 cc `pkg-config --cflags --libs-only-L libderp` \
  69         -o foo foo.c `pkg-config --libs-only-l libderp`
  70 ```
  71
  72 To link statically against the library, change the pkg-config name `libderp` to
  73 `libderp-static`.
  74
  75 #### Installing runtime assets (for the loader)
  76
  77 To install the shared library for loading, use the `install.sh` script.
  78
  79 ```sh
  80 # (if path is omitted, it defaults to /usr/local/lib)
  81 ./install.sh /path
  82 ```
  83
  84 This copies the shared library, and creates symbolic links to match the soname
  85 that applications are built against.
  86
  87 ### Using a different memory allocator
  88
  89 By default, libderp uses memory allocation from the C standard library.
  90 However, if you want it to use a different set of functions, specify them with
  91 a call to `derp_use_alloc_funcs()` prior to any other libderp API calls:
  92
  93 ```c
  94 /* for instance, Boehm GC: */
  95 derp_use_alloc_funcs(GC_malloc, GC_realloc, GC_free);
  96 ```
  97 ### Contributing to Libderp
  98
  99 To build in `build/dev` with warnings, leak checks, and code coverage data, use
 100 the "dev" variant:
 101
 102 ```sh
 103 # requires clang
 104 make VARIANT=dev
 105 ```
 106
 107 Object files for the dev and release variants can coexist. There is no `make
 108 clean` target because there shouldn't be a need to do that manually. The
 109 Makefile has an accurate dependency graph, so running `make` should always know
 110 what to update.
 111
 112 ### Running tests
 113
 114 ```sh
 115 make VARIANT=dev tests
 116
 117 ./build/dev/test/run
 118 ```
 119
 120 The dev variant uses the Boehm garbage collector, if available, [for leak
 121 detection](https://www.hboehm.info/gc/leak.html). Boehm is available on more
 122 platforms than the Clang address sanitizer is.
 123
 124 To see test coverage for a data structure, run the cov script:
 125
 126 ```sh
 127 ./build/dev/test/cov hashmap
 128 ```
 129
 130 ### Customizing the build
 131
 132 #### Cross compiling
 133
 134 The macros `CC`, `AR` and `EXTRA_CFLAGS` can be used to cross-compile for other
 135 architectures. For instance, here is how to compile a static library for ARM
 136 Cortex M4 with hardware floating point support:
 137
 138 ```sh
 139 make CC=arm-none-eabi-gcc AR=arm-none-eabi-ar \
 140      EXTRA_CFLAGS="-mcpu=cortex-m4 -mthumb -mfloat-abi=hard -mfpu=fpv4-sp-d16" \
 141      build/release/libderp.a
 142 ```
 143
 144 Note that the library uses the dynamic memory allocation functions malloc,
 145 free, and realloc, as well as the functions memmove and memset. Thus it needs a
 146 C standard library implementation (like newlib) to function.