summaryrefslogtreecommitdiff
path: root/security/coreconf/README
diff options
context:
space:
mode:
Diffstat (limited to 'security/coreconf/README')
-rw-r--r--security/coreconf/README563
1 files changed, 563 insertions, 0 deletions
diff --git a/security/coreconf/README b/security/coreconf/README
new file mode 100644
index 000000000..dcacd2a85
--- /dev/null
+++ b/security/coreconf/README
@@ -0,0 +1,563 @@
+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.
+
+ 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)
+
+ platform.mk source and release <platform> tags
+ (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
+ -------------
+ $(DIRS):: specifies a helper method
+ used by $(LOOP_THROUGH_DIRS)
+ to recursively change
+ directories and invoke
+ $(MAKE)
+
+ %.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
+
View Lorry Controller Status