]>
Commit | Line | Data |
---|---|---|
11143dcf MS |
1 | Contributing to CUPS |
2 | ==================== | |
549fc0f1 MS |
3 | |
4 | CUPS is developed by Apple Inc. and distributed as open source software under a | |
5 | combination of GNU GPL2 and GNU LGPL2 licenses with exceptions to allow | |
6 | developers on Apple's operating systems to develop CUPS-based software under | |
7 | alternate license terms. Significant contributions to CUPS must be licensed to | |
8 | Apple using the Apple Contributor Agreement: | |
9 | ||
10 | https://www.cups.org/AppleContributorAgreement_2011-03-10.pdf | |
11 | ||
12 | Contributions should be submitted as attachments to bug reports on the CUPS web | |
13 | site. Changes to existing source files should be submitted as unified diffs | |
14 | (both Subversion and Git produce this format by default) while new source files | |
d8ace9c1 MS |
15 | should be provided as-is or in an archive. Github pull requests can also be |
16 | used to submit changes. | |
549fc0f1 MS |
17 | |
18 | ||
11143dcf MS |
19 | How To Contact The Developers |
20 | ----------------------------- | |
549fc0f1 MS |
21 | |
22 | The CUPS mailing lists are the primary means of asking questions and informally | |
23 | discussing issues and feature requests with the CUPS developers and other | |
24 | experienced CUPS users and developers. The "cups" mailing list is intended for | |
25 | CUPS usage questions and new software announcements while the "cups-devel" | |
26 | mailing list provides a forum for CUPS developers and monitoring new bugs. | |
27 | ||
28 | ||
11143dcf MS |
29 | Interfaces |
30 | ---------- | |
549fc0f1 MS |
31 | |
32 | CUPS interfaces, including the C APIs and command-line arguments, environment | |
33 | variables, configuration files, and output format, are stable across patch | |
34 | versions and are generally backwards-compatible with interfaces used in prior | |
35 | major and minor versions. However, program interfaces such as those used by | |
36 | the scheduler to run filter, port monitor, and backend processes for job | |
37 | processing should only be considered stable from the point of view of a | |
38 | filter, port monitor, or backend. Software that simulates the scheduler in | |
39 | order to run those programs outside of CUPS must necessarily be updated when | |
40 | the corresponding interface is changed in a subsequent CUPS release, otherwise | |
41 | undefined behavior can occur. | |
42 | ||
43 | CUPS C APIs starting with an underscore (_) are considered to be private to | |
44 | CUPS and are not subject to the normal guarantees of stability between CUPS | |
45 | releases and must never be used in non-CUPS source code. Similarly, | |
46 | configuration and state files written by CUPS are considered private if a | |
47 | corresponding man page is not provided with the CUPS release. Never rely on | |
48 | undocumented files or formats when developing software for CUPS. Always use a | |
49 | published C API to access data stored in a file to avoid compatibility problems | |
50 | in the future. | |
51 | ||
52 | ||
11143dcf MS |
53 | Build System |
54 | ------------ | |
549fc0f1 MS |
55 | |
56 | The CUPS build system uses GNU autoconf to tailor the library to the local | |
57 | operating system. Project files for the current release of Microsoft Visual | |
58 | Studio are also provided for Microsoft Windows®. To improve portability, | |
59 | makefiles must not make use of features unique to GNU make. See the MAKEFILE | |
60 | GUIDELINES section for a description of the allowed make features and makefile | |
61 | guidelines. | |
62 | ||
63 | Additional GNU build programs such as GNU automake and GNU libtool must not be | |
64 | used. GNU automake produces non-portable makefiles which depend on GNU- | |
65 | specific extensions, and GNU libtool is not portable or reliable enough for | |
66 | CUPS. | |
67 | ||
68 | ||
11143dcf MS |
69 | Version Numbering |
70 | ----------------- | |
549fc0f1 MS |
71 | |
72 | CUPS uses a three-part version number separated by periods to represent the | |
73 | major, minor, and patch release numbers. Major release numbers indicate large | |
74 | design changes or backwards-incompatible changes to the CUPS API or CUPS | |
75 | Imaging API. Minor release numbers indicate new features and other smaller | |
76 | changes which are backwards-compatible with previous CUPS releases. Patch | |
77 | numbers indicate bug fixes to the previous feature or patch release. | |
78 | ||
d8ace9c1 MS |
79 | > Note: |
80 | > | |
81 | > When we talk about compatibility, we are talking about binary compatibility | |
82 | > for public APIs and output format compatibility for program interfaces. | |
83 | > Changes to configuration file formats or the default behavior of programs | |
84 | > are not generally considered incompatible as the upgrade process can | |
85 | > normally address such changes gracefully. | |
549fc0f1 MS |
86 | |
87 | Production releases use the plain version numbers: | |
88 | ||
89 | MAJOR.MINOR.PATCH | |
90 | 1.0.0 | |
91 | ... | |
92 | 1.1.0 | |
93 | ... | |
94 | 1.1.23 | |
95 | ... | |
96 | 2.0.0 | |
97 | ... | |
98 | 2.1.0 | |
99 | 2.1.1 | |
100 | 2.1.2 | |
101 | 2.1.3 | |
102 | ||
103 | The first production release in a MAJOR.MINOR series (MAJOR.MINOR.0) is called | |
104 | a feature release. Feature releases are the only releases that may contain new | |
105 | features. Subsequent production releases in a MAJOR.MINOR series may only | |
106 | contain bug fixes. | |
107 | ||
108 | Beta-test releases are identified by appending the letter B to the major and | |
109 | minor version numbers followed by the beta release number: | |
110 | ||
111 | MAJOR.MINORbNUMBER | |
112 | 2.2b1 | |
113 | ||
114 | Release candidates are identified by appending the letters RC to the major and | |
115 | minor version numbers followed by the release candidate number: | |
116 | ||
117 | MAJOR.MINORrcNUMBER | |
118 | 2.2rc1 | |
119 | ||
120 | ||
11143dcf MS |
121 | Coding Guidelines |
122 | ----------------- | |
549fc0f1 MS |
123 | |
124 | Contributed source code must follow the guidelines below. While the examples | |
125 | are for C and C++ source files, source code for other languages should conform | |
126 | to the same guidelines as allowed by the language. | |
127 | ||
128 | ||
11143dcf | 129 | ### Source Files |
549fc0f1 MS |
130 | |
131 | All source files names must be 16 characters or less in length to ensure | |
132 | compatibility with older UNIX filesystems. Source files containing functions | |
133 | have an extension of ".c" for C and ".cxx" for C++ source files. All other | |
134 | "include" files have an extension of ".h". Tabs are set to 8 characters or | |
135 | columns. | |
136 | ||
d8ace9c1 MS |
137 | > Note: |
138 | > | |
139 | > The ".cxx" extension is used because it is the only common C++ extension | |
8072030b | 140 | > between Linux, macOS, UNIX, and Windows. |
549fc0f1 MS |
141 | |
142 | The top of each source file contains a header giving the purpose or nature of | |
143 | the source file and the copyright and licensing notice: | |
144 | ||
145 | /* | |
146 | * Description of file contents. | |
147 | * | |
148 | * Copyright 2016 by Apple Inc. | |
149 | * | |
150 | * These coded instructions, statements, and computer programs are the | |
151 | * property of Apple Inc. and are protected by Federal copyright | |
152 | * law. Distribution and use rights are outlined in the file "LICENSE.txt" | |
153 | * which should have been included with this file. If this file is | |
154 | * file is missing or damaged, see the license at "http://www.cups.org/". | |
155 | */ | |
156 | ||
157 | For source files that are subject to the Apple OS-Developed Software exception, | |
158 | the following additional comment appears after the contact information: | |
159 | ||
160 | * This file is subject to the Apple OS-Developed Software exception. | |
161 | ||
162 | ||
11143dcf | 163 | ### Header Files |
549fc0f1 MS |
164 | |
165 | All public header files must include the "versioning.h" header file, or a header | |
166 | that does so. Function declarations are then "decorated" with the correct | |
167 | _CUPS_API_major_minor macro to define its availability based on the build | |
168 | environment, for example: | |
169 | ||
170 | extern int cupsDoThis(int foo, int bar) _CUPS_API_2_2; | |
171 | ||
172 | Private API header files must be named with the suffix "-private", for example | |
173 | the "cups.h" header file defines all of the public CUPS APIs while the | |
174 | "cups-private.h" header file defines all of the private CUPS APIs as well. | |
175 | Typically a private API header file will include the corresponding public API | |
176 | header file. | |
177 | ||
178 | ||
11143dcf | 179 | ### Comments |
549fc0f1 MS |
180 | |
181 | All source code utilizes block comments within functions to describe the | |
182 | operations being performed by a group of statements; avoid putting a comment | |
183 | per line unless absolutely necessary, and then consider refactoring the code | |
184 | so that it is not necessary. C source files use the block comment format | |
185 | ("/* comment */") since many vendor C compilers still do not support C99/C++ | |
186 | comments ("// comment"): | |
187 | ||
188 | /* | |
189 | * Clear the state array before we begin... | |
190 | */ | |
191 | ||
192 | for (i = 0; i < (sizeof(array) / sizeof(sizeof(array[0])); i ++) | |
193 | array[i] = CUPS_STATE_IDLE; | |
194 | ||
195 | /* | |
196 | * Wait for state changes on another thread... | |
197 | */ | |
198 | ||
199 | do | |
200 | { | |
201 | for (i = 0; i < (sizeof(array) / sizeof(sizeof(array[0])); i ++) | |
202 | if (array[i] != CUPS_STATE_IDLE) | |
203 | break; | |
204 | ||
205 | if (i == (sizeof(array) / sizeof(array[0]))) | |
206 | sleep(1); | |
207 | } while (i == (sizeof(array) / sizeof(array[0]))); | |
208 | ||
209 | ||
11143dcf | 210 | ### Indentation |
549fc0f1 MS |
211 | |
212 | All code blocks enclosed by brackets begin with the opening brace on a new | |
213 | line. The code then follows starting on a new line after the brace and is | |
214 | indented 2 spaces. The closing brace is then placed on a new line following | |
215 | the code at the original indentation: | |
216 | ||
d8ace9c1 MS |
217 | { |
218 | int i; /* Looping var */ | |
549fc0f1 | 219 | |
d8ace9c1 MS |
220 | /* |
221 | * Process foobar values from 0 to 999... | |
222 | */ | |
549fc0f1 | 223 | |
d8ace9c1 MS |
224 | for (i = 0; i < 1000; i ++) |
225 | { | |
226 | do_this(i); | |
227 | do_that(i); | |
228 | } | |
549fc0f1 | 229 | } |
549fc0f1 MS |
230 | |
231 | Single-line statements following "do", "else", "for", "if", and "while" are | |
232 | indented 2 spaces as well. Blocks of code in a "switch" block are indented 4 | |
233 | spaces after each "case" and "default" case: | |
234 | ||
235 | switch (array[i]) | |
236 | { | |
237 | case CUPS_STATE_IDLE : | |
238 | do_this(i); | |
239 | do_that(i); | |
240 | break; | |
241 | ||
242 | default : | |
243 | do_nothing(i); | |
244 | break; | |
245 | } | |
246 | ||
247 | ||
11143dcf | 248 | ### Spacing |
549fc0f1 MS |
249 | |
250 | A space follows each reserved word such as "if", "while", etc. Spaces are not | |
251 | inserted between a function name and the arguments in parenthesis. | |
252 | ||
253 | ||
11143dcf | 254 | ### Return Values |
549fc0f1 MS |
255 | |
256 | Parenthesis surround values returned from a function: | |
257 | ||
258 | return (CUPS_STATE_IDLE); | |
259 | ||
260 | ||
11143dcf | 261 | ### Functions |
549fc0f1 MS |
262 | |
263 | Functions with a global scope have a lowercase prefix followed by capitalized | |
264 | words, e.g., "cupsDoThis", "cupsDoThat", "cupsDoSomethingElse", etc. Private | |
d8ace9c1 MS |
265 | global functions begin with a leading underscore, e.g., "\_cupsDoThis", |
266 | "\_cupsDoThat", etc. | |
549fc0f1 MS |
267 | |
268 | Functions with a local scope are declared "static" with lowercase names and | |
d8ace9c1 | 269 | underscores between words, e.g., "do\_this", "do\_that", "do\_something\_else", etc. |
549fc0f1 MS |
270 | |
271 | Each function begins with a comment header describing what the function does, | |
272 | the possible input limits (if any), the possible output values (if any), and | |
273 | any special information needed: | |
274 | ||
275 | /* | |
276 | * 'do_this()' - Compute y = this(x). | |
277 | * | |
278 | * Notes: none. | |
279 | */ | |
280 | ||
281 | static float /* O - Inverse power value, 0.0 <= y <= 1.1 */ | |
282 | do_this(float x) /* I - Power value (0.0 <= x <= 1.1) */ | |
283 | { | |
284 | ... | |
285 | return (y); | |
286 | } | |
287 | ||
288 | Return/output values are indicated using an "O" prefix, input values are | |
289 | indicated using the "I" prefix, and values that are both input and output use | |
290 | the "IO" prefix for the corresponding in-line comment. | |
291 | ||
292 | The Mini-XML documentation generator also understands the following special | |
293 | text in the function description comment: | |
294 | ||
295 | @deprecated@ - Marks the function as deprecated (not recommended | |
296 | for new development and scheduled for removal) | |
297 | @since CUPS version@ - Marks the function as new in the specified version | |
298 | of CUPS. | |
299 | @private@ - Marks the function as private (same as starting the | |
300 | function name with an underscore) | |
301 | ||
302 | ||
11143dcf | 303 | ### Variables |
549fc0f1 MS |
304 | |
305 | Variables with a global scope are capitalized, e.g., "ThisVariable", | |
306 | "ThatVariable", "ThisStateVariable", etc. Globals in CUPS libraries are either | |
d8ace9c1 | 307 | part of the per-thread global values managed by the "\_cupsGlobals()" function |
549fc0f1 MS |
308 | or are suitably protected for concurrent access. Global variables should be |
309 | replaced by function arguments whenever possible. | |
310 | ||
311 | Variables with a local scope are lowercase with underscores between words, | |
d8ace9c1 | 312 | e.g., "this\_variable", "that\_variable", etc. Any "local global" variables |
549fc0f1 MS |
313 | shared by functions within a source file are declared "static". As for global |
314 | variables, local static variables are suitably protected for concurrent access. | |
315 | ||
316 | Each variable is declared on a separate line and is immediately followed by a | |
317 | comment block describing the variable: | |
318 | ||
319 | int ThisVariable; /* The current state of this */ | |
320 | static int that_variable; /* The current state of that */ | |
321 | ||
322 | ||
11143dcf | 323 | ### Types |
549fc0f1 | 324 | |
d8ace9c1 MS |
325 | All type names are lowercase with underscores between words and "\_t" appended |
326 | to the end of the name, e.g., "cups\_this\_type\_t", "cups\_that\_type\_t", etc. | |
549fc0f1 MS |
327 | Type names start with a prefix, typically "cups" or the name of the program, |
328 | to avoid conflicts with system types. Private type names start with an | |
d8ace9c1 | 329 | underscore, e.g., "\_cups\_this\_t", "\_cups\_that\_t", etc. |
549fc0f1 MS |
330 | |
331 | Each type has a comment block immediately after the typedef: | |
332 | ||
333 | typedef int cups_this_type_t; /* This type is for CUPS foobar options. */ | |
334 | ||
335 | ||
11143dcf | 336 | ### Structures |
549fc0f1 | 337 | |
d8ace9c1 MS |
338 | All structure names are lowercase with underscores between words and "\_s" |
339 | appended to the end of the name, e.g., "cups\_this\_s", "cups\_that\_s", etc. | |
549fc0f1 MS |
340 | Structure names start with a prefix, typically "cups" or the name of the |
341 | program, to avoid conflicts with system types. Private structure names start | |
d8ace9c1 | 342 | with an underscore, e.g., "\_cups\_this\_s", "\_cups\_that\_s", etc. |
549fc0f1 MS |
343 | |
344 | Each structure has a comment block immediately after the struct and each member | |
345 | is documented similar to the variable naming policy above: | |
346 | ||
347 | struct cups_this_struct_s /* This structure is for CUPS foobar options. */ | |
348 | { | |
349 | int this_member; /* Current state for this */ | |
350 | int that_member; /* Current state for that */ | |
351 | }; | |
352 | ||
353 | ||
11143dcf | 354 | ### Constants |
549fc0f1 MS |
355 | |
356 | All constant names are uppercase with underscores between words, e.g., | |
d8ace9c1 | 357 | "CUPS\_THIS\_CONSTANT", "CUPS\_THAT\_CONSTANT", etc. Constants begin with an |
549fc0f1 | 358 | uppercase prefix, typically "CUPS" or the program name. Private constants |
d8ace9c1 | 359 | start with an underscore, e.g., "\_CUPS\_THIS\_CONSTANT", "\_CUPS\_THAT\_CONSTANT", |
549fc0f1 MS |
360 | etc. |
361 | ||
362 | Typed enumerations should be used whenever possible to allow for type checking | |
363 | by the compiler. | |
364 | ||
365 | Comment blocks immediately follow each constant: | |
366 | ||
367 | typedef enum cups_tray_e /* Tray enumerations */ | |
368 | { | |
369 | CUPS_TRAY_THIS, /* This tray */ | |
370 | CUPS_TRAY_THAT /* That tray */ | |
371 | } cups_tray_t; | |
372 | ||
373 | ||
11143dcf | 374 | ## Makefile Guidelines |
549fc0f1 MS |
375 | |
376 | The following is a guide to the makefile-based build system used by CUPS. | |
377 | These standards have been developed over the years to allow CUPS to be built on | |
378 | as many systems and environments as possible. | |
379 | ||
380 | ||
11143dcf | 381 | ### General Organization |
549fc0f1 MS |
382 | |
383 | The CUPS source code is organized functionally into a top-level makefile, | |
384 | include file, and subdirectories each with their own makefile and dependencies | |
385 | files. The ".in" files are template files for the autoconf software and are | |
386 | used to generate a static version of the corresponding file. | |
387 | ||
388 | ||
11143dcf | 389 | ### Makefile Documentation |
549fc0f1 MS |
390 | |
391 | Each makefile starts with the standard CUPS header containing the description | |
392 | of the file, and CUPS copyright and license notice: | |
393 | ||
394 | # | |
395 | # Makefile for ... | |
396 | # | |
11143dcf | 397 | # Copyright 2017 by Apple Inc. |
549fc0f1 MS |
398 | # |
399 | # These coded instructions, statements, and computer programs are the | |
400 | # property of Apple Inc. and are protected by Federal copyright | |
401 | # law. Distribution and use rights are outlined in the file "LICENSE.txt" | |
402 | # which should have been included with this file. If this file is | |
403 | # file is missing or damaged, see the license at "http://www.cups.org/". | |
404 | # | |
405 | ||
406 | ||
11143dcf | 407 | ### Portable Makefile Construction |
549fc0f1 MS |
408 | |
409 | CUPS uses a common subset of make program syntax to ensure that the software | |
410 | can be compiled "out of the box" on as many systems as possible. The following | |
411 | is a list of assumptions we follow when constructing makefiles: | |
412 | ||
413 | - Targets; we assume that the make program supports the notion of simple | |
414 | targets of the form "name:" that perform tab-indented commands that follow | |
415 | the target, e.g.: | |
416 | ||
417 | target: | |
8cd7e4da | 418 | TAB target commands |
549fc0f1 MS |
419 | |
420 | - Dependencies; we assume that the make program supports recursive dependencies | |
421 | on targets, e.g.: | |
422 | ||
423 | target: foo bar | |
8cd7e4da | 424 | TAB target commands |
549fc0f1 MS |
425 | |
426 | foo: bla | |
8cd7e4da | 427 | TAB foo commands |
549fc0f1 MS |
428 | |
429 | bar: | |
8cd7e4da | 430 | TAB bar commands |
549fc0f1 MS |
431 | |
432 | bla: | |
8cd7e4da | 433 | TAB bla commands |
549fc0f1 MS |
434 | |
435 | - Variable Definition; we assume that the make program supports variable | |
436 | definition on the command-line or in the makefile using the following form: | |
437 | ||
438 | name=value | |
439 | ||
440 | - Variable Substitution; we assume that the make program supports variable | |
441 | substitution using the following forms: | |
442 | ||
443 | - $(name); substitutes the value of "name", | |
444 | - $(name:.old=.new); substitutes the value of "name" with the filename | |
445 | extension ".old" changed to ".new", | |
446 | - $(MAKEFLAGS); substitutes the command-line options passed to the | |
447 | program without the leading hyphen (-), | |
448 | - $$; substitutes a single $ character, | |
449 | - $<; substitutes the current source file or dependency, and | |
450 | - $@; substitutes the current target name. | |
451 | ||
452 | - Suffixes; we assume that the make program supports filename suffixes with | |
453 | assumed dependencies, e.g.: | |
454 | ||
455 | .SUFFIXES: .c .o | |
456 | .c.o: | |
8cd7e4da | 457 | TAB $(CC) $(CFLAGS) -o $@ -c $< |
549fc0f1 MS |
458 | |
459 | - Include Files; we assume that the make program supports the include | |
460 | directive, e.g.: | |
461 | ||
462 | include ../Makedefs | |
463 | include Dependencies | |
464 | ||
465 | - Comments; we assume that comments begin with a # character and proceed to the | |
466 | end of the current line. | |
467 | ||
468 | - Line Length; we assume that there is no practical limit to the length of | |
469 | lines. | |
470 | ||
471 | - Continuation of long lines; we assume that the \ character may be placed at | |
472 | the end of a line to concatenate two or more lines in a makefile to form a | |
473 | single long line. | |
474 | ||
475 | - Shell; we assume a POSIX-compatible shell is present on the build system. | |
476 | ||
477 | ||
11143dcf | 478 | ### Standard Variables |
549fc0f1 MS |
479 | |
480 | The following variables are defined in the "Makedefs" file generated by the | |
481 | autoconf software: | |
482 | ||
11143dcf MS |
483 | - `ALL_CFLAGS`; the combined C compiler options, |
484 | - `ALL_CXXFLAGS`; the combined C++ compiler options, | |
485 | - `AMANDIR`; the administrative man page installation directory (section 8/1m | |
549fc0f1 | 486 | depending on the platform), |
11143dcf MS |
487 | - `AR`; the library archiver command, |
488 | - `ARFLAGS`; options for the library archiver command, | |
489 | - `AWK`; the local awk command, | |
490 | - `BINDIR`; the binary installation directory, | |
491 | - `BUILDROOT`; optional installation prefix (defaults to DSTROOT), | |
492 | - `CC`; the C compiler command, | |
493 | - `CFLAGS`; options for the C compiler command, | |
494 | - `CHMOD`; the chmod command, | |
495 | - `CXX`; the C++ compiler command, | |
496 | - `CXXFLAGS`; options for the C++ compiler command, | |
497 | - `DATADIR`; the data file installation directory, | |
498 | - `DSO`; the C shared library building command, | |
499 | - `DSOXX`; the C++ shared library building command, | |
500 | - `DSOFLAGS`; options for the shared library building command, | |
501 | - `INCLUDEDIR`; the public header file installation directory, | |
502 | - `INSTALL`; the install command, | |
503 | - `INSTALL_BIN`; the program installation command, | |
504 | - `INSTALL_COMPDATA`; the compressed data file installation command, | |
505 | - `INSTALL_CONFIG`; the configuration file installation command, | |
506 | - `INSTALL_DATA`; the data file installation command, | |
507 | - `INSTALL_DIR`; the directory installation command, | |
508 | - `INSTALL_LIB`; the library installation command, | |
509 | - `INSTALL_MAN`; the documentation installation command, | |
510 | - `INSTALL_SCRIPT`; the shell script installation command, | |
511 | - `LD`; the linker command, | |
512 | - `LDFLAGS`; options for the linker, | |
513 | - `LIBDIR`; the library installation directory, | |
514 | - `LIBS`; libraries for all programs, | |
515 | - `LN`; the ln command, | |
516 | - `MAN1EXT`; extension for man pages in section 1, | |
517 | - `MAN3EXT`; extension for man pages in section 3, | |
518 | - `MAN5EXT`; extension for man pages in section 5, | |
519 | - `MAN7EXT`; extension for man pages in section 7, | |
520 | - `MAN8DIR`; subdirectory for man pages in section 8, | |
521 | - `MAN8EXT`; extension for man pages in section 8, | |
522 | - `MANDIR`; the man page installation directory, | |
523 | - `OPTIM`; common compiler optimization options, | |
524 | - `PRIVATEINCLUDE`; the private header file installation directory, | |
525 | - `RM`; the rm command, | |
526 | - `SHELL`; the sh (POSIX shell) command, | |
527 | - `STRIP`; the strip command, | |
528 | - `srcdir`; the source directory. | |
529 | ||
530 | ||
531 | ### Standard Targets | |
549fc0f1 MS |
532 | |
533 | The following standard targets are defined in each makefile: | |
534 | ||
11143dcf MS |
535 | - `all`; creates all target programs, libraries, and documentation files, |
536 | - `clean`; removes all target programs libraries, documentation files, and object | |
549fc0f1 | 537 | files, |
11143dcf | 538 | - `depend`; generates automatic dependencies for any C or C++ source files (also |
549fc0f1 | 539 | see "DEPENDENCIES"), |
11143dcf | 540 | - `distclean`; removes autoconf-generated files in addition to those removed by |
549fc0f1 | 541 | the "clean" target, |
11143dcf | 542 | - `install`; installs all distribution files in their corresponding locations |
549fc0f1 | 543 | (also see "INSTALL/UNINSTALL SUPPORT"), |
11143dcf | 544 | - `install-data`; installs all data files in their corresponding locations (also |
549fc0f1 | 545 | see "INSTALL/UNINSTALL SUPPORT"), |
11143dcf | 546 | - `install-exec`; installs all executable files in their corresponding locations |
549fc0f1 | 547 | (also see "INSTALL/UNINSTALL SUPPORT"), |
11143dcf | 548 | - `install-headers`; installs all include files in their corresponding locations |
549fc0f1 | 549 | (also see "INSTALL/UNINSTALL SUPPORT"), |
11143dcf | 550 | - `install-libs`; installs all library files in their corresponding locations |
549fc0f1 | 551 | (also see "INSTALL/UNINSTALL SUPPORT"), and |
11143dcf | 552 | - `uninstall`; removes all distribution files from their corresponding locations |
549fc0f1 MS |
553 | (also see "INSTALL/UNINSTALL SUPPORT"). |
554 | ||
555 | ||
11143dcf | 556 | ### Object Files |
549fc0f1 MS |
557 | |
558 | Object files (the result of compiling a C or C++ source file) have the | |
559 | extension ".o". | |
560 | ||
561 | ||
11143dcf | 562 | ### Programs |
549fc0f1 MS |
563 | |
564 | Program files are the result of linking object files and libraries together to | |
565 | form an executable file. A typical program target looks like: | |
566 | ||
567 | program: $(OBJS) | |
d8ace9c1 MS |
568 | TAB echo Linking $@... |
569 | TAB $(CC) $(LDFLAGS) -o $@ $(OBJS) $(LIBS) | |
549fc0f1 | 570 | |
11143dcf | 571 | ### Static Libraries |
549fc0f1 MS |
572 | |
573 | Static libraries have a prefix of "lib" and the extension ".a". A typical | |
574 | static library target looks like: | |
575 | ||
576 | libname.a: $(OBJECTS) | |
d8ace9c1 MS |
577 | TAB echo Creating $@... |
578 | TAB $(RM) $@ | |
579 | TAB $(AR) $(ARFLAGS) $@ $(OBJECTS) | |
580 | TAB $(RANLIB) $@ | |
549fc0f1 | 581 | |
11143dcf | 582 | ### Shared Libraries |
549fc0f1 MS |
583 | |
584 | Shared libraries have a prefix of "lib" and the extension ".dylib" or ".so" | |
585 | depending on the operating system. A typical shared library is composed of | |
586 | several targets that look like: | |
587 | ||
588 | libname.so: $(OBJECTS) | |
d8ace9c1 MS |
589 | TAB echo $(DSOCOMMAND) libname.so.$(DSOVERSION) ... |
590 | TAB $(DSOCOMMAND) libname.so.$(DSOVERSION) $(OBJECTS) | |
591 | TAB $(RM) libname.so libname.so.$(DSOMAJOR) | |
592 | TAB $(LN) libname.so.$(DSOVERSION) libname.so.$(DSOMAJOR) | |
593 | TAB $(LN) libname.so.$(DSOVERSION) libname.so | |
549fc0f1 MS |
594 | |
595 | libname.dylib: $(OBJECTS) | |
d8ace9c1 MS |
596 | TAB echo $(DSOCOMMAND) libname.$(DSOVERSION).dylib ... |
597 | TAB $(DSOCOMMAND) libname.$(DSOVERSION).dylib \ | |
598 | TAB TAB -install_name $(libdir)/libname.$(DSOMAJOR).dylib \ | |
599 | TAB TAB -current_version libname.$(DSOVERSION).dylib \ | |
600 | TAB TAB -compatibility_version $(DSOMAJOR).0 \ | |
601 | TAB TAB $(OBJECTS) $(LIBS) | |
602 | TAB $(RM) libname.dylib | |
603 | TAB $(RM) libname.$(DSOMAJOR).dylib | |
604 | TAB $(LN) libname.$(DSOVERSION).dylib libname.$(DSOMAJOR).dylib | |
605 | TAB $(LN) libname.$(DSOVERSION).dylib libname.dylib | |
606 | ||
11143dcf | 607 | ### Dependencies |
549fc0f1 MS |
608 | |
609 | Static dependencies are expressed in each makefile following the target, for | |
610 | example: | |
611 | ||
612 | foo: bar | |
613 | ||
614 | Static dependencies are only used when it is not possible to automatically | |
615 | generate them. Automatic dependencies are stored in a file named | |
616 | "Dependencies" and included at the end of the makefile. The following "depend" | |
617 | target rule is used to create the automatic dependencies: | |
618 | ||
619 | depend: | |
d8ace9c1 | 620 | TAB $(CC) -MM $(ALL_CFLAGS) $(OBJS:.o=.c) >Dependencies |
549fc0f1 | 621 | |
8072030b MS |
622 | We regenerate the automatic dependencies on an macOS system and express any |
623 | non-macOS dependencies statically in the makefile. | |
549fc0f1 MS |
624 | |
625 | ||
11143dcf | 626 | ### Install/Uninstall Support |
549fc0f1 MS |
627 | |
628 | All makefiles contains install and uninstall rules which install or remove the | |
629 | corresponding software. These rules must use the $(BUILDROOT) variable as a | |
630 | prefix to any installation directory so that CUPS can be installed in a | |
631 | temporary location for packaging by programs like rpmbuild. | |
632 | ||
11143dcf MS |
633 | The `INSTALL_BIN`, `INSTALL_COMPDATA`, `INSTALL_CONFIG`, `INSTALL_DATA`, |
634 | `INSTALL_DIR`, `INSTALL_LIB`, `INSTALL_MAN`, and `INSTALL_SCRIPT` variables | |
549fc0f1 MS |
635 | must be used when installing files so that the proper ownership and permissions |
636 | are set on the installed files. | |
637 | ||
11143dcf | 638 | The `$(RANLIB)` command must be run on any static libraries after installation |
549fc0f1 MS |
639 | since the symbol table is invalidated when the library is copied on some |
640 | platforms. |