coreconf - master - niceSOFT/nss

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

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