"Fossies" - the Fresh Open Source Software Archive

Member "nss-3.55/nss/coreconf/README" (24 Jul 2020, 23405 Bytes) of package /linux/misc/nss-3.55.tar.gz:


As a special service "Fossies" has tried to format the requested text file into HTML format (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file. See also the last Fossies "Diffs" side-by-side code changes report for "README": 3.52.1_vs_3.53.

    1 OVERVIEW of "ns/coreconf":
    2 
    3     This README file is an attempt to provide the reader with a simple
    4     synopsis of the "ns/coreconf" build system which was originally
    5     fundamentally designed and built to accomodate Netscape's binary
    6     release model.  Wherever possible, an attempt has been made to
    7     comply with the NSPR 2.0 build system, including mimicing the
    8     compiler/linker flags, and directory naming structure.  The reader
    9     should keep in mind that the system builds binary releases of
   10     header files, class files, libraries, and executables on numerous
   11     flavors of UNIX and Windows operating systems.  Unfortunately,
   12     no serious attempt has ever been made to incorporate an ability to
   13     generate cross-platform binaries on an Apple MacIntosh platform.
   14 
   15     Note that this file will not attempt to redefine or document the
   16     architecture of this system.  However, documents on this subject
   17     are available at the following URL:
   18 
   19         http://warp/hardcore/prj-ttools/specs/release/index.html
   20 
   21 
   22 
   23 DEPENDENCIES of "ns/coreconf":
   24 
   25     The "ns/coreconf" build system requires the specified versions of
   26     the following platform-dependent tools:
   27 
   28         UNIX Platforms:
   29         --------------
   30         gmake (version 3.74 or later)
   31         perl 4.0 (NOTE:  perl 5.003 or later recommended)
   32         uname
   33 
   34         Windows Platforms:
   35         -----------------
   36         gmake 3.74 (must use hacked Netscape version)
   37         shmsdos.exe (contained in Netscape gmake.exe)
   38         nsinstall.exe (contained in Netscape gmake.exe)
   39         perl.exe (version 4.0 for everything except testing;
   40                   NOTE:  MKS toolkit perl 5.002 is broken)
   41         perl5.exe (for testing;
   42                    NOTE:  perl 5.003 or later recommended;
   43                           MKS toolkit perl 5.002 is broken)
   44         uname.exe (use nstools version)
   45 
   46 ENHANCEMENTS to "ns/coreconf":
   47 
   48     With the advent of Certificate Server 4.0 using the ns/coreconf
   49     build system, several changes had to be made to enhance
   50     ns/coreconf support for building Java/JNI classes/programs, as
   51     well as libraries slated to be released as binaries.  While the
   52     following may not represent an exhaustive list of these changes,
   53     it does attempt to be at least somewhat comprehensive:
   54 
   55         (1) During the course of these enhancements, a total of
   56             four files have been modified, and four new files have
   57             been added.
   58 
   59             The following files have been modified:
   60 
   61                 - command.mk:    removed old definition of JAR
   62 
   63                 - config.mk:     added include statement of new
   64                                  "jdk.mk" file
   65 
   66                 - ruleset.mk:    allowed the $(MKPROG) variable to be
   67                                  overridden by supplying it with a
   68                                  default value of $(CC); augmented
   69                                  numerous definitions to enhance
   70                                  ability of ns/coreconf to produce
   71                                  a more robust set of libraries;
   72                                  added some JNI definitions; PACKAGE
   73                                  definition may be overridden by new
   74                                  "jdk.mk" file
   75 
   76                 - rules.mk:      separated the compile phase of a
   77                                  program from the link phase of a
   78                                  program such that a developer can
   79                                  now strictly override program linkage
   80                                  by simply supplying a $(MKPROG)
   81                                  variable; augmented NETLIBDEPTH
   82                                  to use CORE_DEPTH but retain backward
   83                                  compatibility; added JNI section;
   84                                  modified .PRECIOUS rule;
   85 
   86             The following files have been added:
   87 
   88                 - README:        this file; an ASCII-based text
   89                                  document used to summarize the
   90                                  ns/coreconf build system and
   91                                  suitable (paginated) for printing
   92 
   93                 - jdk.mk:        a file comprising most (if not all)
   94                                  of the default Java related build
   95                                  information; the definitions in this
   96                                  file are only included if NS_USE_JDK
   97                                  has been defined
   98 
   99                 - jniregen.pl:   a perl script used to create a
  100                                  dependency for when JNI files should
  101                                  be regenerated (based upon any change
  102                                  to the ".class" file from which the
  103                                  ".h" file was originally generated)
  104 
  105                 - outofdate.pl:  a perl script used to create a
  106                                  dependency for when ".class" files
  107                                  should be regenerated (based upon
  108                                  any change to the ".java" file
  109                                  from which the ".class" file was
  110                                  originally generated)
  111 
  112         (2) As stated above, the ns/coreconf build system now separates
  113             the link phase of a program from its compilation phase.
  114             While ns/coreconf still works exactly as it used to because
  115             the $(MKPROG) variable is assigned $(CC) by default, a developer
  116             may now override this behavior by simply supplying their
  117             own unique value for $(MKPROG) on every platform.  This allows
  118             a program compiled with $(CC) to link with external libraries
  119             that may contain "C++" linkage.  Before this change, a
  120             programmer would need to reference their own local copy of
  121             rules.mk (see the ns/sectools/cmd/pk12util program for
  122             an example of how this used to be accomplished).
  123 
  124         (3) Currently, the ns/coreconf build system differs from the
  125             NSPR 2.0 build system which utilizes an "_s" to denote
  126             static libraries from import libraries.  In fact, the
  127             ns/coreconf build system adds no prefixes or suffixes to
  128             distinguish one version of static libraries from another.
  129             Note that both the ns/coreconf build system as well as the
  130             NSPR 2.0 build system do nothing to provide a method of
  131             distinguishing 16-bit from 32-bit static libraries on the
  132             same machine, either, since:
  133 
  134                 a) this might only provide difficulty during
  135                    development, since static libraries always
  136                    need to be embedded within a program
  137                    (note this is highly unlikely, since libraries
  138                     for different platforms are subdivided via
  139                     a well-known subdirectory structure, and
  140                     a developer may use multiple trees for
  141                     development),
  142 
  143                 b) this maintains backwards compatibility,
  144                    something very important since no legacy
  145                    programs will need to change their link phase, and
  146 
  147                 c) Netscape as a company has dropped any plans
  148                    of future development of 16-bit products.
  149 
  150         (4) Since several members of the Hardcore Security group did
  151             not favor NSPR 2.0's solution of adding an "_s" to static
  152             libraries on Windows platforms as a method to distinguish
  153             them from their import library cousins, a different solution
  154             was proposed and has been recently implemented for ns/coreconf:
  155 
  156                 - a 16 has been added as a suffix to both dynamic and
  157                   import libraries built on 16-bit Windows platforms
  158 
  159                 - a 32 has been added as a suffix to both dynamic and
  160                   import libraries built on 32-bit Windows platforms
  161 
  162             Since the HCL release process currently only contains a
  163             single instance of building a dynamic library,
  164             ns/security/lib/fortcrypt/fort12.dll, the impact of this
  165             change should be relatively small.  (Note: HCL was the
  166             old name of NSS.)
  167 
  168             It should be noted that although this would additionally
  169             limit the 8.3 namespace on 16-bit platforms, it is highly
  170             unlikely that any future development will be performed on
  171             this platform.
  172 
  173         (5) The $(LIBRARY_VERSION) tag has been added to all non-static
  174             libraries created on UNIX operating systems to alleviate
  175             any future confusion for binary releases which utilize this
  176             tag.  Again, it should be noted that this tag is only
  177             utilized on non-static libraries, since more than one
  178             version of the library may need to exist simultaneously
  179             if multiple products are utilized.
  180 
  181             Currently, only one HCL released library utilizes this tag:
  182 
  183                 ns/security/lib/fortcrypt/fort12.a
  184                 (e. g. - in this library, the tag has been set to '12')
  185 
  186             Again, it should be noted that although this would
  187             additionally limit the 8.3 namespace on 16-bit platforms,
  188             it is highly unlikely that any future development will be
  189             performed on this platform.
  190 
  191         (6) The $(JDK_DEBUG_SUFFIX) extension has been added to all
  192             library and program names to support debug versions of
  193             Java programs (e. g. - java_g, javac_g, etc).
  194 
  195             Once again, it should be noted that although this would
  196             additionally limit the 8.3 namespace on 16-bit platforms,
  197             it is highly unlikely that any future Java development
  198             will be performed on this platform.
  199 
  200         (7) Most (if not all) default definitions for java have been
  201             encapsulated within their own file, jdk.mk, which is
  202             always included by default in ns/coreconf/config.mk.
  203             However, the definitions within this file are only ever
  204             activated if NS_USE_JDK has been set to be 1.
  205 
  206 
  207         (8) Two perl scripts (jniregen.pl and outofdate.pl) have been
  208             added to the system to foster a more robust development
  209             environment for composing Java and JNI programs
  210             utilizing the ns/coreconf build system.  Both of these
  211             perl scripts are related to resolving dependencies which
  212             can not be accomplished through normal makefile dependencies.
  213 
  214         (9) This file, README, was created in an attempt to allow
  215             developers who have familiarity with ns/coreconf a simple
  216             roadmap for what has changed, as well as a top-level view of
  217             what comprises ns/coreconf.  This file was written in
  218             ASCII (rather than HTML) primarily to promote simple
  219             paginated printing.
  220 
  221 OVERVIEW of "config.mk":
  222 
  223     This file contains the configuration information necessary to
  224     build each "Core Components" source module:
  225 
  226         include file name       Purpose
  227         ===================     =======================================
  228         arch.mk                 source and release <architecture> tags
  229 
  230         command.mk              default command macros 
  231 				(NOTE: may be overridden in $(OS_CONFIG).mk)
  232 
  233         $(OS_CONFIG).mk         <architecture>-specific macros
  234                                 (dependent upon <architecture> tags)
  235 
  236         tree.mk                 release <tree> tags 
  237 				(dependent upon <architecture> tags)
  238 
  239         module.mk               source and release <component> tags 
  240 				(NOTE:  A component is also called a module 
  241 				or a subsystem.  This file is dependent upon
  242                                 $(MODULE) being defined on the command
  243                                 line, as an environment variable, or in
  244                                 individual makefiles, or more
  245                                 appropriately, manifest.mn)
  246 
  247         version.mk              release <version> tags 
  248 				(dependent upon $(MODULE) being defined on 
  249 				the command line, as an environment variable, 
  250 				or in individual makefiles, or more
  251                                 appropriately, manifest.mn)
  252 
  253         location.mk             macros to figure out binary code location
  254                                 (dependent upon <platform> tags)
  255 
  256         source.mk               <component>-specific source path
  257                                 (dependent upon <user_source_tree>,
  258                                 <source_component>, <version>, and
  259                                 <platform> tags)
  260 
  261         headers.mk              include switch for support header files 
  262 				(dependent upon <tree>, <component>, <version>,
  263                                 and <platform> tags)
  264 
  265         prefix.mk               compute program prefixes
  266 
  267         suffix.mk               compute program suffixes 
  268 				(dependent upon <architecture> tags)
  269 
  270         jdk.mk                  define JDK 
  271 				(dependent upon <architecture>,
  272                                 <source>, and <suffix> tags)
  273 
  274         ruleset.mk              Master "Core Components" rule set
  275                                 (should always be the last file
  276                                 included by config.mk)
  277 
  278 
  279 
  280 OVERVIEW of "rules.mk":
  281 
  282     The "rules.mk" file consists of four sections.  The first section
  283     contains the "master" build rules for all binary releases.  While
  284     this section can (and should) largely be thought of as "language"
  285     independent, it does utilize the "perl" scripting language to
  286     perform both the "import" and "release" of binary modules.
  287 
  288     The rules which dwell in this section and their purpose:
  289 
  290 
  291         CATEGORY/rule::         Purpose
  292         ===================     =======================================
  293 
  294         GENERAL
  295         -------
  296         all::                   "default" all-encompassing rule which
  297                                 performs "export libs program install"
  298 
  299         export::                recursively copy specified
  300                                 cross-platform header files to the
  301                                 $(SOURCE_XPHEADERS_DIR) directory;
  302                                 recursively copy specified
  303                                 machine-dependent header files to the
  304                                 $(SOURCE_MDHEADERS_DIR) directory;
  305                                 although all rules can be written to
  306                                 repetively "chain" into other sections,
  307                                 this rule is the most commonly used
  308                                 rule to "chain" into other sections
  309                                 such as Java providing a simple
  310                                 mechanism which allows no need for
  311                                 developers to memorize specialized
  312                                 rules
  313 
  314         libs::                  recursively build
  315                                 static (archival) $(LIBRARY), shared
  316                                 (dynamic link) $(SHARED_LIBRARY),
  317                                 and/or import $(IMPORT_LIBRARY)
  318                                 libraries
  319 
  320         program::               recursively build $(PROGRAM)
  321                                 executable
  322 
  323         install::               recursively copy all libraries to
  324                                 $(SOURCE_LIB_DIR) directory;
  325                                 recursively copy all executables to
  326                                 $(SOURCE_BIN_DIR) directory
  327 
  328         clean::                 remove all files specified in the
  329                                 $(ALL_TRASH) variable
  330 
  331         clobber::               synonym for "clean::" rule
  332 
  333         realclean::             remove all files specified by
  334                                 $(wildcard *.OBJ), dist, and in
  335                                 the $(ALL_TRASH) variable
  336 
  337         clobber_all::           synonym for "realclean::" rule
  338 
  339 
  340         RELEASE
  341         -------
  342         release_clean::         remove all files from the
  343                                 $(SOURCE_RELEASE_PREFIX) directory
  344 
  345         release::               place specified VERSION of the
  346                                 binary release in the appropriate
  347                                 $(RELEASE_TREE) directory
  348 
  349         release_export::        recursively copy specified
  350                                 cross-platform header files to the
  351                                 $(SOURCE_XPHEADERS_DIR)/include
  352                                 directory
  353 
  354         release_md::            recursively copy all libraries to
  355                                 $(SOURCE_RELEASE_PREFIX)/
  356                                 $(SOURCE_RELEASE_LIB_DIR) directory;
  357                                 recursively copy all executables to
  358                                 $(SOURCE_RELEASE_PREFIX)/
  359                                 $(SOURCE_RELEASE_BIN_DIR) directory
  360 
  361 
  362         TOOLS and AUTOMATION
  363         --------------------
  364         platform::              tool used to display the platform name
  365                                 as composed within the "arch.mk" file
  366 
  367         autobuild::             automation rule used by "Bonsai" and
  368                                 "Tinderbox" to automatically generate
  369                                 binary releases on various platforms
  370 
  371         check::                 automation tool used to run the
  372                                 "regress" and "reporter" tools 
  373                                 on various regression test suites
  374 
  375     The second section of "rules.mk" primarily contains several
  376     "language" dependent build rules for binary releases.  These are
  377     generally "computed" rules (created on the "fly"), and include
  378     rules used by "C", "C++", assembly, the preprocessor, perl, and
  379     the shell.
  380 
  381     The rules which dwell in this section and their purpose:
  382 
  383 
  384         CATEGORY/rule::                   Purpose
  385         ===================               =============================
  386 
  387         LIBRARIES
  388         ---------
  389         $(LIBRARY):                       build the static library
  390                                           specified by the $(LIBRARY)
  391                                           variable
  392 
  393         $(IMPORT_LIBRARY):                build the import library
  394                                           specified by the
  395                                           $(IMPORT_LIBRARY) variable
  396 
  397         $(SHARED_LIBRARY):                build the shared
  398                                           (dynamic link) library
  399                                           specified by the
  400                                           $(SHARED_LIBRARY) variable
  401 
  402 
  403         PROGRAMS
  404         --------
  405         $(PROGRAM):                       build the binary executable
  406                                           specified by the $(PROGRAM)
  407                                           rule
  408 
  409         $(OBJDIR)/
  410         $(PROG_PREFIX)%.pure:             build the "purified" binary
  411                                           executable specified by this
  412                                           rule
  413 
  414 
  415         OBJECTS
  416         -------
  417         $(OBJDIR)/
  418         $(PROG_PREFIX)%$(OBJ_SUFFIX):     build the object file
  419                                           associated with the
  420                                           makefile rule dependency:
  421 
  422                                               %.c   = C file
  423                                               %.cpp = C++ file
  424                                               %.cc  = C++ file
  425                                               %.s   = assembly file
  426                                               %.S   = assembly file
  427 
  428         $(OBJDIR)/
  429         $(PROG_PREFIX)%:                  (NOTE: deprecated rule)
  430                                           build the object file
  431                                           associated with the
  432                                           makefile rule dependency:
  433 
  434                                               %.cpp = C++ file
  435 
  436         MISCELLANEOUS
  437         -------------
  438         %.i:                              build the preprocessor file
  439                                           associated with the
  440                                           makefile rule dependency:
  441 
  442                                               %.c   = C file
  443                                               %.cpp = C++ file
  444 
  445         %:                                process the specified file
  446                                           using the method associated
  447                                           with the makefile rule
  448                                           dependency:
  449 
  450                                               %.pl = perl script
  451                                               %.sh = shell script
  452 
  453         alltags:                          tool used to recursively
  454                                           create a "ctags"-style
  455                                           file for reference
  456 
  457     The third section of "rules.mk' primarily contains several JAVA
  458     "language" build rules for binary releases.  These are also
  459     generally "computed" rules (created on the "fly").
  460 
  461     The rules which dwell in this section and their purpose:
  462 
  463 
  464         CATEGORY/rule::                   Purpose
  465         ===================               =============================
  466         $(JAVA_DESTPATH)::                create directory specified
  467                                           as the Java destination path
  468                                           for where classes are
  469                                           deposited
  470 
  471         $(JAVA_DESTPATH)/$(PACKAGE)::     create directories specified
  472                                           within the $(PACKAGE)
  473                                           variable
  474 
  475         $(JMCSRCDIR)::                    create directory specified
  476                                           as the JMC destination path
  477 
  478         $(JRI_HEADER_CFILES):             used to generate/regenerate
  479                                           JRI header files for "C"
  480 
  481         $(JRI_STUB_CFILES):               used to generate/regenerate
  482                                           JRI stub files for "C"
  483 
  484         $(JNI_HEADERS):                   used to generate/regenerate
  485                                           JNI header files for "C"
  486 
  487     The fourth section of "rules.mk" primarily contains miscellaneous
  488     build rules for binary releases.  Many of these rules are here to
  489     create new subdirectories, manage dependencies, and/or override
  490     standard gmake "Makefile" rules.
  491 
  492     The rules which dwell in this section and their purpose:
  493 
  494 
  495         CATEGORY/rule::                   Purpose
  496         ===================               =============================
  497 
  498         $(SOURCE_XP_DIR)/
  499         release/include::                 create directory used to
  500                                           house "C" header files
  501                                           contained in a release
  502 
  503         .DEFAULT:                         standard gmake rule
  504 
  505         .SUFFIXES:                        standard gmake rule
  506 
  507         .PRECIOUS:                        standard gmake rule
  508 
  509         .PHONY:                           standard gmake rule
  510