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 Meson, 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 Methods
  20
  21 This project supports two installation methods, each designed for different use cases:
  22
  23 ### 1. Development/Versioned Install (`dev` mode)
  24
  25 - **Purpose:**
  26   - For developers and packagers who want to install headers, static/shared libraries, and pkg-config files in a versioned, self-contained directory.
  27   - Allows multiple versions to coexist without interfering with system libraries or headers.
  28 - **What gets installed:**
  29   - Headers, static and shared libraries, and pkg-config files, all under a versioned root (e.g., `/usr/local/libderp-dev.1.1.1/`).
  30 - **How to use:**
  31   ```sh
  32   meson setup build-dev -Dinstall_mode=dev
  33   ninja -C build-dev
  34   meson install -C build-dev
  35   ```
  36 - **Result:**
  37   - All development artifacts are grouped under the versioned root.
  38   - No files are installed to global system locations.
  39
  40 ### 2. System Install (`system` mode)
  41
  42 - **Purpose:**
  43   - For system administrators or users who want to install only the shared library for runtime use, with robust versioned symlinks for compatibility.
  44   - Does **not** install headers or pkg-config files.
  45   - Supports multiple major versions side-by-side, with symlinks for all minor versions.
  46 - **What gets installed:**
  47   - Only the shared library, to the system libdir (e.g., `/usr/local/lib/x86_64-linux-gnu/`), with symlinks for all minor versions (e.g., `libderp.so.1.0`, `libderp.so.1.1`).
  48 - **How to use:**
  49   ```sh
  50   meson setup build-system -Dinstall_mode=system
  51   ninja -C build-system
  52   # For a real install (to /usr/local), run:
  53   sudo meson install -C build-system
  54   # For a safe test install, use:
  55   DESTDIR=/tmp/libderp-test meson install -C build-system
  56   ```
  57 - **Result:**
  58   - Only the shared library and symlinks are installed to the system libdir.
  59   - No headers or pkg-config files are installed.
  60   - Symlinks for all minor versions are created, supporting robust runtime linking and upgrades.
  61
  62 ---
  63
  64 **Which should you use?**
  65 - Use **dev mode** if you are developing, packaging, or need to link against libderp in your own projects.
  66 - Use **system mode** if you only need the runtime shared library for system-wide use, or want to support robust upgrades and multiple major versions.
  67
  68 See the [Portable best practices article](https://begriffs.com/posts/2021-07-04-shared-libraries.html) for more background on these installation strategies.