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`. This library uses position-independent code (PIC) for its
  75 static library. Mostly out of laziness in the build process, but it also allows
  76 shared libraries to link a static copy of libderp inside too. The disadvantage
  77 is that PIC causes a performance hit, especially on some older CPU
  78 architectures.
  79
  80 #### Installing runtime assets (for the loader)
  81
  82 To install the shared library for loading, use the `install.sh` script.
  83
  84 ```sh
  85 # (if path is omitted, it defaults to /usr/local/lib)
  86 ./install.sh /path
  87 ```
  88
  89 This copies the shared library, and creates symbolic links to match the soname
  90 that applications are built against.
  91
  92 ### Contributing to Libderp
  93
  94 To build in `build/dev` with warnings, profiling, debugging information, and
  95 code coverage data, use the "dev" variant:
  96
  97 ```sh
  98 # requires clang specifically
  99 make VARIANT=dev
 100 ```
 101
 102 Object files for the dev and release variants can coexist. There is no `make
 103 clean` target because there shouldn't be a need to do that manually. The
 104 Makefile has an accurate dependency graph, so running `make` should always know
 105 what to update.
 106
 107 ### Running tests
 108
 109 ```sh
 110 make VARIANT=dev tests
 111
 112 ./build/dev/test/run
 113 ```
 114
 115 On platforms where Clang supports memory leak checks, you can activate them
 116 like this:
 117
 118 ```sh
 119 ASAN_OPTIONS=detect_leaks=1 ./build/dev/test/run
 120 ```
 121
 122 To see test coverage for a data structure, run the cov script:
 123
 124 ```sh
 125 ./build/dev/test/cov hashmap
 126 ```