view release on metacpan or  search on metacpan

t/data/generate/rra-c-util/docknot.yaml  view on Meta::CPAN

  type: Git
  url: https://git.eyrie.org/git/devel/rra-c-util.git

quote:
  author: Phil Greenspun
  text: |
    Greenspun's Tenth Rule of Programming: any sufficiently complicated C or
    Fortran program contains an ad hoc informally-specified bug-ridden slow
    implementation of half of Common Lisp.
docs:
  api:
    - name: xmalloc
      title: xmalloc, xcalloc, and xrealloc
  extra:
    - title: Test scripts
      links:
        - name: module-version
          title: tests/perl/module-version-t
        - name: module-version-perl
          title: t/style/module-version.t
  user:
    - name: fakepam
      title: PAM testing
    - name: test-rra
      title: Test::RRA
    - name: test-rra-automake
      title: Test::RRA::Automake
    - name: test-rra-config
      title: Test::RRA::Config
    - name: test-rra-moduleversion
      title: Test::RRA::ModuleVersion

blurb: |
  rra-c-util is my collection of portability functions, utility functions,
  Autoconf macros, and related shared C infrastructure, akin to gnulib but
  without any GPL-covered code and additional support for Kerberos and PAM
  development.  It serves as a common repository of code and infrastructure
  used across multiple projects so that files have a canonical latest
  version.  It's not intended for installation as a regular package;
  instead, other packages are expected to copy files from here as needed.

description: |
  The origins of this package are in the libinn utility library in INN.
  Some of the utility and portability functions here are directly inspired
  by or based on versions in older versions of INN, and I wrote and rewrote
  considerable additional portability code and utility libraries when I took
  over INN maintenance.  When I started maintaining other C packages, I
  started copying pieces of libinn into those packages and merging it with
  other portability and utility code.  Over time, each package gained a
  slightly different version of various utility functions, replacements for
  missing functions, and Autoconf macros.

  The goal of this package is to merge all the various versions of any
  portability or utility code that's used in more than one of my packages in
  one place.  Then, each package can update to the latest rra-c-util version
  before each release and gain from the improvements made for all other
  packages.  You can think of it as my version of
  [Gnulib](https://www.gnu.org/software/gnulib/), with everything released
  under a permissive license (no GPL).

  As well as C portability frameworks, Autoconf macros, and a general C
  utility library, this package has also accumulated a considerable
  collection of standard tests (for C and Perl packages) and a large library
  of test utilities and support functions.  It also includes extensive
  support for writing and testing PAM modules, and a portable implementation
  of AFS PAGs.

  This package uses the infrastructure of C TAP Harness for testing, but is
  not the canonical version of `tests/runtests.c`, `tests/tap/basic.[ch]`,
  `tests/tap/macros.h`, or `tests/tap/libtap.sh`.  Those files should be
  pulled from [C TAP
  Harness](https://www.eyrie.org/~eagle/software/c-tap-harness/) instead.

sections:
  - title: Using This Code
    body: |
      While there is an install target, it's present only because Automake
      provides it automatically.  Its use is not recommended.  Instead,
      the code in this package is intended to be copied into your package
      and refreshed from the latest release of rra-c-util for each
      release.

      You can obviously copy the code and integrate it however works best
      for your package and your build system.  Here's how I do it for my
      packages as an example:

      * Create a portable directory and copy `macros.h`, `system.h`,
        `stdbool.h`, and `dummy.c` along with whatever additional
        functions that your package uses that may not be present on all
        systems.  If you use much of the `util` directory (see below),
        you'll need `asprintf.c`, `reallocarray.c`, and `snprintf.c` at
        least.  If you use `util/network.c`, you'll also need
        `getaddrinfo.c`, `getaddrinfo.h`, `getnameinfo.c`,
        `getnameinfo.h`, `inet_*.c`, and `socket.h`.  You'll need
        `winsock.c` for networking portability to Windows.

      * Copy the necessary portions of `configure.ac` from this package
        into your package.  `configure.ac` is commented to try to give you
        a guide for what you need to copy over.  You will also need to
        make an `m4` subdirectory, add the code to `configure.ac` to load
        Autoconf macros from `m4`, and copy over `m4/snprintf.m4` and
        possibly `m4/socket.m4` and `m4/inet-ntoa.m4`.

      * Copy the code from `Makefile.am` for building `libportable.a` into
        your package and be sure to link your package binaries with
        `libportable.a`.  If you include this code in a shared library,
        you'll need to build `libportable.la` instead; see the Automake
        manual for the differences.  You'll need to change `LIBRARIES` to
        `LTLIBRARIES` and `LIBOBJS` to `LTLIBOBJS` in addition to renaming
        the targets.

      * Create a `util` directory and copy over the portions of the
        utility library that you want.  You will probably need
        `messages.[ch]` and `xmalloc.[ch]` if you copy anything over at
        all, since most of the rest of the library uses those.  You will
        also need `m4/vamacros.m4` if you use `messages.[ch]`.

      * Copy the code from `Makefile.am` for building `libutil.a` into
        your package and be sure to link your package binaries with
        `libutil.a`.  As with `libportable.a`, if you want to use the
        utility functions in a shared library, you'll need to instead