Mercurial > molko

annotate extern/libcompat/README.md @ 299:648f5f949afb

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
core: implement stackable states
author David Demelier <markand@malikania.fr>
date Sun, 11 Apr 2021 16:41:34 +0200
parents f978fa0137ce
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
258
f978fa0137ce extern: provide libcompat
David Demelier <markand@malikania.fr>
parents:
diff changeset
1 libcompat
f978fa0137ce extern: provide libcompat
David Demelier <markand@malikania.fr>
parents:
diff changeset
2 =========
f978fa0137ce extern: provide libcompat
David Demelier <markand@malikania.fr>
parents:
diff changeset
3
f978fa0137ce extern: provide libcompat
David Demelier <markand@malikania.fr>
parents:
diff changeset
4 This project contains several polyfill for various C extensions that are not
f978fa0137ce extern: provide libcompat
David Demelier <markand@malikania.fr>
parents:
diff changeset
5 part of C standard or POSIX.
f978fa0137ce extern: provide libcompat
David Demelier <markand@malikania.fr>
parents:
diff changeset
6
f978fa0137ce extern: provide libcompat
David Demelier <markand@malikania.fr>
parents:
diff changeset
7 For example, it contains various functions such as:
f978fa0137ce extern: provide libcompat
David Demelier <markand@malikania.fr>
parents:
diff changeset
8
f978fa0137ce extern: provide libcompat
David Demelier <markand@malikania.fr>
parents:
diff changeset
9 - pledge: privileges separation from OpenBSD (no-op on other systems),
f978fa0137ce extern: provide libcompat
David Demelier <markand@malikania.fr>
parents:
diff changeset
10 - reallocarray/recallocarray: safe alternative to realloc for arrays from
f978fa0137ce extern: provide libcompat
David Demelier <markand@malikania.fr>
parents:
diff changeset
11 OpenBSD,
f978fa0137ce extern: provide libcompat
David Demelier <markand@malikania.fr>
parents:
diff changeset
12 - strlcpy/strlcat: safer alternatives to strncpy/strncat from OpenBSD,
f978fa0137ce extern: provide libcompat
David Demelier <markand@malikania.fr>
parents:
diff changeset
13 - strsep: better alternative to strtok from 4.4BSD.
f978fa0137ce extern: provide libcompat
David Demelier <markand@malikania.fr>
parents:
diff changeset
14
f978fa0137ce extern: provide libcompat
David Demelier <markand@malikania.fr>
parents:
diff changeset
15 Requirements
f978fa0137ce extern: provide libcompat
David Demelier <markand@malikania.fr>
parents:
diff changeset
16 ------------
f978fa0137ce extern: provide libcompat
David Demelier <markand@malikania.fr>
parents:
diff changeset
17
f978fa0137ce extern: provide libcompat
David Demelier <markand@malikania.fr>
parents:
diff changeset
18 - C compiler,
f978fa0137ce extern: provide libcompat
David Demelier <markand@malikania.fr>
parents:
diff changeset
19 - POSIX conformant system (ar, make, sh, rm, tr, touch).
f978fa0137ce extern: provide libcompat
David Demelier <markand@malikania.fr>
parents:
diff changeset
20
f978fa0137ce extern: provide libcompat
David Demelier <markand@malikania.fr>
parents:
diff changeset
21 Usage
f978fa0137ce extern: provide libcompat
David Demelier <markand@malikania.fr>
parents:
diff changeset
22 -----
f978fa0137ce extern: provide libcompat
David Demelier <markand@malikania.fr>
parents:
diff changeset
23
f978fa0137ce extern: provide libcompat
David Demelier <markand@malikania.fr>
parents:
diff changeset
24 The easiest way to use libcompat is to copy the directory content into your
f978fa0137ce extern: provide libcompat
David Demelier <markand@malikania.fr>
parents:
diff changeset
25 project and to adapt files you need.
f978fa0137ce extern: provide libcompat
David Demelier <markand@malikania.fr>
parents:
diff changeset
26
f978fa0137ce extern: provide libcompat
David Demelier <markand@malikania.fr>
parents:
diff changeset
27 Every routine (or group of routines) is implemented into an individual file
f978fa0137ce extern: provide libcompat
David Demelier <markand@malikania.fr>
parents:
diff changeset
28 plus tested with a test file.
f978fa0137ce extern: provide libcompat
David Demelier <markand@malikania.fr>
parents:
diff changeset
29
f978fa0137ce extern: provide libcompat
David Demelier <markand@malikania.fr>
parents:
diff changeset
30 Example with strlcpy:
f978fa0137ce extern: provide libcompat
David Demelier <markand@malikania.fr>
parents:
diff changeset
31
f978fa0137ce extern: provide libcompat
David Demelier <markand@malikania.fr>
parents:
diff changeset
32 - libcompat/strlcpy.c
f978fa0137ce extern: provide libcompat
David Demelier <markand@malikania.fr>
parents:
diff changeset
33 - libcompat/test-strlcpy.c
f978fa0137ce extern: provide libcompat
David Demelier <markand@malikania.fr>
parents:
diff changeset
34
f978fa0137ce extern: provide libcompat
David Demelier <markand@malikania.fr>
parents:
diff changeset
35 Then, the build process create the following output files, example with
f978fa0137ce extern: provide libcompat
David Demelier <markand@malikania.fr>
parents:
diff changeset
36 strlcpy:
f978fa0137ce extern: provide libcompat
David Demelier <markand@malikania.fr>
parents:
diff changeset
37
f978fa0137ce extern: provide libcompat
David Demelier <markand@malikania.fr>
parents:
diff changeset
38 - libcompat/strlcpy.t: output of the compiler command, usually empty on
f978fa0137ce extern: provide libcompat
David Demelier <markand@malikania.fr>
parents:
diff changeset
39 success.
f978fa0137ce extern: provide libcompat
David Demelier <markand@malikania.fr>
parents:
diff changeset
40 - libcompat/strlcpy.h: a header file containing `#define COMPAT_HAVE_STRLCPY`
f978fa0137ce extern: provide libcompat
David Demelier <markand@malikania.fr>
parents:
diff changeset
41 if the test succeed.
f978fa0137ce extern: provide libcompat
David Demelier <markand@malikania.fr>
parents:
diff changeset
42 - libcompat/strlcpy.o: object file containing fallback implementation or
f978fa0137ce extern: provide libcompat
David Demelier <markand@malikania.fr>
parents:
diff changeset
43 nothing if the component is available in the host system.
f978fa0137ce extern: provide libcompat
David Demelier <markand@malikania.fr>
parents:
diff changeset
44
f978fa0137ce extern: provide libcompat
David Demelier <markand@malikania.fr>
parents:
diff changeset
45 Finally, when you want to use one of the extension, you'll have to import the
f978fa0137ce extern: provide libcompat
David Demelier <markand@malikania.fr>
parents:
diff changeset
46 header file where it's supposed to be declared (unless this header file is not
f978fa0137ce extern: provide libcompat
David Demelier <markand@malikania.fr>
parents:
diff changeset
47 portable) and you also must include libcompat/compat.h.
f978fa0137ce extern: provide libcompat
David Demelier <markand@malikania.fr>
parents:
diff changeset
48
f978fa0137ce extern: provide libcompat
David Demelier <markand@malikania.fr>
parents:
diff changeset
49 Example with strlcpy:
f978fa0137ce extern: provide libcompat
David Demelier <markand@malikania.fr>
parents:
diff changeset
50
f978fa0137ce extern: provide libcompat
David Demelier <markand@malikania.fr>
parents:
diff changeset
51 #include <string.h>
f978fa0137ce extern: provide libcompat
David Demelier <markand@malikania.fr>
parents:
diff changeset
52 #include "libcompat/compat.h"
f978fa0137ce extern: provide libcompat
David Demelier <markand@malikania.fr>
parents:
diff changeset
53
f978fa0137ce extern: provide libcompat
David Demelier <markand@malikania.fr>
parents:
diff changeset
54 ### Wrapper script
f978fa0137ce extern: provide libcompat
David Demelier <markand@malikania.fr>
parents:
diff changeset
55
f978fa0137ce extern: provide libcompat
David Demelier <markand@malikania.fr>
parents:
diff changeset
56 The convenient script libcompat/compile.sh will try co compile the test and
f978fa0137ce extern: provide libcompat
David Demelier <markand@malikania.fr>
parents:
diff changeset
57 will either compile the polyfill or a dummy empty file instead. It should be
f978fa0137ce extern: provide libcompat
David Demelier <markand@malikania.fr>
parents:
diff changeset
58 invoked with the canonical filename (without extension).
f978fa0137ce extern: provide libcompat
David Demelier <markand@malikania.fr>
parents:
diff changeset
59
f978fa0137ce extern: provide libcompat
David Demelier <markand@malikania.fr>
parents:
diff changeset
60 It also read `CC`, `CFLAGS` and `LDFLAGS` environment variable which are all
f978fa0137ce extern: provide libcompat
David Demelier <markand@malikania.fr>
parents:
diff changeset
61 optional.
f978fa0137ce extern: provide libcompat
David Demelier <markand@malikania.fr>
parents:
diff changeset
62
f978fa0137ce extern: provide libcompat
David Demelier <markand@malikania.fr>
parents:
diff changeset
63 Example of use:
f978fa0137ce extern: provide libcompat
David Demelier <markand@malikania.fr>
parents:
diff changeset
64
f978fa0137ce extern: provide libcompat
David Demelier <markand@malikania.fr>
parents:
diff changeset
65 ./libcompat/compile.sh strlcpy
f978fa0137ce extern: provide libcompat
David Demelier <markand@malikania.fr>
parents:
diff changeset
66 CC="clang" CFLAGS="-O2" ./libcompat/compile.sh strlcat
f978fa0137ce extern: provide libcompat
David Demelier <markand@malikania.fr>
parents:
diff changeset
67
f978fa0137ce extern: provide libcompat
David Demelier <markand@malikania.fr>
parents:
diff changeset
68 ### Makefile
f978fa0137ce extern: provide libcompat
David Demelier <markand@malikania.fr>
parents:
diff changeset
69
f978fa0137ce extern: provide libcompat
David Demelier <markand@malikania.fr>
parents:
diff changeset
70 The included Makefile can be used as boilerplate into your project and create a
f978fa0137ce extern: provide libcompat
David Demelier <markand@malikania.fr>
parents:
diff changeset
71 libcompat.a archive ready to use. Simply adapt macros in the Makefile for your
f978fa0137ce extern: provide libcompat
David Demelier <markand@malikania.fr>
parents:
diff changeset
72 own use.
f978fa0137ce extern: provide libcompat
David Demelier <markand@malikania.fr>
parents:
diff changeset
73
f978fa0137ce extern: provide libcompat
David Demelier <markand@malikania.fr>
parents:
diff changeset
74 Licenses
f978fa0137ce extern: provide libcompat
David Demelier <markand@malikania.fr>
parents:
diff changeset
75 --------
f978fa0137ce extern: provide libcompat
David Demelier <markand@malikania.fr>
parents:
diff changeset
76
f978fa0137ce extern: provide libcompat
David Demelier <markand@malikania.fr>
parents:
diff changeset
77 Polyfill code are licensed per their authors and must be checked individually.
f978fa0137ce extern: provide libcompat
David Demelier <markand@malikania.fr>
parents:
diff changeset
78 See headers in the libcompat directory.
f978fa0137ce extern: provide libcompat
David Demelier <markand@malikania.fr>
parents:
diff changeset
79
f978fa0137ce extern: provide libcompat
David Demelier <markand@malikania.fr>
parents:
diff changeset
80 Author
f978fa0137ce extern: provide libcompat
David Demelier <markand@malikania.fr>
parents:
diff changeset
81 ------
f978fa0137ce extern: provide libcompat
David Demelier <markand@malikania.fr>
parents:
diff changeset
82
f978fa0137ce extern: provide libcompat
David Demelier <markand@malikania.fr>
parents:
diff changeset
83 David Demelier <markand@malikania.fr>