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