The Tor Browser / file comparison
comparison: security/nss/coreconf/README
security/nss/coreconf/README
- branch
- TOR_BUG_9701
- changeset 15
- b8a032363ba2
equal
deleted
inserted
replaced
| -1:000000000000 | 0:f53a384569f7 |
|---|---|
| 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 |
