X-Git-Url: https://git.openssl.org/gitweb/?p=openssl.git;a=blobdiff_plain;f=Configurations%2FREADME;h=a03d445aea9ca0766a9b5774c54091e4fc333ea0;hp=e1327e57f9d6607238625afde2f6450e31b58e7c;hb=46d085096c6ead624c61e4b8b301421301511e64;hpb=9e0724a1805fba20a897f6c7f95336f0da017ccf diff --git a/Configurations/README b/Configurations/README index e1327e57f9..a03d445aea 100644 --- a/Configurations/README +++ b/Configurations/README @@ -1,10 +1,31 @@ +Intro +===== + +This directory contains a few sets of files that are used for +configuration in diverse ways: + + *.conf Target platform configurations, please read + 'Configurations of OpenSSL target platforms' for more + information. + *.tmpl Build file templates, please read 'Build-file + programming with the "unified" build system' as well + as 'Build info files' for more information. + *.pm Helper scripts / modules for the main `Configure` + script. See 'Configure helper scripts for more + information. + + Configurations of OpenSSL target platforms ------------------------------------------- +========================================== -Target configurations are a collection of facts that we know about +Configuration targets are a collection of facts that we know about different platforms and their capabilities. We organise them in a hash table, where each entry represent a specific target. +Note that configuration target names must be unique across all config +files. The Configure script does check that a config file doesn't +have config targets that shadow config targets from other files. + In each table entry, the following keys are significant: inherit_from => Other targets to inherit values from. @@ -17,54 +38,78 @@ In each table entry, the following keys are significant: sys_id => System identity for systems where that is difficult to determine automatically. - cc => The compiler command, usually one of "cc", + enable => Enable specific configuration features. + This MUST be an array of words. + disable => Disable specific configuration features. + This MUST be an array of words. + Note: if the same feature is both enabled + and disabled, disable wins. + + as => The assembler command. This is not always + used (for example on Unix, where the C + compiler is used instead). + asflags => Default assembler command flags [4]. + cpp => The C preprocessor command, normally not + given, as the build file defaults are + usually good enough. + cppflags => Default C preprocessor flags [4]. + defines => As an alternative, macro definitions may be + given here instead of in `cppflags' [4]. + If given here, they MUST be as an array of + the string such as "MACRO=value", or just + "MACRO" for definitions without value. + includes => As an alternative, inclusion directories + may be given here instead of in `cppflags' + [4]. If given here, the MUST be an array + of strings, one directory specification + each. + cc => The C compiler command, usually one of "cc", "gcc" or "clang". This command is normally also used to link object files and libraries into the final program. - cflags => Flags that are used at all times when - compiling. - debug_cflags => Extra compilation flags used when making a - debug build (when Configure receives the - --debug option). Typically something like - "-g -O0". - release_cflags => Extra compilation flags used when making a - release build (when Configure receives the - --release option, or doesn't receive the - --debug option). Typically something like - "-O" or "-O3". - thread_cflags => Extra compilation flags used when - compiling with threading enabled. - Explained further below. [2] - shared_cflag => Extra compilation flags used when - compiling for shared libraries, typically - something like "-fPIC". - - ld => the linker command, usually not defined + cxx => The C++ compiler command, usually one of + "c++", "g++" or "clang++". This command is + also used when linking a program where at + least one of the object file is made from + C++ source. + cflags => Defaults C compiler flags [4]. + cxxflags => Default C++ compiler flags [4]. If unset, + it gets the same value as cflags. + + (linking is a complex thing, see [3] below) + ld => Linker command, usually not defined (meaning the compiler command is used instead). (NOTE: this is here for future use, it's not implemented yet) - lflags => the flags that are used at all times when - linking. These can have a % sign in them - showing where the OpenSSL libraries should - appear, otherwise these flags will come - last. So in a typical links situation, - this is a quick table of results: + lflags => Default flags used when linking apps, + shared libraries or DSOs [4]. + ex_libs => Extra libraries that are needed when + linking shared libraries, DSOs or programs. + The value is also assigned to Libs.private + in $(libdir)/pkgconfig/libcrypto.pc. - "-foo%-bar" > -foo -lssl -lcrypto -bar - "-foo%" > -foo -lssl -lcrypto - "-foo" > -lssl -lcrypto -foo - - debug_lflags => Like debug_cflags, but used when linking. - release_lflags => Like release_cflags, but used when linking. - shared_lflags => Like shared_cflags, but used when linking. + shared_cppflags => Extra C preprocessor flags used when + processing C files for shared libraries. + shared_cflag => Extra C compiler flags used when compiling + for shared libraries, typically something + like "-fPIC". + shared_ldflag => Extra linking flags used when linking + shared libraries. + module_cppflags + module_cflags + module_ldflags => Has the same function as the corresponding + `shared_' attributes, but for building DSOs. + When unset, they get the same values as the + corresponding `shared_' attributes. ar => The library archive command, the default is "ar". (NOTE: this is here for future use, it's not implemented yet) arflags => Flags to be used with the library archive - command. + command. On Unix, this includes the + command letter, 'r' by default. ranlib => The library archive indexing command, the default is 'ranlib' it it exists. @@ -82,7 +127,36 @@ In each table entry, the following keys are significant: files. On unix, this defaults to "" (NOTE: this is here for future use, it's not implemented yet) + shlib_variant => A "variant" identifier inserted between the base + shared library name and the extension. On "unixy" + platforms (BSD, Linux, Solaris, MacOS/X, ...) this + supports installation of custom OpenSSL libraries + that don't conflict with other builds of OpenSSL + installed on the system. The variant identifier + becomes part of the SONAME of the library and also + any symbol versions (symbol versions are not used or + needed with MacOS/X). For example, on a system + where a default build would normally create the SSL + shared library as 'libssl.so -> libssl.so.1.1' with + the value of the symlink as the SONAME, a target + definition that sets 'shlib_variant => "-abc"' will + create 'libssl.so -> libssl-abc.so.1.1', again with + an SONAME equal to the value of the symlink. The + symbol versions associated with the variant library + would then be 'OPENSSL_ABC_' rather than + the default 'OPENSSL_'. The string inserted + into symbol versions is obtained by mapping all + letters in the "variant" identifier to upper case + and all non-alphanumeric characters to '_'. + thread_scheme => The type of threads is used on the + configured platform. Currently known + values are "(unknown)", "pthreads", + "uithreads" (a.k.a solaris threads) and + "winthreads". Except for "(unknown)", the + actual value is currently ignored but may + be used in the future. See further notes + below [2]. dso_scheme => The type of dynamic shared objects to build for. This mostly comes into play with engines, but can be used for other purposes @@ -91,14 +165,24 @@ In each table entry, the following keys are significant: that use dlopen() et al but do not have fcntl.h), "DL" (shl_load() et al), "WIN32" and "VMS". - perlasm_scheme => The perlasm method used to created the + perlasm_scheme => The perlasm method used to create the assembler files used when compiling with assembler implementations. shared_target => The shared library building method used. This is a target found in Makefile.shared. build_scheme => The scheme used to build up a Makefile. - (NOTE: this is here for future use, it's - not implemented yet) + In its simplest form, the value is a string + with the name of the build scheme. + The value may also take the form of a list + of strings, if the build_scheme is to have + some options. In this case, the first + string in the list is the name of the build + scheme. + Currently recognised build scheme is "unified". + For the "unified" build scheme, this item + *must* be an array with the first being the + word "unified" and the second being a word + to identify the platform family. multilib => On systems that support having multiple implementations of a library (typically a @@ -106,118 +190,92 @@ In each table entry, the following keys are significant: to have the different variants in different directories. - bn_ops => Building options (was just bignum options - in the earlier history of this option, - hence the name). This a string of words - that describe properties on the designated - target platform, such as the type of - integers used to build up the bitnum, - different ways to implement certain ciphers - and so on. To fully comprehend the + bn_ops => Building options (was just bignum options in + the earlier history of this option, hence the + name). This is a string of words that describe + algorithms' implementation parameters that + are optimal for the designated target platform, + such as the type of integers used to build up + the bignum, different ways to implement certain + ciphers and so on. To fully comprehend the meaning, the best is to read the affected source. The valid words are: - DES_PTR use a pointer to DES_SPtrans - rather that DES_SPtrans - directly in D_ENCRYPT. - DES_RISC1 Alternate implementations of - DES_RISC2 D_ENCRYPT for certain RISC - processors. - DES_UNROLL do not loop around calls to - D_ENCRYPT. - DES_INT have unsigned int as the - integer type for DES rather - than unsigned long. - BN_LLONG use 'unsigned long long' in - some bignum calculations. - This has no value when - SIXTY_FOUR_BIT or - SIXTY_FOUR_BIT_LONG is given. - RC4_CHAR makes the basic RC4 unif of - calculation an unsigned char. - RC4_LONG makes the basic RC4 unif of - calculation an unsigned long. - RC4_INDEX go through input and output - data by indexing into them - rather than incrementing the - pointer. - RC4_CHUNK sets the chunk type to - unsigned long. - RC4_CHUNK_LL sets the chunk type to - unsigned long long. - both these chunk sizes are for - handling data in chunks on - processors that do not have - byte load/store instructions. - MD2_CHAR makes the basic MD2 unit of - calculation an unsigned char. - MD2_LONG makes the basic MD2 unit of - calculation an unsigned long. - IDEA_SHORT makes the basic IDEA unit of - calculation an unsigned short. - IDEA_LONG makes the basic IDEA unit of - calculation an unsigned long. - RC2_SHORT makes the basic RC2 unit of - calculation an unsigned short. - RC2_LONG makes the basic RC2 unit of - calculation an unsigned long. - BF_PTR use different pointer based - BF_PTR2 versions of BF_ENC. - SIXTY_FOUR_BIT processor registers - are 64 bits, long is - 32 bits, long long is - 64 bits. - SIXTY_FOUR_BIT_LONG processor registers - are 64 bits, long is - 64 bits. - THIRTY_TWO_BIT processor registers - are 32 bits. + THIRTY_TWO_BIT bignum limbs are 32 bits, + this is default if no + option is specified, it + works on any supported + system [unless "wider" + limb size is implied in + assembly code]; + BN_LLONG bignum limbs are 32 bits, + but 64-bit 'unsigned long + long' is used internally + in calculations; + SIXTY_FOUR_BIT_LONG bignum limbs are 64 bits + and sizeof(long) is 8; + SIXTY_FOUR_BIT bignums limbs are 64 bits, + but execution environment + is ILP32; + RC4_CHAR RC4 key schedule is made + up of 'unsigned char's; + RC4_INT RC4 key schedule is made + up of 'unsigned int's; EXPORT_VAR_AS_FN for shared libraries, export vars as accessor functions. - cpuid_obj => assembler implementation of cpuid code as + apps_aux_src => Extra source to build apps/openssl and other + apps, as needed by the target and that can be + collected in a library. + apps_init_src => Init source to build apps/openssl and other + apps, as needed by the target. This code + cannot be placed in a library, as the rest + of the code isn't expected to link to it + explicitly. + cpuid_asm_src => assembler implementation of cpuid code as well as OPENSSL_cleanse(). - Default to mem_clr.o - bn_obj => assembler implementation of core bignum + Default to mem_clr.c + bn_asm_src => Assembler implementation of core bignum functions. - Defaults to bn_asm.o - ec_obj => assembler implementation of core EC + Defaults to bn_asm.c + ec_asm_src => Assembler implementation of core EC functions. - des_obj => assembler implementation of core DES + des_asm_src => Assembler implementation of core DES encryption functions. - Defaults to 'des_enc.o fcrypt_b.o' - aes_obj => assembler implementation of core AES + Defaults to 'des_enc.c fcrypt_b.c' + aes_asm_src => Assembler implementation of core AES functions. - Defaults to 'aes_core.o aes_cbc.o' - bf_obj => assembler implementation of core BF + Defaults to 'aes_core.c aes_cbc.c' + bf_asm_src => Assembler implementation of core BlowFish functions. - Defaults to 'bf_enc.o' - md5_obj => assembler implementation of core MD5 + Defaults to 'bf_enc.c' + md5_asm_src => Assembler implementation of core MD5 functions. - sha1_obj => assembler implementation of core SHA1, + sha1_asm_src => Assembler implementation of core SHA1, functions, and also possibly SHA256 and SHA512 ones. - cast_obj => assembler implementation of core BF + cast_asm_src => Assembler implementation of core CAST functions. - Defaults to 'c_enc.o' - rc4_obj => assembler implementation of core BF + Defaults to 'c_enc.c' + rc4_asm_src => Assembler implementation of core RC4 functions. - Defaults to 'rc4_enc.o rc4_skey.o' - rmd160_obj => assembler implementation of core RMD160 + Defaults to 'rc4_enc.c rc4_skey.c' + rmd160_asm_src => Assembler implementation of core RMD160 functions. - rc5_obj => assembler implementation of core RC4 + rc5_asm_src => Assembler implementation of core RC5 functions. - Defaults to 'rc5_enc.o' - wp_obj => assembler implementation of core WHIRLPOOL + Defaults to 'rc5_enc.c' + wp_asm_src => Assembler implementation of core WHIRLPOOL functions. - cmll_obj => assembler implementation of core CAMELLIA + cmll_asm_src => Assembler implementation of core CAMELLIA functions. - Defaults to 'camellia.o cmll_misc.o cmll_cbc.o' - modes_obj => assembler implementation of the - functions gcm_gmult_4bit and gcm_ghash_4bit. - engines_obj => assembler implementation of core parts of + Defaults to 'camellia.c cmll_misc.c cmll_cbc.c' + modes_asm_src => Assembler implementation of cipher modes, + currently the functions gcm_gmult_4bit and + gcm_ghash_4bit. + padlock_asm_src => Assembler implementation of core parts of the padlock engine. This is mandatory on any platform where the padlock engine might actually be built. @@ -227,7 +285,7 @@ In each table entry, the following keys are significant: 'inherit_from' that indicate what other configurations to inherit data from. These are resolved recursively. - Inheritance works as a set of default values that can be overriden + Inheritance works as a set of default values that can be overridden by corresponding key values in the inheriting configuration. Note 1: any configuration table can be used as a template. @@ -276,13 +334,430 @@ In each table entry, the following keys are significant: } [2] OpenSSL is built with threading capabilities unless the user - specifies 'no-threads'. The value of the key 'thread_cflags' may + specifies 'no-threads'. The value of the key 'thread_scheme' may be "(unknown)", in which case the user MUST give some compilation flags to Configure. +[3] OpenSSL has three types of things to link from object files or + static libraries: + + - shared libraries; that would be libcrypto and libssl. + - shared objects (sometimes called dynamic libraries); that would + be the engines. + - applications; those are apps/openssl and all the test apps. + + Very roughly speaking, linking is done like this (words in braces + represent the configuration settings documented at the beginning + of this file): + + shared libraries: + {ld} $(CFLAGS) {lflags} {shared_ldflag} -o libfoo.so \ + foo/something.o foo/somethingelse.o {ex_libs} + + shared objects: + {ld} $(CFLAGS) {lflags} {module_ldflags} -o libeng.so \ + blah1.o blah2.o -lcrypto {ex_libs} + + applications: + {ld} $(CFLAGS) {lflags} -o app \ + app1.o utils.o -lssl -lcrypto {ex_libs} + +[4] There are variants of these attribute, prefixed with `lib_', + `dso_' or `bin_'. Those variants replace the unprefixed attribute + when building library, DSO or program modules specifically. Historically, the target configurations came in form of a string with -values separated by colons. This use is deprecated, although -currently somewhat supported. The string form looks like this: +values separated by colons. This use is deprecated. The string form +looked like this: + + "target" => "{cc}:{cflags}:{unistd}:{thread_cflag}:{sys_id}:{lflags}:{bn_ops}:{cpuid_obj}:{bn_obj}:{ec_obj}:{des_obj}:{aes_obj}:{bf_obj}:{md5_obj}:{sha1_obj}:{cast_obj}:{rc4_obj}:{rmd160_obj}:{rc5_obj}:{wp_obj}:{cmll_obj}:{modes_obj}:{padlock_obj}:{perlasm_scheme}:{dso_scheme}:{shared_target}:{shared_cflag}:{shared_ldflag}:{shared_extension}:{ranlib}:{arflags}:{multilib}" + + +Build info files +================ + +The build.info files that are spread over the source tree contain the +minimum information needed to build and distribute OpenSSL. It uses a +simple and yet fairly powerful language to determine what needs to be +built, from what sources, and other relationships between files. + +For every build.info file, all file references are relative to the +directory of the build.info file for source files, and the +corresponding build directory for built files if the build tree +differs from the source tree. + +When processed, every line is processed with the perl module +Text::Template, using the delimiters "{-" and "-}". The hashes +%config and %target are passed to the perl fragments, along with +$sourcedir and $builddir, which are the locations of the source +directory for the current build.info file and the corresponding build +directory, all relative to the top of the build tree. + +To begin with, things to be built are declared by setting specific +variables: + + PROGRAMS=foo bar + LIBS=libsomething + ENGINES=libeng + SCRIPTS=myhack + EXTRA=file1 file2 + +Note that the files mentioned for PROGRAMS, LIBS and ENGINES *must* be +without extensions. The build file templates will figure them out. + +For each thing to be built, it is then possible to say what sources +they are built from: + + PROGRAMS=foo bar + SOURCE[foo]=foo.c common.c + SOURCE[bar]=bar.c extra.c common.c + +It's also possible to tell some other dependencies: + + DEPEND[foo]=libsomething + DEPEND[libbar]=libsomethingelse + +(it could be argued that 'libsomething' and 'libsomethingelse' are +source as well. However, the files given through SOURCE are expected +to be located in the source tree while files given through DEPEND are +expected to be located in the build tree) + +It's also possible to depend on static libraries explicitly: + + DEPEND[foo]=libsomething.a + DEPEND[libbar]=libsomethingelse.a + +This should be rarely used, and care should be taken to make sure it's +only used when supported. For example, native Windows build doesn't +support building static libraries and DLLs at the same time, so using +static libraries on Windows can only be done when configured +'no-shared'. + +One some platforms, shared libraries come with a name that's different +from their static counterpart. That's declared as follows: + + SHARED_NAME[libfoo]=cygfoo-{- $config{shlibver} -} + +The example is from Cygwin, which has a required naming convention. + +Sometimes, it makes sense to rename an output file, for example a +library: + + RENAME[libfoo]=libbar + +That line has "libfoo" renamed to "libbar". While it makes no +sense at all to just have a rename like that (why not just use +"libbar" everywhere?), it does make sense when it can be used +conditionally. See a little further below for an example. + +In some cases, it's desirable to include some source files in the +shared form of a library only: + + SHARED_SOURCE[libfoo]=dllmain.c + +For any file to be built, it's also possible to tell what extra +include paths the build of their source files should use: + + INCLUDE[foo]=include + +In some cases, one might want to generate some source files from +others, that's done as follows: + + GENERATE[foo.s]=asm/something.pl $(CFLAGS) + GENERATE[bar.s]=asm/bar.S + +The value of each GENERATE line is a command line or part of it. +Configure places no rules on the command line, except that the first +item must be the generator file. It is, however, entirely up to the +build file template to define exactly how those command lines should +be handled, how the output is captured and so on. + +Sometimes, the generator file itself depends on other files, for +example if it is a perl script that depends on other perl modules. +This can be expressed using DEPEND like this: + + DEPEND[asm/something.pl]=../perlasm/Foo.pm + +There may also be cases where the exact file isn't easily specified, +but an inclusion directory still needs to be specified. INCLUDE can +be used in that case: + + INCLUDE[asm/something.pl]=../perlasm + +NOTE: GENERATE lines are limited to one command only per GENERATE. + +As a last resort, it's possible to have raw build file lines, between +BEGINRAW and ENDRAW lines as follows: + + BEGINRAW[Makefile(unix)] + haha.h: {- $builddir -}/Makefile + echo "/* haha */" > haha.h + ENDRAW[Makefile(unix)] + +The word within square brackets is the build_file configuration item +or the build_file configuration item followed by the second word in the +build_scheme configuration item for the configured target within +parenthesis as shown above. For example, with the following relevant +configuration items: + + build_file => "build.ninja" + build_scheme => [ "unified", "unix" ] + +... these lines will be considered: + + BEGINRAW[build.ninja] + build haha.h: echo "/* haha */" > haha.h + ENDRAW[build.ninja] + + BEGINRAW[build.ninja(unix)] + build hoho.h: echo "/* hoho */" > hoho.h + ENDRAW[build.ninja(unix)] + +Should it be needed because the recipes within a RAW section might +clash with those generated by Configure, it's possible to tell it +not to generate them with the use of OVERRIDES, for example: + + SOURCE[libfoo]=foo.c bar.c + + OVERRIDES=bar.o + BEGINRAW[Makefile(unix)] + bar.o: bar.c + $(CC) $(CFLAGS) -DSPECIAL -c -o $@ $< + ENDRAW[Makefile(unix)] + +See the documentation further up for more information on configuration +items. + +Finally, you can have some simple conditional use of the build.info +information, looking like this: + + IF[1] + something + ELSIF[2] + something other + ELSE + something else + ENDIF + +The expression in square brackets is interpreted as a string in perl, +and will be seen as true if perl thinks it is, otherwise false. For +example, the above would have "something" used, since 1 is true. + +Together with the use of Text::Template, this can be used as +conditions based on something in the passed variables, for example: + + IF[{- $disabled{shared} -}] + LIBS=libcrypto + SOURCE[libcrypto]=... + ELSE + LIBS=libfoo + SOURCE[libfoo]=... + ENDIF + +or: + + # VMS has a cultural standard where all libraries are prefixed. + # For OpenSSL, the choice is 'ossl_' + IF[{- $config{target} =~ /^vms/ -}] + RENAME[libcrypto]=ossl_libcrypto + RENAME[libssl]=ossl_libssl + ENDIF + + +Build-file programming with the "unified" build system +====================================================== + +"Build files" are called "Makefile" on Unix-like operating systems, +"descrip.mms" for MMS on VMS, "makefile" for nmake on Windows, etc. + +To use the "unified" build system, the target configuration needs to +set the three items 'build_scheme', 'build_file' and 'build_command'. +In the rest of this section, we will assume that 'build_scheme' is set +to "unified" (see the configurations documentation above for the +details). + +For any name given by 'build_file', the "unified" system expects a +template file in Configurations/ named like the build file, with +".tmpl" appended, or in case of possible ambiguity, a combination of +the second 'build_scheme' list item and the 'build_file' name. For +example, if 'build_file' is set to "Makefile", the template could be +Configurations/Makefile.tmpl or Configurations/unix-Makefile.tmpl. +In case both Configurations/unix-Makefile.tmpl and +Configurations/Makefile.tmpl are present, the former takes +precedence. + +The build-file template is processed with the perl module +Text::Template, using "{-" and "-}" as delimiters that enclose the +perl code fragments that generate configuration-dependent content. +Those perl fragments have access to all the hash variables from +configdata.pem. + +The build-file template is expected to define at least the following +perl functions in a perl code fragment enclosed with "{-" and "-}". +They are all expected to return a string with the lines they produce. + + generatesrc - function that produces build file lines to generate + a source file from some input. + + It's called like this: + + generatesrc(src => "PATH/TO/tobegenerated", + generator => [ "generatingfile", ... ] + generator_incs => [ "INCL/PATH", ... ] + generator_deps => [ "dep1", ... ] + generator => [ "generatingfile", ... ] + incs => [ "INCL/PATH", ... ], + deps => [ "dep1", ... ], + intent => one of "libs", "dso", "bin" ); + + 'src' has the name of the file to be generated. + 'generator' is the command or part of command to + generate the file, of which the first item is + expected to be the file to generate from. + generatesrc() is expected to analyse and figure out + exactly how to apply that file and how to capture + the result. 'generator_incs' and 'generator_deps' + are include directories and files that the generator + file itself depends on. 'incs' and 'deps' are + include directories and files that are used if $(CC) + is used as an intermediary step when generating the + end product (the file indicated by 'src'). 'intent' + indicates what the generated file is going to be + used for. + + src2obj - function that produces build file lines to build an + object file from source files and associated data. + + It's called like this: + + src2obj(obj => "PATH/TO/objectfile", + srcs => [ "PATH/TO/sourcefile", ... ], + deps => [ "dep1", ... ], + incs => [ "INCL/PATH", ... ] + intent => one of "lib", "dso", "bin" ); + + 'obj' has the intended object file with '.o' + extension, src2obj() is expected to change it to + something more suitable for the platform. + 'srcs' has the list of source files to build the + object file, with the first item being the source + file that directly corresponds to the object file. + 'deps' is a list of explicit dependencies. 'incs' + is a list of include file directories. Finally, + 'intent' indicates what this object file is going + to be used for. + + obj2lib - function that produces build file lines to build a + static library file ("libfoo.a" in Unix terms) from + object files. + + called like this: + + obj2lib(lib => "PATH/TO/libfile", + objs => [ "PATH/TO/objectfile", ... ]); + + 'lib' has the intended library file name *without* + extension, obj2lib is expected to add that. 'objs' + has the list of object files to build this library. + + libobj2shlib - backward compatibility function that's used the + same way as obj2shlib (described next), and was + expected to build the shared library from the + corresponding static library when that was suitable. + NOTE: building a shared library from a static + library is now DEPRECATED, as they no longer share + object files. Attempting to do this will fail. + + obj2shlib - function that produces build file lines to build a + shareable object library file ("libfoo.so" in Unix + terms) from the corresponding object files. + + called like this: + + obj2shlib(shlib => "PATH/TO/shlibfile", + lib => "PATH/TO/libfile", + objs => [ "PATH/TO/objectfile", ... ], + deps => [ "PATH/TO/otherlibfile", ... ]); + + 'lib' has the base (static) library ffile name + *without* extension. This is useful in case + supporting files are needed (such as import + libraries on Windows). + 'shlib' has the corresponding shared library name + *without* extension. 'deps' has the list of other + libraries (also *without* extension) this library + needs to be linked with. 'objs' has the list of + object files to build this library. + + obj2dso - function that produces build file lines to build a + dynamic shared object file from object files. + + called like this: + + obj2dso(lib => "PATH/TO/libfile", + objs => [ "PATH/TO/objectfile", ... ], + deps => [ "PATH/TO/otherlibfile", + ... ]); + + This is almost the same as obj2shlib, but the + intent is to build a shareable library that can be + loaded in runtime (a "plugin"...). + + obj2bin - function that produces build file lines to build an + executable file from object files. + + called like this: + + obj2bin(bin => "PATH/TO/binfile", + objs => [ "PATH/TO/objectfile", ... ], + deps => [ "PATH/TO/libfile", ... ]); + + 'bin' has the intended executable file name + *without* extension, obj2bin is expected to add + that. 'objs' has the list of object files to build + this library. 'deps' has the list of library files + (also *without* extension) that the programs needs + to be linked with. + + in2script - function that produces build file lines to build a + script file from some input. + + called like this: + + in2script(script => "PATH/TO/scriptfile", + sources => [ "PATH/TO/infile", ... ]); + + 'script' has the intended script file name. + 'sources' has the list of source files to build the + resulting script from. + +In all cases, file file paths are relative to the build tree top, and +the build file actions run with the build tree top as current working +directory. + +Make sure to end the section with these functions with a string that +you thing is appropriate for the resulting build file. If nothing +else, end it like this: + + ""; # Make sure no lingering values end up in the Makefile + -} + + +Configure helper scripts +======================== + +Configure uses helper scripts in this directory: + +Checker scripts +--------------- + +These scripts are per platform family, to check the integrity of the +tools used for configuration and building. The checker script used is +either {build_platform}-{build_file}-checker.pm or +{build_platform}-checker.pm, where {build_platform} is the second +'build_scheme' list element from the configuration target data, and +{build_file} is 'build_file' from the same target data. - "target" => "{cc}:{cflags}:{unistd}:{thread_cflag}:{sys_id}:{lflags}:{bn_ops}:{cpuid_obj}:{bn_obj}:{ec_obj}:{des_obj}:{aes_obj}:{bf_obj}:{md5_obj}:{sha1_obj}:{cast_obj}:{rc4_obj}:{rmd160_obj}:{rc5_obj}:{wp_obj}:{cmll_obj}:{modes_obj}:{engines_obj}:{perlasm_scheme}:{dso_scheme}:{shared_target}:{shared_cflag}:{shared_ldflag}:{shared_extension}:{ranlib}:{arflags}:{multilib}" +If the check succeeds, the script is expected to end with a non-zero +expression. If the check fails, the script can end with a zero, or +with a `die`.