michael@0: OVERVIEW of "ns/coreconf": michael@0: michael@0: This README file is an attempt to provide the reader with a simple michael@0: synopsis of the "ns/coreconf" build system which was originally michael@0: fundamentally designed and built to accomodate Netscape's binary michael@0: release model. Wherever possible, an attempt has been made to michael@0: comply with the NSPR 2.0 build system, including mimicing the michael@0: compiler/linker flags, and directory naming structure. The reader michael@0: should keep in mind that the system builds binary releases of michael@0: header files, class files, libraries, and executables on numerous michael@0: flavors of UNIX and Windows operating systems. Unfortunately, michael@0: no serious attempt has ever been made to incorporate an ability to michael@0: generate cross-platform binaries on an Apple MacIntosh platform. michael@0: michael@0: Note that this file will not attempt to redefine or document the michael@0: architecture of this system. However, documents on this subject michael@0: are available at the following URL: michael@0: michael@0: http://warp/hardcore/prj-ttools/specs/release/index.html michael@0: michael@0: michael@0: michael@0: DEPENDENCIES of "ns/coreconf": michael@0: michael@0: The "ns/coreconf" build system requires the specified versions of michael@0: the following platform-dependent tools: michael@0: michael@0: UNIX Platforms: michael@0: -------------- michael@0: gmake (version 3.74 or later) michael@0: perl 4.0 (NOTE: perl 5.003 or later recommended) michael@0: uname michael@0: michael@0: Windows Platforms: michael@0: ----------------- michael@0: gmake 3.74 (must use hacked Netscape version) michael@0: shmsdos.exe (contained in Netscape gmake.exe) michael@0: nsinstall.exe (contained in Netscape gmake.exe) michael@0: perl.exe (version 4.0 for everything except testing; michael@0: NOTE: MKS toolkit perl 5.002 is broken) michael@0: perl5.exe (for testing; michael@0: NOTE: perl 5.003 or later recommended; michael@0: MKS toolkit perl 5.002 is broken) michael@0: uname.exe (use nstools version) michael@0: michael@0: ENHANCEMENTS to "ns/coreconf": michael@0: michael@0: With the advent of Certificate Server 4.0 using the ns/coreconf michael@0: build system, several changes had to be made to enhance michael@0: ns/coreconf support for building Java/JNI classes/programs, as michael@0: well as libraries slated to be released as binaries. While the michael@0: following may not represent an exhaustive list of these changes, michael@0: it does attempt to be at least somewhat comprehensive: michael@0: michael@0: (1) During the course of these enhancements, a total of michael@0: four files have been modified, and four new files have michael@0: been added. michael@0: michael@0: The following files have been modified: michael@0: michael@0: - command.mk: removed old definition of JAR michael@0: michael@0: - config.mk: added include statement of new michael@0: "jdk.mk" file michael@0: michael@0: - ruleset.mk: allowed the $(MKPROG) variable to be michael@0: overridden by supplying it with a michael@0: default value of $(CC); augmented michael@0: numerous definitions to enhance michael@0: ability of ns/coreconf to produce michael@0: a more robust set of libraries; michael@0: added some JNI definitions; PACKAGE michael@0: definition may be overridden by new michael@0: "jdk.mk" file michael@0: michael@0: - rules.mk: separated the compile phase of a michael@0: program from the link phase of a michael@0: program such that a developer can michael@0: now strictly override program linkage michael@0: by simply supplying a $(MKPROG) michael@0: variable; augmented NETLIBDEPTH michael@0: to use CORE_DEPTH but retain backward michael@0: compatibility; added JNI section; michael@0: modified .PRECIOUS rule; michael@0: michael@0: The following files have been added: michael@0: michael@0: - README: this file; an ASCII-based text michael@0: document used to summarize the michael@0: ns/coreconf build system and michael@0: suitable (paginated) for printing michael@0: michael@0: - jdk.mk: a file comprising most (if not all) michael@0: of the default Java related build michael@0: information; the definitions in this michael@0: file are only included if NS_USE_JDK michael@0: has been defined michael@0: michael@0: - jniregen.pl: a perl script used to create a michael@0: dependency for when JNI files should michael@0: be regenerated (based upon any change michael@0: to the ".class" file from which the michael@0: ".h" file was originally generated) michael@0: michael@0: - outofdate.pl: a perl script used to create a michael@0: dependency for when ".class" files michael@0: should be regenerated (based upon michael@0: any change to the ".java" file michael@0: from which the ".class" file was michael@0: originally generated) michael@0: michael@0: (2) As stated above, the ns/coreconf build system now separates michael@0: the link phase of a program from its compilation phase. michael@0: While ns/coreconf still works exactly as it used to because michael@0: the $(MKPROG) variable is assigned $(CC) by default, a developer michael@0: may now override this behavior by simply supplying their michael@0: own unique value for $(MKPROG) on every platform. This allows michael@0: a program compiled with $(CC) to link with external libraries michael@0: that may contain "C++" linkage. Before this change, a michael@0: programmer would need to reference their own local copy of michael@0: rules.mk (see the ns/sectools/cmd/pk12util program for michael@0: an example of how this used to be accomplished). michael@0: michael@0: (3) Currently, the ns/coreconf build system differs from the michael@0: NSPR 2.0 build system which utilizes an "_s" to denote michael@0: static libraries from import libraries. In fact, the michael@0: ns/coreconf build system adds no prefixes or suffixes to michael@0: distinguish one version of static libraries from another. michael@0: Note that both the ns/coreconf build system as well as the michael@0: NSPR 2.0 build system do nothing to provide a method of michael@0: distinguishing 16-bit from 32-bit static libraries on the michael@0: same machine, either, since: michael@0: michael@0: a) this might only provide difficulty during michael@0: development, since static libraries always michael@0: need to be embedded within a program michael@0: (note this is highly unlikely, since libraries michael@0: for different platforms are subdivided via michael@0: a well-known subdirectory structure, and michael@0: a developer may use multiple trees for michael@0: development), michael@0: michael@0: b) this maintains backwards compatibility, michael@0: something very important since no legacy michael@0: programs will need to change their link phase, and michael@0: michael@0: c) Netscape as a company has dropped any plans michael@0: of future development of 16-bit products. michael@0: michael@0: (4) Since several members of the Hardcore Security group did michael@0: not favor NSPR 2.0's solution of adding an "_s" to static michael@0: libraries on Windows platforms as a method to distinguish michael@0: them from their import library cousins, a different solution michael@0: was proposed and has been recently implemented for ns/coreconf: michael@0: michael@0: - a 16 has been added as a suffix to both dynamic and michael@0: import libraries built on 16-bit Windows platforms michael@0: michael@0: - a 32 has been added as a suffix to both dynamic and michael@0: import libraries built on 32-bit Windows platforms michael@0: michael@0: Since the HCL release process currently only contains a michael@0: single instance of building a dynamic library, michael@0: ns/security/lib/fortcrypt/fort12.dll, the impact of this michael@0: change should be relatively small. (Note: HCL was the michael@0: old name of NSS.) michael@0: michael@0: It should be noted that although this would additionally michael@0: limit the 8.3 namespace on 16-bit platforms, it is highly michael@0: unlikely that any future development will be performed on michael@0: this platform. michael@0: michael@0: (5) The $(LIBRARY_VERSION) tag has been added to all non-static michael@0: libraries created on UNIX operating systems to alleviate michael@0: any future confusion for binary releases which utilize this michael@0: tag. Again, it should be noted that this tag is only michael@0: utilized on non-static libraries, since more than one michael@0: version of the library may need to exist simultaneously michael@0: if multiple products are utilized. michael@0: michael@0: Currently, only one HCL released library utilizes this tag: michael@0: michael@0: ns/security/lib/fortcrypt/fort12.a michael@0: (e. g. - in this library, the tag has been set to '12') michael@0: michael@0: Again, it should be noted that although this would michael@0: additionally limit the 8.3 namespace on 16-bit platforms, michael@0: it is highly unlikely that any future development will be michael@0: performed on this platform. michael@0: michael@0: (6) The $(JDK_DEBUG_SUFFIX) extension has been added to all michael@0: library and program names to support debug versions of michael@0: Java programs (e. g. - java_g, javac_g, etc). michael@0: michael@0: Once again, it should be noted that although this would michael@0: additionally limit the 8.3 namespace on 16-bit platforms, michael@0: it is highly unlikely that any future Java development michael@0: will be performed on this platform. michael@0: michael@0: (7) Most (if not all) default definitions for java have been michael@0: encapsulated within their own file, jdk.mk, which is michael@0: always included by default in ns/coreconf/config.mk. michael@0: However, the definitions within this file are only ever michael@0: activated if NS_USE_JDK has been set to be 1. michael@0: michael@0: michael@0: (8) Two perl scripts (jniregen.pl and outofdate.pl) have been michael@0: added to the system to foster a more robust development michael@0: environment for composing Java and JNI programs michael@0: utilizing the ns/coreconf build system. Both of these michael@0: perl scripts are related to resolving dependencies which michael@0: can not be accomplished through normal makefile dependencies. michael@0: michael@0: (9) This file, README, was created in an attempt to allow michael@0: developers who have familiarity with ns/coreconf a simple michael@0: roadmap for what has changed, as well as a top-level view of michael@0: what comprises ns/coreconf. This file was written in michael@0: ASCII (rather than HTML) primarily to promote simple michael@0: paginated printing. michael@0: michael@0: OVERVIEW of "config.mk": michael@0: michael@0: This file contains the configuration information necessary to michael@0: build each "Core Components" source module: michael@0: michael@0: include file name Purpose michael@0: =================== ======================================= michael@0: arch.mk source and release tags michael@0: michael@0: command.mk default command macros michael@0: (NOTE: may be overridden in $(OS_CONFIG).mk) michael@0: michael@0: $(OS_CONFIG).mk -specific macros michael@0: (dependent upon tags) michael@0: michael@0: tree.mk release tags michael@0: (dependent upon tags) michael@0: michael@0: module.mk source and release tags michael@0: (NOTE: A component is also called a module michael@0: or a subsystem. This file is dependent upon michael@0: $(MODULE) being defined on the command michael@0: line, as an environment variable, or in michael@0: individual makefiles, or more michael@0: appropriately, manifest.mn) michael@0: michael@0: version.mk release tags michael@0: (dependent upon $(MODULE) being defined on michael@0: the command line, as an environment variable, michael@0: or in individual makefiles, or more michael@0: appropriately, manifest.mn) michael@0: michael@0: location.mk macros to figure out binary code location michael@0: (dependent upon tags) michael@0: michael@0: source.mk -specific source path michael@0: (dependent upon , michael@0: , , and michael@0: tags) michael@0: michael@0: headers.mk include switch for support header files michael@0: (dependent upon , , , michael@0: and tags) michael@0: michael@0: prefix.mk compute program prefixes michael@0: michael@0: suffix.mk compute program suffixes michael@0: (dependent upon tags) michael@0: michael@0: jdk.mk define JDK michael@0: (dependent upon , michael@0: , and tags) michael@0: michael@0: ruleset.mk Master "Core Components" rule set michael@0: (should always be the last file michael@0: included by config.mk) michael@0: michael@0: michael@0: michael@0: OVERVIEW of "rules.mk": michael@0: michael@0: The "rules.mk" file consists of four sections. The first section michael@0: contains the "master" build rules for all binary releases. While michael@0: this section can (and should) largely be thought of as "language" michael@0: independent, it does utilize the "perl" scripting language to michael@0: perform both the "import" and "release" of binary modules. michael@0: michael@0: The rules which dwell in this section and their purpose: michael@0: michael@0: michael@0: CATEGORY/rule:: Purpose michael@0: =================== ======================================= michael@0: michael@0: GENERAL michael@0: ------- michael@0: all:: "default" all-encompassing rule which michael@0: performs "export libs program install" michael@0: michael@0: export:: recursively copy specified michael@0: cross-platform header files to the michael@0: $(SOURCE_XPHEADERS_DIR) directory; michael@0: recursively copy specified michael@0: machine-dependent header files to the michael@0: $(SOURCE_MDHEADERS_DIR) directory; michael@0: although all rules can be written to michael@0: repetively "chain" into other sections, michael@0: this rule is the most commonly used michael@0: rule to "chain" into other sections michael@0: such as Java providing a simple michael@0: mechanism which allows no need for michael@0: developers to memorize specialized michael@0: rules michael@0: michael@0: libs:: recursively build michael@0: static (archival) $(LIBRARY), shared michael@0: (dynamic link) $(SHARED_LIBRARY), michael@0: and/or import $(IMPORT_LIBRARY) michael@0: libraries michael@0: michael@0: program:: recursively build $(PROGRAM) michael@0: executable michael@0: michael@0: install:: recursively copy all libraries to michael@0: $(SOURCE_LIB_DIR) directory; michael@0: recursively copy all executables to michael@0: $(SOURCE_BIN_DIR) directory michael@0: michael@0: clean:: remove all files specified in the michael@0: $(ALL_TRASH) variable michael@0: michael@0: clobber:: synonym for "clean::" rule michael@0: michael@0: realclean:: remove all files specified by michael@0: $(wildcard *.OBJ), dist, and in michael@0: the $(ALL_TRASH) variable michael@0: michael@0: clobber_all:: synonym for "realclean::" rule michael@0: michael@0: private_export:: recursively copy specified michael@0: cross-platform header files to the michael@0: $(SOURCE_XPPRIVATE_DIR) directory michael@0: michael@0: michael@0: IMPORT michael@0: ------ michael@0: import:: uses perl script to retrieve specified michael@0: VERSION of the binary release from michael@0: $(RELEASE_TREE) michael@0: michael@0: RELEASE michael@0: ------- michael@0: release_clean:: remove all files from the michael@0: $(SOURCE_RELEASE_PREFIX) directory michael@0: michael@0: release:: place specified VERSION of the michael@0: binary release in the appropriate michael@0: $(RELEASE_TREE) directory michael@0: michael@0: release_export:: recursively copy specified michael@0: cross-platform header files to the michael@0: $(SOURCE_XPHEADERS_DIR)/include michael@0: directory michael@0: michael@0: release_md:: recursively copy all libraries to michael@0: $(SOURCE_RELEASE_PREFIX)/ michael@0: $(SOURCE_RELEASE_LIB_DIR) directory; michael@0: recursively copy all executables to michael@0: $(SOURCE_RELEASE_PREFIX)/ michael@0: $(SOURCE_RELEASE_BIN_DIR) directory michael@0: michael@0: release_jars:: use perl script to package appropriate michael@0: files in the $(XPCLASS_JAR), michael@0: $(XPHEADER_JAR), $(MDHEADER_JAR), and michael@0: $(MDBINARY_JAR) jar files michael@0: michael@0: release_cpdistdir:: use perl script to copy the michael@0: $(XPCLASS_JAR), $(XPHEADER_JAR), michael@0: $(MDHEADER_JAR), and $(MDBINARY_JAR) michael@0: jar files to the specified VERSION michael@0: of the $(RELEASE_TREE) directory michael@0: michael@0: michael@0: michael@0: TOOLS and AUTOMATION michael@0: -------------------- michael@0: platform:: tool used to display the platform name michael@0: as composed within the "arch.mk" file michael@0: michael@0: autobuild:: automation rule used by "Bonsai" and michael@0: "Tinderbox" to automatically generate michael@0: binary releases on various platforms michael@0: michael@0: tests:: automation tool used to run the michael@0: "regress" and "reporter" tools michael@0: on various regression test suites michael@0: michael@0: The second section of "rules.mk" primarily contains several michael@0: "language" dependent build rules for binary releases. These are michael@0: generally "computed" rules (created on the "fly"), and include michael@0: rules used by "C", "C++", assembly, the preprocessor, perl, and michael@0: the shell. michael@0: michael@0: The rules which dwell in this section and their purpose: michael@0: michael@0: michael@0: CATEGORY/rule:: Purpose michael@0: =================== ============================= michael@0: michael@0: LIBRARIES michael@0: --------- michael@0: $(LIBRARY): build the static library michael@0: specified by the $(LIBRARY) michael@0: variable michael@0: michael@0: $(IMPORT_LIBRARY): build the import library michael@0: specified by the michael@0: $(IMPORT_LIBRARY) variable michael@0: michael@0: $(SHARED_LIBRARY): build the shared michael@0: (dynamic link) library michael@0: specified by the michael@0: $(SHARED_LIBRARY) variable michael@0: michael@0: michael@0: PROGRAMS michael@0: -------- michael@0: $(PROGRAM): build the binary executable michael@0: specified by the $(PROGRAM) michael@0: rule michael@0: michael@0: $(OBJDIR)/ michael@0: $(PROG_PREFIX)%.pure: build the "purified" binary michael@0: executable specified by this michael@0: rule michael@0: michael@0: michael@0: OBJECTS michael@0: ------- michael@0: $(OBJDIR)/ michael@0: $(PROG_PREFIX)%$(OBJ_SUFFIX): build the object file michael@0: associated with the michael@0: makefile rule dependency: michael@0: michael@0: %.c = C file michael@0: %.cpp = C++ file michael@0: %.cc = C++ file michael@0: %.s = assembly file michael@0: %.S = assembly file michael@0: michael@0: $(OBJDIR)/ michael@0: $(PROG_PREFIX)%: (NOTE: deprecated rule) michael@0: build the object file michael@0: associated with the michael@0: makefile rule dependency: michael@0: michael@0: %.cpp = C++ file michael@0: michael@0: MISCELLANEOUS michael@0: ------------- michael@0: %.i: build the preprocessor file michael@0: associated with the michael@0: makefile rule dependency: michael@0: michael@0: %.c = C file michael@0: %.cpp = C++ file michael@0: michael@0: %: process the specified file michael@0: using the method associated michael@0: with the makefile rule michael@0: dependency: michael@0: michael@0: %.pl = perl script michael@0: %.sh = shell script michael@0: michael@0: alltags: tool used to recursively michael@0: create a "ctags"-style michael@0: file for reference michael@0: michael@0: The third section of "rules.mk' primarily contains several JAVA michael@0: "language" build rules for binary releases. These are also michael@0: generally "computed" rules (created on the "fly"). michael@0: michael@0: The rules which dwell in this section and their purpose: michael@0: michael@0: michael@0: CATEGORY/rule:: Purpose michael@0: =================== ============================= michael@0: $(JAVA_DESTPATH):: create directory specified michael@0: as the Java destination path michael@0: for where classes are michael@0: deposited michael@0: michael@0: $(JAVA_DESTPATH)/$(PACKAGE):: create directories specified michael@0: within the $(PACKAGE) michael@0: variable michael@0: michael@0: $(JMCSRCDIR):: create directory specified michael@0: as the JMC destination path michael@0: michael@0: $(JRI_HEADER_CFILES): used to generate/regenerate michael@0: JRI header files for "C" michael@0: michael@0: $(JRI_STUB_CFILES): used to generate/regenerate michael@0: JRI stub files for "C" michael@0: michael@0: $(JNI_HEADERS): used to generate/regenerate michael@0: JNI header files for "C" michael@0: michael@0: The fourth section of "rules.mk" primarily contains miscellaneous michael@0: build rules for binary releases. Many of these rules are here to michael@0: create new subdirectories, manage dependencies, and/or override michael@0: standard gmake "Makefile" rules. michael@0: michael@0: The rules which dwell in this section and their purpose: michael@0: michael@0: michael@0: CATEGORY/rule:: Purpose michael@0: =================== ============================= michael@0: michael@0: $(PUBLIC_EXPORT_DIR):: create directory used to michael@0: house public "C" header files michael@0: michael@0: $(PRIVATE_EXPORT_DIR):: create directory used to michael@0: house private "C" header michael@0: files michael@0: michael@0: $(SOURCE_XP_DIR)/ michael@0: release/include:: create directory used to michael@0: house "C" header files michael@0: contained in a release michael@0: michael@0: $(MKDEPENDENCIES):: for UNIX systems, create michael@0: a directory used to house michael@0: dependencies and utilize michael@0: the $(MKDEPEND) rule to michael@0: create them michael@0: michael@0: $(MKDEPEND):: cd to the dependency michael@0: directory and create them michael@0: michael@0: depend:: if $(OBJS) exist, perform the michael@0: $(MKDEPEND) rule followed by michael@0: the $(MKDEPENDENCIES) rule michael@0: michael@0: dependclean:: remove all files contained michael@0: in the dependency repository michael@0: michael@0: .DEFAULT: standard gmake rule michael@0: michael@0: .SUFFIXES: standard gmake rule michael@0: michael@0: .PRECIOUS: standard gmake rule michael@0: michael@0: .PHONY: standard gmake rule michael@0: