aboutsummaryrefslogtreecommitdiffstats
path: root/doc/man/librarian.1
blob: 85a5d5f671b51c00f13b8e5b56b25d8e83e7c8da (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
.TH LIBRARIAN 1 LIBRARIAN
.SH NAME
librarian \- Return flags for compiling against libraries
.SH SYNOPSIS
.B librarian
.RI [ OPTION ]...\ [\-\-]
.RI [ VARIABLE ]...\ [ LIBRARY ...]
.SH DESCRIPTION
.B librarian
is used to print flags required when compiling or linking,
and want to use library that requires non-trival flags.
.PP
.B librarian
shall output the flags, required by the selected libraries,
.IR LIBRARY ,
that are listed under the selected variables,
.IR VARIABLE .
.PP
.I LIBRARY
can either be the name of the required library, the name of
the required library and a version of said library, or the
name of the required library and an accepted version range
of said library. If the same library name is used more than
once, the versions and version ranges are unioned. Recognised
formats are:
.TP
.I NAME
Any version of the library
.I NAME
will do.
.TP
.IB NAME = VERSION
Only version
.I VERSION
of the library
.I NAME
is acceptable. (Multiple version can be used by specifying
more than once.)
.TP
.IB NAME <= MAX
Any versions up to and including
.I MAX
of the library
.I NAME
will do.
.TP
.IB NAME < MAX
Any versions up to but excluding
.I MAX
of the library
.I NAME
will do.
.TP
.IB NAME >= MIN
At least version
.I MIN
of the library
.I NAME
is required.
.TP
.IB NAME > MIN
A greater version than version
.I MIN
of the library
.I NAME
is required.
.TP
.IB NAME >= MIN <= MAX
Combines
.IB NAME >= MIN
and
.IR NAME \fB<=\fP MAX .
.TP
.IB NAME >= MIN < MAX
Combines
.IB NAME >= MIN
and
.IR NAME \fB<\fP MAX .
.TP
.IB NAME > MIN <= MAX
Combines
.IB NAME > MIN
and
.IR NAME \fB<=\fP MAX .
.TP
.IB NAME > MIN < MAX
Combines
.IB NAME > MIN
and
.IR NAME \fB<\fP MAX .
.PP
The are not predefined values for
.IR VARIABLE ,
but the standardised ones are:
.TP
.B CFLAGS
Flags required by the compiler to compile the if the library
.I LIBRARY
is used. The library is a C library.
.TP
.B CPPFLAGS
Flags required by the C preprocessor to compile the if the
library
.I LIBRARY
is used.
.TP
.B LDFLAGS
Flags required by the linker to link the program when the
library
.I LIBRARY
is used.
.TP
.B CXXFLAGS
Flags required by the compiler to compile
the if the library
.I LIBRARY
is used. The library is a C++ library.
.TP
.B deps
Libraries the library
.I LIBRARY
is dependent on. Flags from these libraries should not
appear in the other variables unless the library
.I LIBRARY
requires them directly.
.PP
All variables should be in upper case unless they are
reserved. In the latter case, the are lower cased.
.PP
If
.I VARIABLE
is omitted, the process will exit with the value
.B 0
if all listed
libraries,
.IR LIBRARY ,
are available, and otherwise exit with the value
.BR 2 .
.PP
.B
librarian
files should be stored in
.BR PREFIX/share/librarian/ .
Its filename should be the name of the library, followed
by an
.B =
(equals-sign) and the version number.
.PP
Empty lines and lines starting with a
.B #
(she) in a
.B librarian
files are ignored. Other lines should begin with a variable
name and be followed by the required flags relevant to that
variable. For the variable
.BR deps ,
libraries that the library requires should be listed in the
same format the
.I LIBRARY
argument uses.
.SH OPTIONS
.TP
.B \-d
Add output for dependencies too. Should be used for
.B LDFLAGS
when linking statically.
.TP
.B \-l
Print the location of the files specified by
.IR LIBRARY .
.TP
.B \-o
Prefer-older libraries, when multiple versions are available.
.SH ENVIRONMENT
.B LIBRARIAN_PATH
Colon separated list of directories to search for librarian files.
.SH "EXIT STATUS"
.TP
.B 0
Program was successful.
.TP
.B 1
An error occurred.
.TP
.B 2
A library was not found.
.TP
.B 3
Usage error.
.SH RATIONALE
.BR pkg-config (1)
sucks.
.SH "FUTURE DIRECTION"
Will be implemented if needed in the real world:
.TP
*
When is used
.BR \-d ,
.B librarian
will try all versions of the libraries until it founds
a combination all selected libraries and their dependencies
are compatible with, rather than simply failing.
.TP
*
Library conflicts.
.SH "SEE ALSO"
.BR pkg-config (1)
.SH AUTHORS
Principal author, Mattias Andrée.  See the LICENSE file for the full
list of authors.
.SH LICENSE
MIT/X Consortium License.
.SH BUGS
Please report bugs to https://github.com/maandree/librarian/issues or to
maandree@member.fsf.org