1OVERVIEW of "ns/coreconf":
2
3 This README file is an attempt to provide the reader with a simple
4 synopsis of the "ns/coreconf" build system which was originally
5 fundamentally designed and built to accomodate Netscape's binary
6 release model. Wherever possible, an attempt has been made to
7 comply with the NSPR 2.0 build system, including mimicing the
8 compiler/linker flags, and directory naming structure. The reader
9 should keep in mind that the system builds binary releases of
10 header files, class files, libraries, and executables on numerous
11 flavors of UNIX and Windows operating systems. Unfortunately,
12 no serious attempt has ever been made to incorporate an ability to
13 generate cross-platform binaries on an Apple MacIntosh platform.
14
15 Note that this file will not attempt to redefine or document the
16 architecture of this system. However, documents on this subject
17 are available at the following URL:
18
19 http://warp/hardcore/prj-ttools/specs/release/index.html
20
21
22
23DEPENDENCIES of "ns/coreconf":
24
25 The "ns/coreconf" build system requires the specified versions of
26 the following platform-dependent tools:
27
28 UNIX Platforms:
29 --------------
30 gmake (version 3.74 or later)
31 perl 4.0 (NOTE: perl 5.003 or later recommended)
32 uname
33
34 Windows Platforms:
35 -----------------
36 gmake 3.74 (must use hacked Netscape version)
37 shmsdos.exe (contained in Netscape gmake.exe)
38 nsinstall.exe (contained in Netscape gmake.exe)
39 perl.exe (version 4.0 for everything except testing;
40 NOTE: MKS toolkit perl 5.002 is broken)
41 perl5.exe (for testing;
42 NOTE: perl 5.003 or later recommended;
43 MKS toolkit perl 5.002 is broken)
44 uname.exe (use nstools version)
45
46ENHANCEMENTS to "ns/coreconf":
47
48 With the advent of Certificate Server 4.0 using the ns/coreconf
49 build system, several changes had to be made to enhance
50 ns/coreconf support for building Java/JNI classes/programs, as
51 well as libraries slated to be released as binaries. While the
52 following may not represent an exhaustive list of these changes,
53 it does attempt to be at least somewhat comprehensive:
54
55 (1) During the course of these enhancements, a total of
56 four files have been modified, and four new files have
57 been added.
58
59 The following files have been modified:
60
61 - command.mk: removed old definition of JAR
62
63 - config.mk: added include statement of new
64 "jdk.mk" file
65
66 - ruleset.mk: allowed the $(MKPROG) variable to be
67 overridden by supplying it with a
68 default value of $(CC); augmented
69 numerous definitions to enhance
70 ability of ns/coreconf to produce
71 a more robust set of libraries;
72 added some JNI definitions; PACKAGE
73 definition may be overridden by new
74 "jdk.mk" file
75
76 - rules.mk: separated the compile phase of a
77 program from the link phase of a
78 program such that a developer can
79 now strictly override program linkage
80 by simply supplying a $(MKPROG)
81 variable; augmented NETLIBDEPTH
82 to use CORE_DEPTH but retain backward
83 compatibility; added JNI section;
84 modified .PRECIOUS rule;
85
86 The following files have been added:
87
88 - README: this file; an ASCII-based text
89 document used to summarize the
90 ns/coreconf build system and
91 suitable (paginated) for printing
92
93 - jdk.mk: a file comprising most (if not all)
94 of the default Java related build
95 information; the definitions in this
96 file are only included if NS_USE_JDK
97 has been defined
98
99 - jniregen.pl: a perl script used to create a
100 dependency for when JNI files should
101 be regenerated (based upon any change
102 to the ".class" file from which the
103 ".h" file was originally generated)
104
105 - outofdate.pl: a perl script used to create a
106 dependency for when ".class" files
107 should be regenerated (based upon
108 any change to the ".java" file
109 from which the ".class" file was
110 originally generated)
111
112 (2) As stated above, the ns/coreconf build system now separates
113 the link phase of a program from its compilation phase.
114 While ns/coreconf still works exactly as it used to because
115 the $(MKPROG) variable is assigned $(CC) by default, a developer
116 may now override this behavior by simply supplying their
117 own unique value for $(MKPROG) on every platform. This allows
118 a program compiled with $(CC) to link with external libraries
119 that may contain "C++" linkage. Before this change, a
120 programmer would need to reference their own local copy of
121 rules.mk (see the ns/sectools/cmd/pk12util program for
122 an example of how this used to be accomplished).
123
124 (3) Currently, the ns/coreconf build system differs from the
125 NSPR 2.0 build system which utilizes an "_s" to denote
126 static libraries from import libraries. In fact, the
127 ns/coreconf build system adds no prefixes or suffixes to
128 distinguish one version of static libraries from another.
129 Note that both the ns/coreconf build system as well as the
130 NSPR 2.0 build system do nothing to provide a method of
131 distinguishing 16-bit from 32-bit static libraries on the
132 same machine, either, since:
133
134 a) this might only provide difficulty during
135 development, since static libraries always
136 need to be embedded within a program
137 (note this is highly unlikely, since libraries
138 for different platforms are subdivided via
139 a well-known subdirectory structure, and
140 a developer may use multiple trees for
141 development),
142
143 b) this maintains backwards compatibility,
144 something very important since no legacy
145 programs will need to change their link phase, and
146
147 c) Netscape as a company has dropped any plans
148 of future development of 16-bit products.
149
150 (4) Since several members of the Hardcore Security group did
151 not favor NSPR 2.0's solution of adding an "_s" to static
152 libraries on Windows platforms as a method to distinguish
153 them from their import library cousins, a different solution
154 was proposed and has been recently implemented for ns/coreconf:
155
156 - a 16 has been added as a suffix to both dynamic and
157 import libraries built on 16-bit Windows platforms
158
159 - a 32 has been added as a suffix to both dynamic and
160 import libraries built on 32-bit Windows platforms
161
162 Since the HCL release process currently only contains a
163 single instance of building a dynamic library,
164 ns/security/lib/fortcrypt/fort12.dll, the impact of this
165 change should be relatively small. (Note: HCL was the
166 old name of NSS.)
167
168 It should be noted that although this would additionally
169 limit the 8.3 namespace on 16-bit platforms, it is highly
170 unlikely that any future development will be performed on
171 this platform.
172
173 (5) The $(LIBRARY_VERSION) tag has been added to all non-static
174 libraries created on UNIX operating systems to alleviate
175 any future confusion for binary releases which utilize this
176 tag. Again, it should be noted that this tag is only
177 utilized on non-static libraries, since more than one
178 version of the library may need to exist simultaneously
179 if multiple products are utilized.
180
181 Currently, only one HCL released library utilizes this tag:
182
183 ns/security/lib/fortcrypt/fort12.a
184 (e. g. - in this library, the tag has been set to '12')
185
186 Again, it should be noted that although this would
187 additionally limit the 8.3 namespace on 16-bit platforms,
188 it is highly unlikely that any future development will be
189 performed on this platform.
190
191 (6) The $(JDK_DEBUG_SUFFIX) extension has been added to all
192 library and program names to support debug versions of
193 Java programs (e. g. - java_g, javac_g, etc).
194
195 Once again, it should be noted that although this would
196 additionally limit the 8.3 namespace on 16-bit platforms,
197 it is highly unlikely that any future Java development
198 will be performed on this platform.
199
200 (7) Most (if not all) default definitions for java have been
201 encapsulated within their own file, jdk.mk, which is
202 always included by default in ns/coreconf/config.mk.
203 However, the definitions within this file are only ever
204 activated if NS_USE_JDK has been set to be 1.
205
206
207 (8) Two perl scripts (jniregen.pl and outofdate.pl) have been
208 added to the system to foster a more robust development
209 environment for composing Java and JNI programs
210 utilizing the ns/coreconf build system. Both of these
211 perl scripts are related to resolving dependencies which
212 can not be accomplished through normal makefile dependencies.
213
214 (9) This file, README, was created in an attempt to allow
215 developers who have familiarity with ns/coreconf a simple
216 roadmap for what has changed, as well as a top-level view of
217 what comprises ns/coreconf. This file was written in
218 ASCII (rather than HTML) primarily to promote simple
219 paginated printing.
220
221OVERVIEW of "config.mk":
222
223 This file contains the configuration information necessary to
224 build each "Core Components" source module:
225
226 include file name Purpose
227 =================== =======================================
228 arch.mk source and release <architecture> tags
229
230 command.mk default command macros
231 (NOTE: may be overridden in $(OS_CONFIG).mk)
232
233 $(OS_CONFIG).mk <architecture>-specific macros
234 (dependent upon <architecture> tags)
235
236 tree.mk release <tree> tags
237 (dependent upon <architecture> tags)
238
239 module.mk source and release <component> tags
240 (NOTE: A component is also called a module
241 or a subsystem. This file is dependent upon
242 $(MODULE) being defined on the command
243 line, as an environment variable, or in
244 individual makefiles, or more
245 appropriately, manifest.mn)
246
247 version.mk release <version> tags
248 (dependent upon $(MODULE) being defined on
249 the command line, as an environment variable,
250 or in individual makefiles, or more
251 appropriately, manifest.mn)
252
253 location.mk macros to figure out binary code location
254 (dependent upon <platform> tags)
255
256 source.mk <component>-specific source path
257 (dependent upon <user_source_tree>,
258 <source_component>, <version>, and
259 <platform> tags)
260
261 headers.mk include switch for support header files
262 (dependent upon <tree>, <component>, <version>,
263 and <platform> tags)
264
265 prefix.mk compute program prefixes
266
267 suffix.mk compute program suffixes
268 (dependent upon <architecture> tags)
269
270 jdk.mk define JDK
271 (dependent upon <architecture>,
272 <source>, and <suffix> tags)
273
274 ruleset.mk Master "Core Components" rule set
275 (should always be the last file
276 included by config.mk)
277
278
279
280OVERVIEW of "rules.mk":
281
282 The "rules.mk" file consists of four sections. The first section
283 contains the "master" build rules for all binary releases. While
284 this section can (and should) largely be thought of as "language"
285 independent, it does utilize the "perl" scripting language to
286 perform both the "import" and "release" of binary modules.
287
288 The rules which dwell in this section and their purpose:
289
290
291 CATEGORY/rule:: Purpose
292 =================== =======================================
293
294 GENERAL
295 -------
296 all:: "default" all-encompassing rule which
297 performs "export libs program install"
298
299 export:: recursively copy specified
300 cross-platform header files to the
301 $(SOURCE_XPHEADERS_DIR) directory;
302 recursively copy specified
303 machine-dependent header files to the
304 $(SOURCE_MDHEADERS_DIR) directory;
305 although all rules can be written to
306 repetively "chain" into other sections,
307 this rule is the most commonly used
308 rule to "chain" into other sections
309 such as Java providing a simple
310 mechanism which allows no need for
311 developers to memorize specialized
312 rules
313
314 libs:: recursively build
315 static (archival) $(LIBRARY), shared
316 (dynamic link) $(SHARED_LIBRARY),
317 and/or import $(IMPORT_LIBRARY)
318 libraries
319
320 program:: recursively build $(PROGRAM)
321 executable
322
323 install:: recursively copy all libraries to
324 $(SOURCE_LIB_DIR) directory;
325 recursively copy all executables to
326 $(SOURCE_BIN_DIR) directory
327
328 clean:: remove all files specified in the
329 $(ALL_TRASH) variable
330
331 clobber:: synonym for "clean::" rule
332
333 realclean:: remove all files specified by
334 $(wildcard *.OBJ), dist, and in
335 the $(ALL_TRASH) variable
336
337 clobber_all:: synonym for "realclean::" rule
338
339
340 RELEASE
341 -------
342 release_clean:: remove all files from the
343 $(SOURCE_RELEASE_PREFIX) directory
344
345 release:: place specified VERSION of the
346 binary release in the appropriate
347 $(RELEASE_TREE) directory
348
349 release_export:: recursively copy specified
350 cross-platform header files to the
351 $(SOURCE_XPHEADERS_DIR)/include
352 directory
353
354 release_md:: recursively copy all libraries to
355 $(SOURCE_RELEASE_PREFIX)/
356 $(SOURCE_RELEASE_LIB_DIR) directory;
357 recursively copy all executables to
358 $(SOURCE_RELEASE_PREFIX)/
359 $(SOURCE_RELEASE_BIN_DIR) directory
360
361
362 TOOLS and AUTOMATION
363 --------------------
364 platform:: tool used to display the platform name
365 as composed within the "arch.mk" file
366
367 autobuild:: automation rule used by "Bonsai" and
368 "Tinderbox" to automatically generate
369 binary releases on various platforms
370
371 check:: automation tool used to run the
372 "regress" and "reporter" tools
373 on various regression test suites
374
375 The second section of "rules.mk" primarily contains several
376 "language" dependent build rules for binary releases. These are
377 generally "computed" rules (created on the "fly"), and include
378 rules used by "C", "C++", assembly, the preprocessor, perl, and
379 the shell.
380
381 The rules which dwell in this section and their purpose:
382
383
384 CATEGORY/rule:: Purpose
385 =================== =============================
386
387 LIBRARIES
388 ---------
389 $(LIBRARY): build the static library
390 specified by the $(LIBRARY)
391 variable
392
393 $(IMPORT_LIBRARY): build the import library
394 specified by the
395 $(IMPORT_LIBRARY) variable
396
397 $(SHARED_LIBRARY): build the shared
398 (dynamic link) library
399 specified by the
400 $(SHARED_LIBRARY) variable
401
402
403 PROGRAMS
404 --------
405 $(PROGRAM): build the binary executable
406 specified by the $(PROGRAM)
407 rule
408
409 $(OBJDIR)/
410 $(PROG_PREFIX)%.pure: build the "purified" binary
411 executable specified by this
412 rule
413
414
415 OBJECTS
416 -------
417 $(OBJDIR)/
418 $(PROG_PREFIX)%$(OBJ_SUFFIX): build the object file
419 associated with the
420 makefile rule dependency:
421
422 %.c = C file
423 %.cpp = C++ file
424 %.cc = C++ file
425 %.s = assembly file
426 %.S = assembly file
427
428 $(OBJDIR)/
429 $(PROG_PREFIX)%: (NOTE: deprecated rule)
430 build the object file
431 associated with the
432 makefile rule dependency:
433
434 %.cpp = C++ file
435
436 MISCELLANEOUS
437 -------------
438 %.i: build the preprocessor file
439 associated with the
440 makefile rule dependency:
441
442 %.c = C file
443 %.cpp = C++ file
444
445 %: process the specified file
446 using the method associated
447 with the makefile rule
448 dependency:
449
450 %.pl = perl script
451 %.sh = shell script
452
453 alltags: tool used to recursively
454 create a "ctags"-style
455 file for reference
456
457 The third section of "rules.mk' primarily contains several JAVA
458 "language" build rules for binary releases. These are also
459 generally "computed" rules (created on the "fly").
460
461 The rules which dwell in this section and their purpose:
462
463
464 CATEGORY/rule:: Purpose
465 =================== =============================
466 $(JAVA_DESTPATH):: create directory specified
467 as the Java destination path
468 for where classes are
469 deposited
470
471 $(JAVA_DESTPATH)/$(PACKAGE):: create directories specified
472 within the $(PACKAGE)
473 variable
474
475 $(JMCSRCDIR):: create directory specified
476 as the JMC destination path
477
478 $(JRI_HEADER_CFILES): used to generate/regenerate
479 JRI header files for "C"
480
481 $(JRI_STUB_CFILES): used to generate/regenerate
482 JRI stub files for "C"
483
484 $(JNI_HEADERS): used to generate/regenerate
485 JNI header files for "C"
486
487 The fourth section of "rules.mk" primarily contains miscellaneous
488 build rules for binary releases. Many of these rules are here to
489 create new subdirectories, manage dependencies, and/or override
490 standard gmake "Makefile" rules.
491
492 The rules which dwell in this section and their purpose:
493
494
495 CATEGORY/rule:: Purpose
496 =================== =============================
497
498 $(SOURCE_XP_DIR)/
499 release/include:: create directory used to
500 house "C" header files
501 contained in a release
502
503 .DEFAULT: standard gmake rule
504
505 .SUFFIXES: standard gmake rule
506
507 .PRECIOUS: standard gmake rule
508
509 .PHONY: standard gmake rule
510
511