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