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 * hard-coded to use malloc/free
  18 * not (yet) thread safe
  19
  20 ### Installation
  21
  22 Compile the shared and static libraries:
  23
  24 ```sh
  25 # detect proper way to generate shared library
  26 ./configure
  27
  28 # create static and shared libs in build/release
  29 make
  30 ```
  31
  32 #### Installing development assets (for the linker)
  33
  34 To install libraries that an application would link with, along with headers,
  35 and pkg-config specifications, use the `install-dev.sh` script:
  36
  37 ```sh
  38 # (if path is omitted, it defaults to /opt)
  39 ./install-dev.sh /path
  40 ```
  41
  42 The result will be a folder structure like this:
  43
  44 ```
  45 /path/libderp-dev.x.y.z
  46 ├── libderp.pc
  47 ├── libderp-static.pc
  48 ├── include
  49 │   └── derp
  50 │       ├── ...
  51 │       └── ...
  52 ├── lib
  53 │   ├── libderp.so (or dylib or dll)
  54 │   └── static
  55 │       └── libderp.a
  56 └── man
  57     ├── ...
  58     └── ...
  59 ```
  60
  61 The easiest way to build against these files is to use pkg-config, which will
  62 provide the correct compiler/linker flags.
  63
  64 ```sh
  65 # make desired libderp version visible to pkg-config
  66 export PKG_CONFIG_PATH="$PKG_CONFIG_PATH:/path/libderp.x.y.z"
  67
  68 # compile foo.c and link with libderp
  69 cc `pkg-config --cflags --libs-only-L libderp` \
  70         -o foo foo.c `pkg-config --libs-only-l libderp`
  71 ```
  72
  73 To link statically against the library, change the pkg-config name `libderp` to
  74 `libderp-static`.
  75
  76 #### Installing runtime assets (for the loader)
  77
  78 To install the shared library for loading, use the `install.sh` script.
  79
  80 ```sh
  81 # (if path is omitted, it defaults to /usr/local/lib)
  82 ./install.sh /path
  83 ```
  84
  85 This copies the shared library, and creates symbolic links to match the soname
  86 that applications are built against.
  87
  88 ### Contributing to Libderp
  89
  90 To build in `build/dev` with warnings, profiling, debugging information, and
  91 code coverage data, use the "dev" variant:
  92
  93 ```sh
  94 # requires clang specifically
  95 make VARIANT=dev
  96 ```
  97
  98 Object files for the dev and release variants can coexist. There is no `make
  99 clean` target because there shouldn't be a need to do that manually. The
 100 Makefile has an accurate dependency graph, so running `make` should always know
 101 what to update.
 102
 103 ### Running tests
 104
 105 ```sh
 106 make VARIANT=dev tests
 107
 108 ./build/dev/test/run
 109 ```
 110
 111 On platforms where Clang supports memory leak checks, you can activate them
 112 like this:
 113
 114 ```sh
 115 ASAN_OPTIONS=detect_leaks=1 ./build/dev/test/run
 116 ```
 117
 118 To see test coverage for a data structure, run the cov script:
 119
 120 ```sh
 121 ./build/dev/test/cov hashmap
 122 ```
 123
 124 ### Cross compiling
 125
 126 The macros `CC`, `AR` and `EXTRA_CFLAGS` can be used to cross-compile for other
 127 architectures. For instance, below is how to compile a static library for ARM
 128 Cortex M4 with hardware floating point.
 129
 130 ```sh
 131 make CC=arm-none-eabi-gcc AR=arm-none-eabi-ar \
 132      EXTRA_CFLAGS="-mcpu=cortex-m4 -mthumb -mfloat-abi=hard -mfpu=fpv4-sp-d16" \
 133      build/release/libderp.a
 134 ```