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 and install the library:
  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 # create versioned directory for headers and libs
  32 # (if path is omitted, it tries /opt and /usr/local in that order)
  33 ./install.sh /path
  34 ```
  35
  36 The result will be a new folder and symbolic link like this:
  37
  38 ```
  39 /path/libderp.x -> /path/libderp.x.y.z
  40 /path/libderp.x.y.z
  41 ├── include
  42 │   └── derp
  43 │       ├── ...
  44 │       └── ...
  45 ├── lib
  46 │   ├── libderp.a
  47 │   ├── libderp.so (or dylib or dll)
  48 │   └── pkgconfig
  49 │       └── libderp.pc
  50 └── man
  51     ├── ...
  52     └── ...
  53 ```
  54
  55 ### Usage
  56
  57 Multiple versionf of libderp may be installed at once on the system in their
  58 own dedicated folders. This allows everything to be versioned, including
  59 headers and man pages.
  60
  61 When linking to libderp, set an rpath inside your binary to point to the
  62 library of the appropriate major version. The easiest way is to use pkg-config
  63 which will provide you the correct compiler/linker flags.
  64
  65 ```sh
  66 # make desired libderp version visible to pkg-config
  67 export PKG_CONFIG_PATH="$PKG_CONFIG_PATH:/path/libderp.x/lib/pkgconfig"
  68
  69 # compile foo.c and link with libderp
  70 cc `pkg-config --cflags --libs-only-L --libs-only-other libderp` \
  71         -o foo foo.c `pkg-config --libs-only-l libderp`
  72 ```
  73
  74 The `--libs-only-other` options set the rpath for the resulting binary.
  75
  76 ### Libderp development
  77
  78 To build in `build/dev` with warnings, profiling, debugging information, and
  79 code coverage data, use the "dev" variant:
  80
  81 ```sh
  82 # requires clang specifically
  83 make VARIANT=dev
  84 ```
  85
  86 Object files for the dev and release variants can coexist. There is no `make
  87 clean` target because there shouldn't be a need to do that manually. The
  88 Makefile has an accurate dependency graph, so running `make` should always know
  89 what to update.
  90
  91 ### Running tests
  92
  93 ```sh
  94 make VARIANT=dev tests
  95
  96 ./build/dev/test/run
  97 ```
  98
  99 On platforms where Clang supports memory leak checks, you can activate them
 100 like this:
 101
 102 ```sh
 103 ASAN_OPTIONS=detect_leaks=1 ./build/dev/test/run
 104 ```
 105
 106 To see test coverage for a data structure, run the cov script:
 107
 108 ```sh
 109 ./build/dev/test/cov hashmap
 110 ```