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