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