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