diff options
| -rw-r--r-- | CHANGES.md | 120 | ||||
| -rw-r--r-- | CONTRIBUTING.md | 11 | ||||
| -rw-r--r-- | Configurations/README-design.md | 218 | ||||
| -rw-r--r-- | Configurations/README.md | 140 | ||||
| -rwxr-xr-x | Configure | 2 | ||||
| -rw-r--r-- | HACKING.md | 29 | ||||
| -rw-r--r-- | INSTALL.md | 24 | ||||
| -rw-r--r-- | NOTES-Android.md | 45 | ||||
| -rw-r--r-- | NOTES-DJGPP.md | 36 | ||||
| -rw-r--r-- | NOTES-Perl.md | 50 | ||||
| -rw-r--r-- | NOTES-Unix.md | 61 | ||||
| -rw-r--r-- | NOTES-VMS.md | 32 | ||||
| -rw-r--r-- | NOTES-Valgrind.md | 34 | ||||
| -rw-r--r-- | README-Engine.md | 335 | ||||
| -rw-r--r-- | README-FIPS.md | 3 | ||||
| -rw-r--r-- | README.md | 14 | ||||
| -rw-r--r-- | VERSION.txt | 7 | ||||
| -rw-r--r-- | crypto/README-sparse_array.md | 17 | ||||
| -rw-r--r-- | crypto/engine/README.md | 27 | ||||
| -rw-r--r-- | crypto/err/README.md | 24 | ||||
| -rw-r--r-- | crypto/objects/README.md | 51 | ||||
| -rw-r--r-- | crypto/perlasm/README.md | 170 | ||||
| -rw-r--r-- | crypto/property/README.md | 23 | ||||
| -rw-r--r-- | demos/README.txt | 2 | ||||
| -rw-r--r-- | doc/README.md | 19 | ||||
| -rw-r--r-- | ssl/record/README.md | 61 | ||||
| -rw-r--r-- | ssl/statem/README.md | 96 | ||||
| -rw-r--r-- | test/README-external.md | 85 |
28 files changed, 881 insertions, 855 deletions
diff --git a/CHANGES.md b/CHANGES.md index c0140a35bb..2cb73985a3 100644 --- a/CHANGES.md +++ b/CHANGES.md @@ -174,12 +174,12 @@ OpenSSL 3.0 *Richard Levitte* * Project text documents not yet having a proper file name extension - (HACKING, LICENSE, NOTES*, README*, VERSION) have been renamed to *.md - as far as reasonable, else to *.txt, for better use with file managers. + (`HACKING`, `LICENSE`, `NOTES*`, `README*`, `VERSION`) have been renamed to + `*.md` as far as reasonable, else `*.txt`, for better use with file managers. *David von Oheimb* -* The main project documents (README, NEWS, CHANGES, INSTALL, SUPPORT) + * The main project documents (README, NEWS, CHANGES, INSTALL, SUPPORT) have been converted to Markdown with the goal to produce documents which not only look pretty when viewed online in the browser, but remain well readable inside a plain text editor. @@ -1060,7 +1060,7 @@ OpenSSL 3.0 * Added EVP_MAC, an EVP layer MAC API, to simplify adding MAC implementations. This includes a generic EVP_PKEY to EVP_MAC bridge, to facilitate the continued use of MACs through raw private keys in - functionality such as EVP_DigestSign* and EVP_DigestVerify*. + functionality such as `EVP_DigestSign*` and `EVP_DigestVerify*`. *Richard Levitte* @@ -1732,9 +1732,9 @@ OpenSSL 1.1.1 *Paul Yang* * Add SM3 implemented according to GB/T 32905-2016 - * Jack Lloyd <jack.lloyd@ribose.com>, - Ronald Tse <ronald.tse@ribose.com>, - Erick Borsboom <erick.borsboom@ribose.com> * + *Jack Lloyd <jack.lloyd@ribose.com>,* + *Ronald Tse <ronald.tse@ribose.com>,* + *Erick Borsboom <erick.borsboom@ribose.com>* * Add 'Maximum Fragment Length' TLS extension negotiation and support as documented in RFC6066. @@ -1743,9 +1743,9 @@ OpenSSL 1.1.1 *Filipe Raimundo da Silva* * Add SM4 implemented according to GB/T 32907-2016. - * Jack Lloyd <jack.lloyd@ribose.com>, - Ronald Tse <ronald.tse@ribose.com>, - Erick Borsboom <erick.borsboom@ribose.com> * + *Jack Lloyd <jack.lloyd@ribose.com>,* + *Ronald Tse <ronald.tse@ribose.com>,* + *Erick Borsboom <erick.borsboom@ribose.com>* * Reimplement -newreq-nodes and ERR_error_string_n; the original author does not agree with the license change. @@ -2931,7 +2931,7 @@ OpenSSL 1.1.0 Makefile. Instead, Configure produces a perl module in configdata.pm which holds most of the config data (in the hash table %config), the target data that comes from the target - configuration in one of the `Configurations/*.conf~ files (in + configuration in one of the `Configurations/*.conf` files (in %target). *Richard Levitte* @@ -3062,21 +3062,21 @@ OpenSSL 1.1.0 opaque. For HMAC_CTX, the following constructors and destructors were added: - HMAC_CTX *HMAC_CTX_new(void); - void HMAC_CTX_free(HMAC_CTX *ctx); + HMAC_CTX *HMAC_CTX_new(void); + void HMAC_CTX_free(HMAC_CTX *ctx); For EVP_MD and EVP_CIPHER, complete APIs to create, fill and destroy such methods has been added. See EVP_MD_meth_new(3) and EVP_CIPHER_meth_new(3) for documentation. Additional changes: - 1) EVP_MD_CTX_cleanup(), EVP_CIPHER_CTX_cleanup() and - HMAC_CTX_cleanup() were removed. HMAC_CTX_reset() and - EVP_MD_CTX_reset() should be called instead to reinitialise + 1) `EVP_MD_CTX_cleanup()`, `EVP_CIPHER_CTX_cleanup()` and + `HMAC_CTX_cleanup()` were removed. `HMAC_CTX_reset()` and + `EVP_MD_CTX_reset()` should be called instead to reinitialise an already created structure. 2) For consistency with the majority of our object creators and - destructors, EVP_MD_CTX_(create|destroy) were renamed to - EVP_MD_CTX_(new|free). The old names are retained as macros + destructors, `EVP_MD_CTX_(create|destroy)` were renamed to + `EVP_MD_CTX_(new|free)`. The old names are retained as macros for deprecated builds. *Richard Levitte* @@ -3174,8 +3174,8 @@ OpenSSL 1.1.0 *Emilia Käsper* * Fix no-stdio build. - * David Woodhouse <David.Woodhouse@intel.com> and also - Ivan Nestlerode <ivan.nestlerode@sonos.com> * + *David Woodhouse <David.Woodhouse@intel.com> and also* + *Ivan Nestlerode <ivan.nestlerode@sonos.com>* * New testing framework The testing framework has been largely rewritten and is now using @@ -3579,7 +3579,7 @@ OpenSSL 1.1.0 *Steve Henson* - * Rename old X9.31 PRNG functions of the form FIPS_rand* to FIPS_x931*. + * Rename old X9.31 PRNG functions of the form `FIPS_rand*` to `FIPS_x931*`. This shouldn't present any incompatibility problems because applications shouldn't be using these directly and any that are will need to rethink anyway as the X9.31 PRNG is now deprecated by FIPS 140-2 @@ -4458,11 +4458,11 @@ OpenSSL 1.0.2 * Fix BN_hex2bn/BN_dec2bn NULL pointer deref/heap corruption In the BN_hex2bn function the number of hex digits is calculated using an - int value |i|. Later |bn_expand| is called with a value of |i * 4|. For - large values of |i| this can result in |bn_expand| not allocating any - memory because |i * 4| is negative. This can leave the internal BIGNUM data + int value `i`. Later `bn_expand` is called with a value of `i * 4`. For + large values of `i` this can result in `bn_expand` not allocating any + memory because `i * 4` is negative. This can leave the internal BIGNUM data field as NULL leading to a subsequent NULL ptr deref. For very large values - of |i|, the calculation |i * 4| could be a positive value smaller than |i|. + of `i`, the calculation `i * 4` could be a positive value smaller than `i`. In this case memory is allocated to the internal BIGNUM data field, but it is insufficiently sized leading to heap corruption. A similar issue exists in BN_dec2bn. This could have security consequences if BN_hex2bn/BN_dec2bn @@ -4482,11 +4482,11 @@ OpenSSL 1.0.2 * Fix memory issues in `BIO_*printf` functions - The internal |fmtstr| function used in processing a "%s" format string in + The internal `fmtstr` function used in processing a "%s" format string in the `BIO_*printf` functions could overflow while calculating the length of a string and cause an OOB read when printing very long strings. - Additionally the internal |doapr_outch| function can attempt to write to an + Additionally the internal `doapr_outch` function can attempt to write to an OOB memory location (at an offset from the NULL pointer) in the event of a memory allocation failure. In 1.0.2 and below this could be caused where the size of a buffer to be allocated is greater than INT_MAX. E.g. this @@ -5660,11 +5660,11 @@ OpenSSL 1.0.1 * Fix BN_hex2bn/BN_dec2bn NULL pointer deref/heap corruption In the BN_hex2bn function the number of hex digits is calculated using an - int value |i|. Later |bn_expand| is called with a value of |i * 4|. For - large values of |i| this can result in |bn_expand| not allocating any - memory because |i * 4| is negative. This can leave the internal BIGNUM data + int value `i`. Later `bn_expand` is called with a value of `i * 4`. For + large values of `i` this can result in `bn_expand` not allocating any + memory because `i * 4` is negative. This can leave the internal BIGNUM data field as NULL leading to a subsequent NULL ptr deref. For very large values - of |i|, the calculation |i * 4| could be a positive value smaller than |i|. + of `i`, the calculation `i * 4` could be a positive value smaller than `i`. In this case memory is allocated to the internal BIGNUM data field, but it is insufficiently sized leading to heap corruption. A similar issue exists in BN_dec2bn. This could have security consequences if BN_hex2bn/BN_dec2bn @@ -5684,11 +5684,11 @@ OpenSSL 1.0.1 * Fix memory issues in `BIO_*printf` functions - The internal |fmtstr| function used in processing a "%s" format string in + The internal `fmtstr` function used in processing a "%s" format string in the `BIO_*printf` functions could overflow while calculating the length of a string and cause an OOB read when printing very long strings. - Additionally the internal |doapr_outch| function can attempt to write to an + Additionally the internal `doapr_outch` function can attempt to write to an OOB memory location (at an offset from the NULL pointer) in the event of a memory allocation failure. In 1.0.2 and below this could be caused where the size of a buffer to be allocated is greater than INT_MAX. E.g. this @@ -6505,8 +6505,8 @@ OpenSSL 1.0.1 disable just protocol X, but all protocols above X *if* there are protocols *below* X still enabled. In more practical terms it means that if application wants to disable TLS1.0 in favor of TLS1.1 and - above, it's not sufficient to pass SSL_OP_NO_TLSv1, one has to pass - SSL_OP_NO_TLSv1|SSL_OP_NO_SSLv3|SSL_OP_NO_SSLv2. This applies to + above, it's not sufficient to pass `SSL_OP_NO_TLSv1`, one has to pass + `SSL_OP_NO_TLSv1|SSL_OP_NO_SSLv3|SSL_OP_NO_SSLv2`. This applies to client side. *Andy Polyakov* @@ -12328,8 +12328,8 @@ s-cbc 3624.96k 5258.21k 5530.91k 5624.30k 5628.26k *Geoff Thorpe, Lutz Jaenicke* * Modify mkdef.pl to recognise and parse preprocessor conditionals - of the form '#if defined(...) || defined(...) || ...' and - '#if !defined(...) && !defined(...) && ...'. This also avoids + of the form `#if defined(...) || defined(...) || ...` and + `#if !defined(...) && !defined(...) && ...`. This also avoids the growing number of special cases it was previously handling. *Richard Levitte* @@ -12902,9 +12902,9 @@ s-cbc 3624.96k 5258.21k 5530.91k 5624.30k 5628.26k *Bodo Moeller* - * Move `BN_mod_...` functions into new file crypto/bn/bn_mod.c - (except for exponentiation, which stays in crypto/bn/bn_exp.c, - and BN_mod_mul_reciprocal, which stays in crypto/bn/bn_recp.c) + * Move `BN_mod_...` functions into new file `crypto/bn/bn_mod.c` + (except for exponentiation, which stays in `crypto/bn/bn_exp.c`, + and `BN_mod_mul_reciprocal`, which stays in `crypto/bn/bn_recp.c`) and add new functions: BN_nnmod @@ -12920,16 +12920,16 @@ s-cbc 3624.96k 5258.21k 5530.91k 5624.30k 5628.26k These functions always generate non-negative results. - BN_nnmod otherwise is like BN_mod (if BN_mod computes a remainder r - such that |m| < r < 0, BN_nnmod will output rem + |m| instead). + `BN_nnmod` otherwise is `like BN_mod` (if `BN_mod` computes a remainder `r` + such that `|m| < r < 0`, `BN_nnmod` will output `rem + |m|` instead). - BN_mod_XXX_quick(r, a, [b,] m) generates the same result as - BN_mod_XXX(r, a, [b,] m, ctx), but requires that a [and b] - be reduced modulo m. + `BN_mod_XXX_quick(r, a, [b,] m)` generates the same result as + `BN_mod_XXX(r, a, [b,] m, ctx)`, but requires that `a` [and `b`] + be reduced modulo `m`. *Lenka Fibikova <fibikova@exp-math.uni-essen.de>, Bodo Moeller* -f 0 +<!-- The following entry accidentally appeared in the CHANGES file distributed with OpenSSL 0.9.7. The modifications described in it do *not* apply to OpenSSL 0.9.7. @@ -12943,7 +12943,7 @@ f 0 differing sizes. *Richard Levitte* -ndif +--> * In 'openssl passwd', verify passwords read from the terminal unless the '-salt' option is used (which usually means that @@ -14683,7 +14683,7 @@ ndif * Change the handling of OID objects as follows: - New object identifiers are inserted in objects.txt, following - the syntax given in objects.README. + the syntax given in [crypto/objects/README.md](crypto/objects/README.md). - objects.pl is used to process obj_mac.num and create a new obj_mac.h. - obj_dat.pl is used to create a new obj_dat.h, using the data in @@ -17399,10 +17399,10 @@ ndif *Steve Henson* * Be less restrictive and allow also `perl util/perlpath.pl - /path/to/bin/perl' in addition to `perl util/perlpath.pl /path/to/bin', - because this way one can also use an interpreter named `perl5' (which is + /path/to/bin/perl` in addition to `perl util/perlpath.pl /path/to/bin`, + because this way one can also use an interpreter named `perl5` (which is usually the name of Perl 5.xxx on platforms where an Perl 4.x is still - installed as `perl'). + installed as `perl`). *Matthias Loepfe <Matthias.Loepfe@adnovum.ch>* @@ -17435,7 +17435,7 @@ ndif *Steve Henson* - * Make `openssl version' output lines consistent. + * Make `openssl version` output lines consistent. *Ralf S. Engelschall* @@ -17492,7 +17492,7 @@ ndif *Ben Laurie* * Allow DSO flags like -fpic, -fPIC, -KPIC etc. to be specified - on the `perl Configure ...' command line. This way one can compile + on the `perl Configure ...` command line. This way one can compile OpenSSL libraries with Position Independent Code (PIC) which is needed for linking it into DSOs. @@ -17511,9 +17511,9 @@ ndif *Ralf S. Engelschall* - * General source tree makefile cleanups: Made `making xxx in yyy...' - display consistent in the source tree and replaced `/bin/rm' by `rm'. - Additionally cleaned up the `make links' target: Remove unnecessary + * General source tree makefile cleanups: Made `making xxx in yyy...` + display consistent in the source tree and replaced `/bin/rm` by `rm`. + Additionally cleaned up the `make links` target: Remove unnecessary semicolons, subsequent redundant removes, inline point.sh into mklink.sh to speed processing and no longer clutter the display with confusing stuff. Instead only the actually done links are displayed. @@ -17640,12 +17640,12 @@ ndif *Ralf S. Engelschall* - * Make `openssl x509 -noout -modulus' functional also for DSA certificates + * Make `openssl x509 -noout -modulus`' functional also for DSA certificates (in addition to RSA certificates) to match the behaviour of `openssl dsa - -noout -modulus' as it's already the case for `openssl rsa -noout - -modulus'. For RSA the -modulus is the real "modulus" while for DSA + -noout -modulus` as it's already the case for `openssl rsa -noout + -modulus`. For RSA the -modulus is the real "modulus" while for DSA currently the public key is printed (a decision which was already done by - `openssl dsa -modulus' in the past) which serves a similar purpose. + `openssl dsa -modulus` in the past) which serves a similar purpose. Additionally the NO_RSA no longer completely removes the whole -modulus option; it now only avoids using the RSA stuff. Same applies to NO_DSA now, too. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 96290fffca..3e11b0b89f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -54,8 +54,8 @@ guidelines: (usually by rebasing) before it will be acceptable. 4. Patches should follow our [coding style][] and compile without warnings. - Where gcc or clang is available you should use the - --strict-warnings Configure option. OpenSSL compiles on many varied + Where `gcc` or `clang` is available you should use the + `--strict-warnings` `Configure` option. OpenSSL compiles on many varied platforms: try to ensure you only use portable features. Clean builds via Travis and AppVeyor are required, and they are started automatically whenever a PR is created or updated. @@ -64,7 +64,7 @@ guidelines: 5. When at all possible, patches should include tests. These can either be added to an existing test, or completely new. Please see - test/README.md for information on the test framework. + [test/README.md](test/README.md) for information on the test framework. 6. New features or changed functionality must include documentation. Please look at the "pod" files in doc/man[1357] for @@ -77,7 +77,7 @@ guidelines: explain the grander details. Have a look through existing entries for inspiration. Please note that this is NOT simply a copy of git-log one-liners. - Also note that security fixes get an entry in CHANGES.md. + Also note that security fixes get an entry in [CHANGES.md](CHANGES.md). This file helps users get more in depth information of what comes with a specific release without having to sift through the higher noise ratio in git-log. @@ -89,3 +89,6 @@ guidelines: OpenSSL 1.1.0). This file helps users get a very quick summary of what comes with a specific release, to see if an upgrade is worth the effort. + + 9. Guidelines how to integrate error output of new crypto library modules + can be found in [crypto/err/README.md](crypto/err/README.md).
\ No newline at end of file diff --git a/Configurations/README-design.md b/Configurations/README-design.md index b79d0b2e49..ef21a3ae28 100644 --- a/Configurations/README-design.md +++ b/Configurations/README-design.md @@ -4,17 +4,17 @@ Design document for the unified scheme data How are things connected? ------------------------- -The unified scheme takes all its data from the build.info files seen +The unified scheme takes all its data from the `build.info` files seen throughout the source tree. These files hold the minimum information needed to build end product files from diverse sources. See the -section on build.info files below. +section on `build.info` files below. -From the information in build.info files, Configure builds up an -information database as a hash table called %unified_info, which is +From the information in `build.info` files, `Configure` builds up an +information database as a hash table called `%unified_info`, which is stored in configdata.pm, found at the top of the build tree (which may or may not be the same as the source tree). -Configurations/common.tmpl uses the data from %unified_info to +[`Configurations/common.tmpl`](common.tmpl) uses the data from `%unified_info` to generate the rules for building end product files as well as intermediary files with the help of a few functions found in the build-file templates. See the section on build-file templates further @@ -23,36 +23,35 @@ down for more information. build.info files ---------------- -As mentioned earlier, build.info files are meant to hold the minimum +As mentioned earlier, `build.info` files are meant to hold the minimum information needed to build output files, and therefore only (with a few possible exceptions [1]) have information about end products (such as scripts, library files and programs) and source files (such as C files, C header files, assembler files, etc). Intermediate files such -as object files are rarely directly referred to in build.info files (and -when they are, it's always with the file name extension .o), they are -inferred by Configure. By the same rule of minimalism, end product -file name extensions (such as .so, .a, .exe, etc) are never mentioned -in build.info. Their file name extensions will be inferred by the +as object files are rarely directly referred to in `build.info` files (and +when they are, it's always with the file name extension `.o`), they are +inferred by `Configure`. By the same rule of minimalism, end product +file name extensions (such as `.so`, `.a`, `.exe`, etc) are never mentioned +in `build.info`. Their file name extensions will be inferred by the build-file templates, adapted for the platform they are meant for (see -sections on %unified_info and build-file templates further down). +sections on `%unified_info` and build-file templates further down). -The variables PROGRAMS, LIBS, MODULES and SCRIPTS are used to declare -end products. There are variants for them with '_NO_INST' as suffix -(PROGRAM_NO_INST etc) to specify end products that shouldn't get -installed. +The variables `PROGRAMS`, `LIBS`, `MODULES` and `SCRIPTS` are used to declare +end products. There are variants for them with `_NO_INST` as suffix +(`PROGRAM_NO_INST` etc) to specify end products that shouldn't get installed. -The variables SOURCE, DEPEND, INCLUDE and DEFINE are indexed by a +The variables `SOURCE`, `DEPEND`, `INCLUDE` and `DEFINE` are indexed by a produced file, and their values are the source used to produce that particular produced file, extra dependencies, include directories needed, or C macros to be defined. -All their values in all the build.info throughout the source tree are +All their values in all the `build.info` throughout the source tree are collected together and form a set of programs, libraries, modules and scripts to be produced, source files, dependencies, etc etc etc. Let's have a pretend example, a very limited contraption of OpenSSL, -composed of the program 'apps/openssl', the libraries 'libssl' and -'libcrypto', an module 'engines/ossltest' and their sources and +composed of the program `apps/openssl`, the libraries `libssl` and +`libcrypto`, an module `engines/ossltest` and their sources and dependencies. # build.info @@ -61,11 +60,11 @@ dependencies. INCLUDE[libssl]=include DEPEND[libssl]=libcrypto -This is the top directory build.info file, and it tells us that two -libraries are to be built, the include directory 'include/' shall be +This is the top directory `build.info` file, and it tells us that two +libraries are to be built, the include directory `include/` shall be used throughout when building anything that will end up in each -library, and that the library 'libssl' depend on the library -'libcrypto' to function properly. +library, and that the library `libssl` depend on the library +`libcrypto` to function properly. # apps/build.info PROGRAMS=openssl @@ -73,15 +72,15 @@ library, and that the library 'libssl' depend on the library INCLUDE[openssl]=.. ../include DEPEND[openssl]=../libssl -This is the build.info file in 'apps/', one may notice that all file -paths mentioned are relative to the directory the build.info file is +This is the `build.info` file in `apps/`, one may notice that all file +paths mentioned are relative to the directory the `build.info` file is located in. This one tells us that there's a program to be built -called 'apps/openssl' (the file name extension will depend on the -platform and is therefore not mentioned in the build.info file). It's -built from one source file, 'apps/openssl.c', and building it requires -the use of '.' and 'include' include directories (both are declared -from the point of view of the 'apps/' directory), and that the program -depends on the library 'libssl' to function properly. +called `apps/openss` (the file name extension will depend on the +platform and is therefore not mentioned in the `build.info` file). It's +built from one source file, `apps/openssl.c`, and building it requires +the use of `.` and `include/` include directories (both are declared +from the point of view of the `apps/` directory), and that the program +depends on the library `libssl` to function properly. # crypto/build.info LIBS=../libcrypto @@ -92,32 +91,32 @@ depends on the library 'libssl' to function properly. DEPEND[buildinf.h]=../Makefile DEPEND[../util/mkbuildinf.pl]=../util/Foo.pm -This is the build.info file in 'crypto', and it tells us a little more -about what's needed to produce 'libcrypto'. LIBS is used again to -declare that 'libcrypto' is to be produced. This declaration is -really unnecessary as it's already mentioned in the top build.info +This is the `build.info` file in `crypto/`, and it tells us a little more +about what's needed to produce `libcrypto`. LIBS is used again to +declare that `libcrypto` is to be produced. This declaration is +really unnecessary as it's already mentioned in the top `build.info` file, but can make the info file easier to understand. This is to show that duplicate information isn't an issue. -This build.info file informs us that 'libcrypto' is built from a few -source files, 'crypto/aes.c', 'crypto/evp.c' and 'crypto/cversion.c'. +This `build.info` file informs us that `libcrypto` is built from a few +source files, `crypto/aes.c`, `crypto/evp.c` and `crypto/cversion.c`. It also shows us that building the object file inferred from -'crypto/cversion.c' depends on 'crypto/buildinf.h'. Finally, it +`crypto/cversion.c` depends on `crypto/buildinf.h`. Finally, it also shows the possibility to declare how some files are generated using some script, in this case a perl script, and how such scripts can be declared to depend on other files, in this case a perl module. Two things are worth an extra note: -'DEPEND[cversion.o]' mentions an object file. DEPEND indexes is the +`DEPEND[cversion.o]` mentions an object file. DEPEND indexes is the only location where it's valid to mention them # ssl/build.info LIBS=../libssl SOURCE[../libssl]=tls.c -This is the build.info file in 'ssl/', and it tells us that the -library 'libssl' is built from the source file 'ssl/tls.c'. +This is the build.info file in `ssl/`, and it tells us that the +library `libssl` is built from the source file `ssl/tls.c`. # engines/build.info MODULES=dasync @@ -130,17 +129,17 @@ library 'libssl' is built from the source file 'ssl/tls.c'. DEPEND[ossltest]=../libcrypto.a INCLUDE[ossltest]=../include -This is the build.info file in 'engines/', telling us that two modules -called 'engines/dasync' and 'engines/ossltest' shall be built, that -dasync's source is 'engines/e_dasync.c' and ossltest's source is -'engines/e_ossltest.c' and that the include directory 'include/' may +This is the `build.info` file in `engines/`, telling us that two modules +called `engines/dasync` and `engines/ossltest` shall be built, that +`dasync`'s source is `engines/e_dasync.c` and `ossltest`'s source is +`engines/e_ossltest.c` and that the include directory `include/` may be used when building anything that will be part of these modules. -Also, both modules depend on the library 'libcrypto' to function -properly. ossltest is explicitly linked with the static variant of -the library 'libcrypto'. Finally, only dasync is being installed, as -ossltest is only for internal testing. +Also, both modules depend on the library `libcrypto` to function +properly. `ossltest` is explicitly linked with the static variant of +the library `libcrypto`. Finally, only `dasync` is being installed, as +`ossltest` is only for internal testing. -When Configure digests these build.info files, the accumulated +When `Configure` digests these `build.info` files, the accumulated information comes down to this: LIBS=libcrypto libssl @@ -170,83 +169,81 @@ information comes down to this: DEPEND[crypto/buildinf.h]=Makefile DEPEND[util/mkbuildinf.pl]=util/Foo.pm - A few notes worth mentioning: -LIBS may be used to declare routine libraries only. +`LIBS` may be used to declare routine libraries only. -PROGRAMS may be used to declare programs only. +`PROGRAMS` may be used to declare programs only. -MODULES may be used to declare modules only. +`MODULES` may be used to declare modules only. -The indexes for SOURCE must only be end product files, such as -libraries, programs or modules. The values of SOURCE variables must +The indexes for `SOURCE` must only be end product files, such as +libraries, programs or modules. The values of `SOURCE` variables must only be source files (possibly generated). -INCLUDE and DEPEND shows a relationship between different files +`INCLUDE` and `DEPEND` shows a relationship between different files (usually produced files) or between files and directories, such as a program depending on a library, or between an object file and some extra source file. -When Configure processes the build.info files, it will take it as +When `Configure` processes the `build.info` files, it will take it as truth without question, and will therefore perform very few checks. If the build tree is separate from the source tree, it will assume that all built files and up in the build directory and that all source files are to be found in the source tree, if they can be found there. -Configure will assume that source files that can't be found in the -source tree (such as 'crypto/bildinf.h' in the example above) are +`Configure` will assume that source files that can't be found in the +source tree (such as `crypto/bildinf.h` in the example above) are generated and will be found in the build tree. +The `%unified_info` database +---------------------------- -The %unified_info database --------------------------- - -The information in all the build.info get digested by Configure and -collected into the %unified_info database, divided into the following +The information in all the `build.info` get digested by `Configure` and +collected into the `%unified_info` database, divided into the following indexes: - depends => a hash table containing 'file' => [ 'dependency' ... ] - pairs. These are directly inferred from the DEPEND - variables in build.info files. + depends => a hash table containing 'file' => [ 'dependency' ... ] + pairs. These are directly inferred from the DEPEND + variables in build.info files. - modules => a list of modules. These are directly inferred from - the MODULES variable in build.info files. + modules => a list of modules. These are directly inferred from + the MODULES variable in build.info files. - generate => a hash table containing 'file' => [ 'generator' ... ] - pairs. These are directly inferred from the GENERATE - variables in build.info files. + generate => a hash table containing 'file' => [ 'generator' ... ] + pairs. These are directly inferred from the GENERATE + variables in build.info files. - includes => a hash table containing 'file' => [ 'include' ... ] - pairs. These are directly inferred from the INCLUDE - variables in build.info files. + includes => a hash table containing 'file' => [ 'include' ... ] + pairs. These are directly inferred from the INCLUDE + variables in build.info files. - install => a hash table containing 'type' => [ 'file' ... ] pairs. - The types are 'programs', 'libraries', 'modules' and - 'scripts', and the array of files list the files of - that type that should be installed. + install => a hash table containing 'type' => [ 'file' ... ] pairs. + The types are 'programs', 'libraries', 'modules' and + 'scripts', and the array of files list the files of + that type that should be installed. - libraries => a list of libraries. These are directly inferred from - the LIBS variable in build.info files. + libraries => a list of libraries. These are directly inferred from + the LIBS variable in build.info files. - programs => a list of programs. These are directly inferred from - the PROGRAMS variable in build.info files. + programs => a list of programs. These are directly inferred from + the PROGRAMS variable in build.info files. - scripts => a list of scripts. There are directly inferred from - the SCRIPTS variable in build.info files. + scripts => a list of scripts. There are directly inferred from + the SCRIPTS variable in build.info files. - sources => a hash table containing 'file' => [ 'sourcefile' ... ] - pairs. These are indirectly inferred from the SOURCE - variables in build.info files. Object files are - mentioned in this hash table, with source files from - SOURCE variables, and AS source files for programs and - libraries. + sources => a hash table containing 'file' => [ 'sourcefile' ... ] + pairs. These are indirectly inferred from the SOURCE + variables in build.info files. Object files are + mentioned in this hash table, with source files from + SOURCE variables, and AS source files for programs and + libraries. - shared_sources => - a hash table just like 'sources', but only as source - files (object files) for building shared libraries. + shared_sources => + a hash table just like 'sources', but only as source + files (object files) for building shared libraries. -As an example, here is how the build.info files example from the -section above would be digested into a %unified_info table: +As an example, here is how the `build.info` files example from the +section above would be digested into a `%unified_info` table: our %unified_info = ( "depends" => @@ -399,20 +396,19 @@ section a |