1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/security/nss/coreconf/README Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,555 @@
1.4 +OVERVIEW of "ns/coreconf":
1.5 +
1.6 + This README file is an attempt to provide the reader with a simple
1.7 + synopsis of the "ns/coreconf" build system which was originally
1.8 + fundamentally designed and built to accomodate Netscape's binary
1.9 + release model. Wherever possible, an attempt has been made to
1.10 + comply with the NSPR 2.0 build system, including mimicing the
1.11 + compiler/linker flags, and directory naming structure. The reader
1.12 + should keep in mind that the system builds binary releases of
1.13 + header files, class files, libraries, and executables on numerous
1.14 + flavors of UNIX and Windows operating systems. Unfortunately,
1.15 + no serious attempt has ever been made to incorporate an ability to
1.16 + generate cross-platform binaries on an Apple MacIntosh platform.
1.17 +
1.18 + Note that this file will not attempt to redefine or document the
1.19 + architecture of this system. However, documents on this subject
1.20 + are available at the following URL:
1.21 +
1.22 + http://warp/hardcore/prj-ttools/specs/release/index.html
1.23 +
1.24 +
1.25 +
1.26 +DEPENDENCIES of "ns/coreconf":
1.27 +
1.28 + The "ns/coreconf" build system requires the specified versions of
1.29 + the following platform-dependent tools:
1.30 +
1.31 + UNIX Platforms:
1.32 + --------------
1.33 + gmake (version 3.74 or later)
1.34 + perl 4.0 (NOTE: perl 5.003 or later recommended)
1.35 + uname
1.36 +
1.37 + Windows Platforms:
1.38 + -----------------
1.39 + gmake 3.74 (must use hacked Netscape version)
1.40 + shmsdos.exe (contained in Netscape gmake.exe)
1.41 + nsinstall.exe (contained in Netscape gmake.exe)
1.42 + perl.exe (version 4.0 for everything except testing;
1.43 + NOTE: MKS toolkit perl 5.002 is broken)
1.44 + perl5.exe (for testing;
1.45 + NOTE: perl 5.003 or later recommended;
1.46 + MKS toolkit perl 5.002 is broken)
1.47 + uname.exe (use nstools version)
1.48 +
1.49 +ENHANCEMENTS to "ns/coreconf":
1.50 +
1.51 + With the advent of Certificate Server 4.0 using the ns/coreconf
1.52 + build system, several changes had to be made to enhance
1.53 + ns/coreconf support for building Java/JNI classes/programs, as
1.54 + well as libraries slated to be released as binaries. While the
1.55 + following may not represent an exhaustive list of these changes,
1.56 + it does attempt to be at least somewhat comprehensive:
1.57 +
1.58 + (1) During the course of these enhancements, a total of
1.59 + four files have been modified, and four new files have
1.60 + been added.
1.61 +
1.62 + The following files have been modified:
1.63 +
1.64 + - command.mk: removed old definition of JAR
1.65 +
1.66 + - config.mk: added include statement of new
1.67 + "jdk.mk" file
1.68 +
1.69 + - ruleset.mk: allowed the $(MKPROG) variable to be
1.70 + overridden by supplying it with a
1.71 + default value of $(CC); augmented
1.72 + numerous definitions to enhance
1.73 + ability of ns/coreconf to produce
1.74 + a more robust set of libraries;
1.75 + added some JNI definitions; PACKAGE
1.76 + definition may be overridden by new
1.77 + "jdk.mk" file
1.78 +
1.79 + - rules.mk: separated the compile phase of a
1.80 + program from the link phase of a
1.81 + program such that a developer can
1.82 + now strictly override program linkage
1.83 + by simply supplying a $(MKPROG)
1.84 + variable; augmented NETLIBDEPTH
1.85 + to use CORE_DEPTH but retain backward
1.86 + compatibility; added JNI section;
1.87 + modified .PRECIOUS rule;
1.88 +
1.89 + The following files have been added:
1.90 +
1.91 + - README: this file; an ASCII-based text
1.92 + document used to summarize the
1.93 + ns/coreconf build system and
1.94 + suitable (paginated) for printing
1.95 +
1.96 + - jdk.mk: a file comprising most (if not all)
1.97 + of the default Java related build
1.98 + information; the definitions in this
1.99 + file are only included if NS_USE_JDK
1.100 + has been defined
1.101 +
1.102 + - jniregen.pl: a perl script used to create a
1.103 + dependency for when JNI files should
1.104 + be regenerated (based upon any change
1.105 + to the ".class" file from which the
1.106 + ".h" file was originally generated)
1.107 +
1.108 + - outofdate.pl: a perl script used to create a
1.109 + dependency for when ".class" files
1.110 + should be regenerated (based upon
1.111 + any change to the ".java" file
1.112 + from which the ".class" file was
1.113 + originally generated)
1.114 +
1.115 + (2) As stated above, the ns/coreconf build system now separates
1.116 + the link phase of a program from its compilation phase.
1.117 + While ns/coreconf still works exactly as it used to because
1.118 + the $(MKPROG) variable is assigned $(CC) by default, a developer
1.119 + may now override this behavior by simply supplying their
1.120 + own unique value for $(MKPROG) on every platform. This allows
1.121 + a program compiled with $(CC) to link with external libraries
1.122 + that may contain "C++" linkage. Before this change, a
1.123 + programmer would need to reference their own local copy of
1.124 + rules.mk (see the ns/sectools/cmd/pk12util program for
1.125 + an example of how this used to be accomplished).
1.126 +
1.127 + (3) Currently, the ns/coreconf build system differs from the
1.128 + NSPR 2.0 build system which utilizes an "_s" to denote
1.129 + static libraries from import libraries. In fact, the
1.130 + ns/coreconf build system adds no prefixes or suffixes to
1.131 + distinguish one version of static libraries from another.
1.132 + Note that both the ns/coreconf build system as well as the
1.133 + NSPR 2.0 build system do nothing to provide a method of
1.134 + distinguishing 16-bit from 32-bit static libraries on the
1.135 + same machine, either, since:
1.136 +
1.137 + a) this might only provide difficulty during
1.138 + development, since static libraries always
1.139 + need to be embedded within a program
1.140 + (note this is highly unlikely, since libraries
1.141 + for different platforms are subdivided via
1.142 + a well-known subdirectory structure, and
1.143 + a developer may use multiple trees for
1.144 + development),
1.145 +
1.146 + b) this maintains backwards compatibility,
1.147 + something very important since no legacy
1.148 + programs will need to change their link phase, and
1.149 +
1.150 + c) Netscape as a company has dropped any plans
1.151 + of future development of 16-bit products.
1.152 +
1.153 + (4) Since several members of the Hardcore Security group did
1.154 + not favor NSPR 2.0's solution of adding an "_s" to static
1.155 + libraries on Windows platforms as a method to distinguish
1.156 + them from their import library cousins, a different solution
1.157 + was proposed and has been recently implemented for ns/coreconf:
1.158 +
1.159 + - a 16 has been added as a suffix to both dynamic and
1.160 + import libraries built on 16-bit Windows platforms
1.161 +
1.162 + - a 32 has been added as a suffix to both dynamic and
1.163 + import libraries built on 32-bit Windows platforms
1.164 +
1.165 + Since the HCL release process currently only contains a
1.166 + single instance of building a dynamic library,
1.167 + ns/security/lib/fortcrypt/fort12.dll, the impact of this
1.168 + change should be relatively small. (Note: HCL was the
1.169 + old name of NSS.)
1.170 +
1.171 + It should be noted that although this would additionally
1.172 + limit the 8.3 namespace on 16-bit platforms, it is highly
1.173 + unlikely that any future development will be performed on
1.174 + this platform.
1.175 +
1.176 + (5) The $(LIBRARY_VERSION) tag has been added to all non-static
1.177 + libraries created on UNIX operating systems to alleviate
1.178 + any future confusion for binary releases which utilize this
1.179 + tag. Again, it should be noted that this tag is only
1.180 + utilized on non-static libraries, since more than one
1.181 + version of the library may need to exist simultaneously
1.182 + if multiple products are utilized.
1.183 +
1.184 + Currently, only one HCL released library utilizes this tag:
1.185 +
1.186 + ns/security/lib/fortcrypt/fort12.a
1.187 + (e. g. - in this library, the tag has been set to '12')
1.188 +
1.189 + Again, it should be noted that although this would
1.190 + additionally limit the 8.3 namespace on 16-bit platforms,
1.191 + it is highly unlikely that any future development will be
1.192 + performed on this platform.
1.193 +
1.194 + (6) The $(JDK_DEBUG_SUFFIX) extension has been added to all
1.195 + library and program names to support debug versions of
1.196 + Java programs (e. g. - java_g, javac_g, etc).
1.197 +
1.198 + Once again, it should be noted that although this would
1.199 + additionally limit the 8.3 namespace on 16-bit platforms,
1.200 + it is highly unlikely that any future Java development
1.201 + will be performed on this platform.
1.202 +
1.203 + (7) Most (if not all) default definitions for java have been
1.204 + encapsulated within their own file, jdk.mk, which is
1.205 + always included by default in ns/coreconf/config.mk.
1.206 + However, the definitions within this file are only ever
1.207 + activated if NS_USE_JDK has been set to be 1.
1.208 +
1.209 +
1.210 + (8) Two perl scripts (jniregen.pl and outofdate.pl) have been
1.211 + added to the system to foster a more robust development
1.212 + environment for composing Java and JNI programs
1.213 + utilizing the ns/coreconf build system. Both of these
1.214 + perl scripts are related to resolving dependencies which
1.215 + can not be accomplished through normal makefile dependencies.
1.216 +
1.217 + (9) This file, README, was created in an attempt to allow
1.218 + developers who have familiarity with ns/coreconf a simple
1.219 + roadmap for what has changed, as well as a top-level view of
1.220 + what comprises ns/coreconf. This file was written in
1.221 + ASCII (rather than HTML) primarily to promote simple
1.222 + paginated printing.
1.223 +
1.224 +OVERVIEW of "config.mk":
1.225 +
1.226 + This file contains the configuration information necessary to
1.227 + build each "Core Components" source module:
1.228 +
1.229 + include file name Purpose
1.230 + =================== =======================================
1.231 + arch.mk source and release <architecture> tags
1.232 +
1.233 + command.mk default command macros
1.234 + (NOTE: may be overridden in $(OS_CONFIG).mk)
1.235 +
1.236 + $(OS_CONFIG).mk <architecture>-specific macros
1.237 + (dependent upon <architecture> tags)
1.238 +
1.239 + tree.mk release <tree> tags
1.240 + (dependent upon <architecture> tags)
1.241 +
1.242 + module.mk source and release <component> tags
1.243 + (NOTE: A component is also called a module
1.244 + or a subsystem. This file is dependent upon
1.245 + $(MODULE) being defined on the command
1.246 + line, as an environment variable, or in
1.247 + individual makefiles, or more
1.248 + appropriately, manifest.mn)
1.249 +
1.250 + version.mk release <version> tags
1.251 + (dependent upon $(MODULE) being defined on
1.252 + the command line, as an environment variable,
1.253 + or in individual makefiles, or more
1.254 + appropriately, manifest.mn)
1.255 +
1.256 + location.mk macros to figure out binary code location
1.257 + (dependent upon <platform> tags)
1.258 +
1.259 + source.mk <component>-specific source path
1.260 + (dependent upon <user_source_tree>,
1.261 + <source_component>, <version>, and
1.262 + <platform> tags)
1.263 +
1.264 + headers.mk include switch for support header files
1.265 + (dependent upon <tree>, <component>, <version>,
1.266 + and <platform> tags)
1.267 +
1.268 + prefix.mk compute program prefixes
1.269 +
1.270 + suffix.mk compute program suffixes
1.271 + (dependent upon <architecture> tags)
1.272 +
1.273 + jdk.mk define JDK
1.274 + (dependent upon <architecture>,
1.275 + <source>, and <suffix> tags)
1.276 +
1.277 + ruleset.mk Master "Core Components" rule set
1.278 + (should always be the last file
1.279 + included by config.mk)
1.280 +
1.281 +
1.282 +
1.283 +OVERVIEW of "rules.mk":
1.284 +
1.285 + The "rules.mk" file consists of four sections. The first section
1.286 + contains the "master" build rules for all binary releases. While
1.287 + this section can (and should) largely be thought of as "language"
1.288 + independent, it does utilize the "perl" scripting language to
1.289 + perform both the "import" and "release" of binary modules.
1.290 +
1.291 + The rules which dwell in this section and their purpose:
1.292 +
1.293 +
1.294 + CATEGORY/rule:: Purpose
1.295 + =================== =======================================
1.296 +
1.297 + GENERAL
1.298 + -------
1.299 + all:: "default" all-encompassing rule which
1.300 + performs "export libs program install"
1.301 +
1.302 + export:: recursively copy specified
1.303 + cross-platform header files to the
1.304 + $(SOURCE_XPHEADERS_DIR) directory;
1.305 + recursively copy specified
1.306 + machine-dependent header files to the
1.307 + $(SOURCE_MDHEADERS_DIR) directory;
1.308 + although all rules can be written to
1.309 + repetively "chain" into other sections,
1.310 + this rule is the most commonly used
1.311 + rule to "chain" into other sections
1.312 + such as Java providing a simple
1.313 + mechanism which allows no need for
1.314 + developers to memorize specialized
1.315 + rules
1.316 +
1.317 + libs:: recursively build
1.318 + static (archival) $(LIBRARY), shared
1.319 + (dynamic link) $(SHARED_LIBRARY),
1.320 + and/or import $(IMPORT_LIBRARY)
1.321 + libraries
1.322 +
1.323 + program:: recursively build $(PROGRAM)
1.324 + executable
1.325 +
1.326 + install:: recursively copy all libraries to
1.327 + $(SOURCE_LIB_DIR) directory;
1.328 + recursively copy all executables to
1.329 + $(SOURCE_BIN_DIR) directory
1.330 +
1.331 + clean:: remove all files specified in the
1.332 + $(ALL_TRASH) variable
1.333 +
1.334 + clobber:: synonym for "clean::" rule
1.335 +
1.336 + realclean:: remove all files specified by
1.337 + $(wildcard *.OBJ), dist, and in
1.338 + the $(ALL_TRASH) variable
1.339 +
1.340 + clobber_all:: synonym for "realclean::" rule
1.341 +
1.342 + private_export:: recursively copy specified
1.343 + cross-platform header files to the
1.344 + $(SOURCE_XPPRIVATE_DIR) directory
1.345 +
1.346 +
1.347 + IMPORT
1.348 + ------
1.349 + import:: uses perl script to retrieve specified
1.350 + VERSION of the binary release from
1.351 + $(RELEASE_TREE)
1.352 +
1.353 + RELEASE
1.354 + -------
1.355 + release_clean:: remove all files from the
1.356 + $(SOURCE_RELEASE_PREFIX) directory
1.357 +
1.358 + release:: place specified VERSION of the
1.359 + binary release in the appropriate
1.360 + $(RELEASE_TREE) directory
1.361 +
1.362 + release_export:: recursively copy specified
1.363 + cross-platform header files to the
1.364 + $(SOURCE_XPHEADERS_DIR)/include
1.365 + directory
1.366 +
1.367 + release_md:: recursively copy all libraries to
1.368 + $(SOURCE_RELEASE_PREFIX)/
1.369 + $(SOURCE_RELEASE_LIB_DIR) directory;
1.370 + recursively copy all executables to
1.371 + $(SOURCE_RELEASE_PREFIX)/
1.372 + $(SOURCE_RELEASE_BIN_DIR) directory
1.373 +
1.374 + release_jars:: use perl script to package appropriate
1.375 + files in the $(XPCLASS_JAR),
1.376 + $(XPHEADER_JAR), $(MDHEADER_JAR), and
1.377 + $(MDBINARY_JAR) jar files
1.378 +
1.379 + release_cpdistdir:: use perl script to copy the
1.380 + $(XPCLASS_JAR), $(XPHEADER_JAR),
1.381 + $(MDHEADER_JAR), and $(MDBINARY_JAR)
1.382 + jar files to the specified VERSION
1.383 + of the $(RELEASE_TREE) directory
1.384 +
1.385 +
1.386 +
1.387 + TOOLS and AUTOMATION
1.388 + --------------------
1.389 + platform:: tool used to display the platform name
1.390 + as composed within the "arch.mk" file
1.391 +
1.392 + autobuild:: automation rule used by "Bonsai" and
1.393 + "Tinderbox" to automatically generate
1.394 + binary releases on various platforms
1.395 +
1.396 + tests:: automation tool used to run the
1.397 + "regress" and "reporter" tools
1.398 + on various regression test suites
1.399 +
1.400 + The second section of "rules.mk" primarily contains several
1.401 + "language" dependent build rules for binary releases. These are
1.402 + generally "computed" rules (created on the "fly"), and include
1.403 + rules used by "C", "C++", assembly, the preprocessor, perl, and
1.404 + the shell.
1.405 +
1.406 + The rules which dwell in this section and their purpose:
1.407 +
1.408 +
1.409 + CATEGORY/rule:: Purpose
1.410 + =================== =============================
1.411 +
1.412 + LIBRARIES
1.413 + ---------
1.414 + $(LIBRARY): build the static library
1.415 + specified by the $(LIBRARY)
1.416 + variable
1.417 +
1.418 + $(IMPORT_LIBRARY): build the import library
1.419 + specified by the
1.420 + $(IMPORT_LIBRARY) variable
1.421 +
1.422 + $(SHARED_LIBRARY): build the shared
1.423 + (dynamic link) library
1.424 + specified by the
1.425 + $(SHARED_LIBRARY) variable
1.426 +
1.427 +
1.428 + PROGRAMS
1.429 + --------
1.430 + $(PROGRAM): build the binary executable
1.431 + specified by the $(PROGRAM)
1.432 + rule
1.433 +
1.434 + $(OBJDIR)/
1.435 + $(PROG_PREFIX)%.pure: build the "purified" binary
1.436 + executable specified by this
1.437 + rule
1.438 +
1.439 +
1.440 + OBJECTS
1.441 + -------
1.442 + $(OBJDIR)/
1.443 + $(PROG_PREFIX)%$(OBJ_SUFFIX): build the object file
1.444 + associated with the
1.445 + makefile rule dependency:
1.446 +
1.447 + %.c = C file
1.448 + %.cpp = C++ file
1.449 + %.cc = C++ file
1.450 + %.s = assembly file
1.451 + %.S = assembly file
1.452 +
1.453 + $(OBJDIR)/
1.454 + $(PROG_PREFIX)%: (NOTE: deprecated rule)
1.455 + build the object file
1.456 + associated with the
1.457 + makefile rule dependency:
1.458 +
1.459 + %.cpp = C++ file
1.460 +
1.461 + MISCELLANEOUS
1.462 + -------------
1.463 + %.i: build the preprocessor file
1.464 + associated with the
1.465 + makefile rule dependency:
1.466 +
1.467 + %.c = C file
1.468 + %.cpp = C++ file
1.469 +
1.470 + %: process the specified file
1.471 + using the method associated
1.472 + with the makefile rule
1.473 + dependency:
1.474 +
1.475 + %.pl = perl script
1.476 + %.sh = shell script
1.477 +
1.478 + alltags: tool used to recursively
1.479 + create a "ctags"-style
1.480 + file for reference
1.481 +
1.482 + The third section of "rules.mk' primarily contains several JAVA
1.483 + "language" build rules for binary releases. These are also
1.484 + generally "computed" rules (created on the "fly").
1.485 +
1.486 + The rules which dwell in this section and their purpose:
1.487 +
1.488 +
1.489 + CATEGORY/rule:: Purpose
1.490 + =================== =============================
1.491 + $(JAVA_DESTPATH):: create directory specified
1.492 + as the Java destination path
1.493 + for where classes are
1.494 + deposited
1.495 +
1.496 + $(JAVA_DESTPATH)/$(PACKAGE):: create directories specified
1.497 + within the $(PACKAGE)
1.498 + variable
1.499 +
1.500 + $(JMCSRCDIR):: create directory specified
1.501 + as the JMC destination path
1.502 +
1.503 + $(JRI_HEADER_CFILES): used to generate/regenerate
1.504 + JRI header files for "C"
1.505 +
1.506 + $(JRI_STUB_CFILES): used to generate/regenerate
1.507 + JRI stub files for "C"
1.508 +
1.509 + $(JNI_HEADERS): used to generate/regenerate
1.510 + JNI header files for "C"
1.511 +
1.512 + The fourth section of "rules.mk" primarily contains miscellaneous
1.513 + build rules for binary releases. Many of these rules are here to
1.514 + create new subdirectories, manage dependencies, and/or override
1.515 + standard gmake "Makefile" rules.
1.516 +
1.517 + The rules which dwell in this section and their purpose:
1.518 +
1.519 +
1.520 + CATEGORY/rule:: Purpose
1.521 + =================== =============================
1.522 +
1.523 + $(PUBLIC_EXPORT_DIR):: create directory used to
1.524 + house public "C" header files
1.525 +
1.526 + $(PRIVATE_EXPORT_DIR):: create directory used to
1.527 + house private "C" header
1.528 + files
1.529 +
1.530 + $(SOURCE_XP_DIR)/
1.531 + release/include:: create directory used to
1.532 + house "C" header files
1.533 + contained in a release
1.534 +
1.535 + $(MKDEPENDENCIES):: for UNIX systems, create
1.536 + a directory used to house
1.537 + dependencies and utilize
1.538 + the $(MKDEPEND) rule to
1.539 + create them
1.540 +
1.541 + $(MKDEPEND):: cd to the dependency
1.542 + directory and create them
1.543 +
1.544 + depend:: if $(OBJS) exist, perform the
1.545 + $(MKDEPEND) rule followed by
1.546 + the $(MKDEPENDENCIES) rule
1.547 +
1.548 + dependclean:: remove all files contained
1.549 + in the dependency repository
1.550 +
1.551 + .DEFAULT: standard gmake rule
1.552 +
1.553 + .SUFFIXES: standard gmake rule
1.554 +
1.555 + .PRECIOUS: standard gmake rule
1.556 +
1.557 + .PHONY: standard gmake rule
1.558 +
