diff options
Diffstat (limited to 'security/nss/coreconf/README')
| -rw-r--r-- | security/nss/coreconf/README | 555 |
1 files changed, 555 insertions, 0 deletions
diff --git a/security/nss/coreconf/README b/security/nss/coreconf/README new file mode 100644 index 000000000..4b1e410cb --- /dev/null +++ b/security/nss/coreconf/README @@ -0,0 +1,555 @@ +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 + |