"Fossies" - the Fresh Open Source Software Archive

Member "nss-3.37.3/nss/coreconf/README" (5 Jun 2018, 25536 Bytes) of package /linux/misc/nss-3.37.3.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.

    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         private_export::        recursively copy specified
  340                                 cross-platform header files to the
  341                                 $(SOURCE_XPPRIVATE_DIR) directory
  342 
  343 
  344         IMPORT
  345         ------
  346         import::                uses perl script to retrieve specified
  347                                 VERSION of the binary release from
  348                                 $(RELEASE_TREE)
  349 
  350         RELEASE
  351         -------
  352         release_clean::         remove all files from the
  353                                 $(SOURCE_RELEASE_PREFIX) directory
  354 
  355         release::               place specified VERSION of the
  356                                 binary release in the appropriate
  357                                 $(RELEASE_TREE) directory
  358 
  359         release_export::        recursively copy specified
  360                                 cross-platform header files to the
  361                                 $(SOURCE_XPHEADERS_DIR)/include
  362                                 directory
  363 
  364         release_md::            recursively copy all libraries to
  365                                 $(SOURCE_RELEASE_PREFIX)/
  366                                 $(SOURCE_RELEASE_LIB_DIR) directory;
  367                                 recursively copy all executables to
  368                                 $(SOURCE_RELEASE_PREFIX)/
  369                                 $(SOURCE_RELEASE_BIN_DIR) directory
  370 
  371         release_jars::          use perl script to package appropriate
  372                                 files in the $(XPCLASS_JAR),
  373                                 $(XPHEADER_JAR), $(MDHEADER_JAR), and
  374                                 $(MDBINARY_JAR) jar files
  375 
  376         release_cpdistdir::     use perl script to copy the
  377                                 $(XPCLASS_JAR), $(XPHEADER_JAR),
  378                                 $(MDHEADER_JAR), and $(MDBINARY_JAR)
  379                                 jar files to the specified VERSION
  380                                 of the $(RELEASE_TREE) directory
  381 
  382 
  383 
  384         TOOLS and AUTOMATION
  385         --------------------
  386         platform::              tool used to display the platform name
  387                                 as composed within the "arch.mk" file
  388 
  389         autobuild::             automation rule used by "Bonsai" and
  390                                 "Tinderbox" to automatically generate
  391                                 binary releases on various platforms
  392 
  393         tests::                 automation tool used to run the
  394                                 "regress" and "reporter" tools 
  395                                 on various regression test suites
  396 
  397     The second section of "rules.mk" primarily contains several
  398     "language" dependent build rules for binary releases.  These are
  399     generally "computed" rules (created on the "fly"), and include
  400     rules used by "C", "C++", assembly, the preprocessor, perl, and
  401     the shell.
  402 
  403     The rules which dwell in this section and their purpose:
  404 
  405 
  406         CATEGORY/rule::                   Purpose
  407         ===================               =============================
  408 
  409         LIBRARIES
  410         ---------
  411         $(LIBRARY):                       build the static library
  412                                           specified by the $(LIBRARY)
  413                                           variable
  414 
  415         $(IMPORT_LIBRARY):                build the import library
  416                                           specified by the
  417                                           $(IMPORT_LIBRARY) variable
  418 
  419         $(SHARED_LIBRARY):                build the shared
  420                                           (dynamic link) library
  421                                           specified by the
  422                                           $(SHARED_LIBRARY) variable
  423 
  424 
  425         PROGRAMS
  426         --------
  427         $(PROGRAM):                       build the binary executable
  428                                           specified by the $(PROGRAM)
  429                                           rule
  430 
  431         $(OBJDIR)/
  432         $(PROG_PREFIX)%.pure:             build the "purified" binary
  433                                           executable specified by this
  434                                           rule
  435 
  436 
  437         OBJECTS
  438         -------
  439         $(OBJDIR)/
  440         $(PROG_PREFIX)%$(OBJ_SUFFIX):     build the object file
  441                                           associated with the
  442                                           makefile rule dependency:
  443 
  444                                               %.c   = C file
  445                                               %.cpp = C++ file
  446                                               %.cc  = C++ file
  447                                               %.s   = assembly file
  448                                               %.S   = assembly file
  449 
  450         $(OBJDIR)/
  451         $(PROG_PREFIX)%:                  (NOTE: deprecated rule)
  452                                           build the object file
  453                                           associated with the
  454                                           makefile rule dependency:
  455 
  456                                               %.cpp = C++ file
  457 
  458         MISCELLANEOUS
  459         -------------
  460         %.i:                              build the preprocessor file
  461                                           associated with the
  462                                           makefile rule dependency:
  463 
  464                                               %.c   = C file
  465                                               %.cpp = C++ file
  466 
  467         %:                                process the specified file
  468                                           using the method associated
  469                                           with the makefile rule
  470                                           dependency:
  471 
  472                                               %.pl = perl script
  473                                               %.sh = shell script
  474 
  475         alltags:                          tool used to recursively
  476                                           create a "ctags"-style
  477                                           file for reference
  478 
  479     The third section of "rules.mk' primarily contains several JAVA
  480     "language" build rules for binary releases.  These are also
  481     generally "computed" rules (created on the "fly").
  482 
  483     The rules which dwell in this section and their purpose:
  484 
  485 
  486         CATEGORY/rule::                   Purpose
  487         ===================               =============================
  488         $(JAVA_DESTPATH)::                create directory specified
  489                                           as the Java destination path
  490                                           for where classes are
  491                                           deposited
  492 
  493         $(JAVA_DESTPATH)/$(PACKAGE)::     create directories specified
  494                                           within the $(PACKAGE)
  495                                           variable
  496 
  497         $(JMCSRCDIR)::                    create directory specified
  498                                           as the JMC destination path
  499 
  500         $(JRI_HEADER_CFILES):             used to generate/regenerate
  501                                           JRI header files for "C"
  502 
  503         $(JRI_STUB_CFILES):               used to generate/regenerate
  504                                           JRI stub files for "C"
  505 
  506         $(JNI_HEADERS):                   used to generate/regenerate
  507                                           JNI header files for "C"
  508 
  509     The fourth section of "rules.mk" primarily contains miscellaneous
  510     build rules for binary releases.  Many of these rules are here to
  511     create new subdirectories, manage dependencies, and/or override
  512     standard gmake "Makefile" rules.
  513 
  514     The rules which dwell in this section and their purpose:
  515 
  516 
  517         CATEGORY/rule::                   Purpose
  518         ===================               =============================
  519 
  520         $(PUBLIC_EXPORT_DIR)::            create directory used to
  521                                           house public "C" header files
  522 
  523         $(PRIVATE_EXPORT_DIR)::           create directory used to
  524                                           house private "C" header
  525                                           files
  526 
  527         $(SOURCE_XP_DIR)/
  528         release/include::                 create directory used to
  529                                           house "C" header files
  530                                           contained in a release
  531 
  532         $(MKDEPENDENCIES)::               for UNIX systems, create
  533                                           a directory used to house
  534                                           dependencies and utilize
  535                                           the $(MKDEPEND) rule to
  536                                           create them
  537 
  538         $(MKDEPEND)::                     cd to the dependency
  539                                           directory and create them
  540 
  541         depend::                          if $(OBJS) exist, perform the
  542                                           $(MKDEPEND) rule followed by
  543                                           the $(MKDEPENDENCIES) rule
  544 
  545         dependclean::                     remove all files contained
  546                                           in the dependency repository
  547 
  548         .DEFAULT:                         standard gmake rule
  549 
  550         .SUFFIXES:                        standard gmake rule
  551 
  552         .PRECIOUS:                        standard gmake rule
  553 
  554         .PHONY:                           standard gmake rule
  555