X-Git-Url: https://git.openssl.org/?p=openssl.git;a=blobdiff_plain;f=Configurations%2FREADME.design;h=cae08fc249627cc6bedda084a1f023bda85d3951;hp=5065960a764aa63a3c8a42a2ee10ba16169d1cbc;hb=0ef40b76e745731a28f7340071c051316b8a1bae;hpb=ae4c7450754ea13265edd69e6ff74d87c89401cd diff --git a/Configurations/README.design b/Configurations/README.design index 5065960a76..cae08fc249 100644 --- a/Configurations/README.design +++ b/Configurations/README.design @@ -37,12 +37,13 @@ build-file templates, adapted for the platform they are meant for (see sections on %unified_info and build-file templates further down). The variables PROGRAMS, LIBS, ENGINES and SCRIPTS are used to declare -end products. +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 ORDINALS are indexed by a -produced file, and their values are the source used to produce that -particular produced file, extra dependencies, include directories -needed, and ordinal files (explained further below. +The variables SOURCE, DEPEND and INCLUDE are indexed by a produced +file, and their values are the source used to produce that particular +produced file, extra dependencies, and include directories needed. All their values in all the build.info throughout the source tree are collected together and form a set of programs, libraries, engines and @@ -55,18 +56,15 @@ dependencies. # build.info LIBS=libcrypto libssl - ORDINALS[libcrypto]=crypto - ORDINALS[libssl]=ssl INCLUDE[libcrypto]=include 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, there are some ordinals to be used to -declare what symbols in those libraries are seen as public, 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. +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. # apps/build.info PROGRAMS=openssl @@ -91,6 +89,7 @@ depends on the library 'libssl' to function properly. GENERATE[buildinf.h]=../util/mkbuildinf.pl "$(CC) $(CFLAGS)" "$(PLATFORM)" 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 @@ -103,9 +102,9 @@ 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 -also shows the possibility to include raw build-file statements in a -build.info file, in this case showing how 'buildinf.h' is built on -Unix-like operating systems. +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: @@ -123,27 +122,33 @@ 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 - ENGINES=libossltest - SOURCE[libossltest]=e_ossltest.c - DEPEND[libossltest]=../libcrypto - INCLUDE[libossltest]=../include - -This is the build.info file in 'engines/', telling us that an engine -called 'engines/libossltest' shall be built, that it's source is + ENGINES=dasync + SOURCE[dasync]=e_dasync.c + DEPEND[dasync]=../libcrypto + INCLUDE[dasync]=../include + + ENGINES_NO_INST=ossltest + SOURCE[ossltest]=e_ossltest.c + DEPEND[ossltest]=../libcrypto.a + INCLUDE[ossltest]=../include + +This is the build.info file in 'engines/', telling us that two engines +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 this engine. -Finally, the engine 'engines/libossltest' depends on the library -'libcrypto' to function properly. +be used when building anything that will be part of these engines. +Also, both engines 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 information comes down to this: LIBS=libcrypto libssl - ORDINALS[libcrypto]=crypto SOURCE[libcrypto]=crypto/aes.c crypto/evp.c crypto/cversion.c DEPEND[crypto/cversion.o]=crypto/buildinf.h INCLUDE[libcrypto]=include - ORDINALS[libssl]=ssl SOURCE[libssl]=ssl/tls.c INCLUDE[libssl]=include DEPEND[libssl]=libcrypto @@ -153,13 +158,19 @@ information comes down to this: INCLUDE[apps/openssl]=. include DEPEND[apps/openssl]=libssl - ENGINES=engines/libossltest - SOURCE[engines/libossltest]=engines/e_ossltest.c - DEPEND[engines/libossltest]=libcrypto - INCLUDE[engines/libossltest]=include + ENGINES=engines/dasync + SOURCE[engines/dasync]=engines/e_dasync.c + DEPEND[engines/dasync]=libcrypto + INCLUDE[engines/dasync]=include + + ENGINES_NO_INST=engines/ossltest + SOURCE[engines/ossltest]=engines/e_ossltest.c + DEPEND[engines/ossltest]=libcrypto.a + INCLUDE[engines/ossltest]=include GENERATE[crypto/buildinf.h]=util/mkbuildinf.pl "$(CC) $(CFLAGS)" "$(PLATFORM)" DEPEND[crypto/buildinf.h]=Makefile + DEPEND[util/mkbuildinf.pl]=util/Foo.pm A few notes worth mentioning: @@ -170,13 +181,14 @@ PROGRAMS may be used to declare programs only. ENGINES may be used to declare engines only. -The indexes for SOURCE, INCLUDE and ORDINALS must only be end product -files, such as libraries, programs or engines. The values of SOURCE -variables must only be source files (possibly generated) +The indexes for SOURCE must only be end product files, such as +libraries, programs or engines. The values of SOURCE variables must +only be source files (possibly generated). -DEPEND shows a relationship between different produced files, such -as a program depending on a library, or between an object file and -some extra source file. +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 truth without question, and will therefore perform very few checks. @@ -202,19 +214,22 @@ indexes: engines => a list of engines. These are directly inferred from the ENGINES 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. + 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', 'engines' 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. - ordinals => a hash table containing 'file' => [ 'word', 'ordfile' ] - pairs. 'file' and 'word' are directly inferred from - the ORDINALS variables in build.info files, while the - file 'ofile' comes from internal knowledge in - Configure. - programs => a list of programs. These are directly inferred from the PROGRAMS variable in build.info files. @@ -233,6 +248,10 @@ indexes: 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. + As an example, here is how the build.info files example from the section above would be digested into a %unified_info table: @@ -243,23 +262,46 @@ section above would be digested into a %unified_info table: [ "libssl", ], + "crypto/buildinf.h" => + [ + "Makefile", + ], "crypto/cversion.o" => [ "crypto/buildinf.h", ], - "engines/libossltest" => + "engines/dasync" => [ "libcrypto", ], + "engines/ossltest" => + [ + "libcrypto.a", + ], "libssl" => [ "libcrypto", ], + "util/mkbuildinf.pl" => + [ + "util/Foo.pm", + ], }, "engines" => [ - "engines/libossltest", + "engines/dasync", + "engines/ossltest", ], + "generate" => + { + "crypto/buildinf.h" => + [ + "util/mkbuildinf.pl", + "\"\$(CC)", + "\$(CFLAGS)\"", + "\"$(PLATFORM)\"", + ], + }, "includes" => { "apps/openssl" => @@ -267,7 +309,7 @@ section above would be digested into a %unified_info table: ".", "include", ], - "engines/libossltest" => + "engines/ossltest" => [ "include" ], @@ -279,34 +321,38 @@ section above would be digested into a %unified_info table: [ "include", ], + "util/mkbuildinf.pl" => + [ + "util", + ], } - "libraries" => - [ - "libcrypto", - "libssl", - ], - "ordinals" => + "install" => { - "libcrypto" => + "engines" => [ - "crypto", - "util/libcrypto.num", + "engines/dasync", ], - "libssl" => + "libraries" => + [ + "libcrypto", + "libssl", + ], + "programs" => [ - "ssl", - "util/libssl.num", + "apps/openssl", ], - }, + }, + "libraries" => + [ + "libcrypto", + "libssl", + ], "programs" => [ "apps/openssl", ], "rawlines" => [ - "crypto/buildinf.h : Makefile", - " perl util/mkbuildinf.h \"\$(CC) \$(CFLAGS)\" \"\$(PLATFORM)\" \\" - " > crypto/buildinf.h" ], "sources" => { @@ -330,11 +376,19 @@ section above would be digested into a %unified_info table: [ "crypto/evp.c", ], + "engines/e_dasync.o" => + [ + "engines/e_dasync.c", + ], + "engines/dasync" => + [ + "engines/e_dasync.o", + ], "engines/e_ossltest.o" => [ "engines/e_ossltest.c", ], - "engines/libossltest" => + "engines/ossltest" => [ "engines/e_ossltest.o", ], @@ -378,6 +432,34 @@ build static libraries from object files, to build shared libraries from static libraries, to programs from object files and libraries, etc. + 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", ... ] + 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. @@ -423,8 +505,7 @@ etc. libobj2shlib(shlib => "PATH/TO/shlibfile", lib => "PATH/TO/libfile", objs => [ "PATH/TO/objectfile", ... ], - deps => [ "PATH/TO/otherlibfile", ... ], - ordinals => [ "word", "/PATH/TO/ordfile" ]); + deps => [ "PATH/TO/otherlibfile", ... ]); 'lib' has the intended library file name *without* extension, libobj2shlib is expected to add that. @@ -433,11 +514,7 @@ etc. libraries (also *without* extension) this library needs to be linked with. 'objs' has the list of object files (also *without* extension) to build - this library. 'ordinals' MAY be present, and when - it is, its value is an array where the word is - "crypto" or "ssl" and the file is one of the ordinal - files util/libcrypto.num or util/libssl.num in the - source directory. + this library. This function has a choice; it can use the corresponding static library as input to make the @@ -497,7 +574,7 @@ programs and all intermediate files, using the rule generating functions defined in the build-file template. As an example with the smaller build.info set we've seen as an -example, producing the rules to build 'libssl' would result in the +example, producing the rules to build 'libcrypto' would result in the following calls: # Note: libobj2shlib will only be called if shared libraries are @@ -505,25 +582,42 @@ following calls: # Note 2: libobj2shlib gets both the name of the static library # and the names of all the object files that go into it. It's up # to the implementation to decide which to use as input. - libobj2shlib(shlib => "libssl", - lib => "libssl", - objs => [ "ssl/tls.o" ], - deps => [ "libcrypto" ] - ordinals => [ "ssl", "util/libssl.num" ]); - - obj2lib(lib => "libssl" - objs => [ "ssl/tls.o" ]); - - # Note 3: common.tmpl peals off the ".o" extension, as the - # platform at hand may have a different one. - src2obj(obj => "ssl/tls" - srcs => [ "ssl/tls.c" ], + # Note 3: common.tmpl peals off the ".o" extension from all object + # files, as the platform at hand may have a different one. + libobj2shlib(shlib => "libcrypto", + lib => "libcrypto", + objs => [ "crypto/aes", "crypto/evp", "crypto/cversion" ], + deps => [ ]); + + obj2lib(lib => "libcrypto" + objs => [ "crypto/aes", "crypto/evp", "crypto/cversion" ]); + + src2obj(obj => "crypto/aes" + srcs => [ "crypto/aes.c" ], deps => [ ], - incs => [ "include" ]); + incs => [ "include" ], + intent => "lib"); - src2dep(obj => "ssl/tls" - srcs => [ "ssl/tls.c" ], - incs => [ "include" ]); + src2obj(obj => "crypto/evp" + srcs => [ "crypto/evp.c" ], + deps => [ ], + incs => [ "include" ], + intent => "lib"); + + src2obj(obj => "crypto/cversion" + srcs => [ "crypto/cversion.c" ], + deps => [ "crypto/buildinf.h" ], + incs => [ "include" ], + intent => "lib"); + + generatesrc(src => "crypto/buildinf.h", + generator => [ "util/mkbuildinf.pl", "\"$(CC)", + "$(CFLAGS)\"", "\"$(PLATFORM)\"" ], + generator_incs => [ "util" ], + generator_deps => [ "util/Foo.pm" ], + incs => [ ], + deps => [ ], + intent => "lib"); The returned strings from all those calls are then concatenated together and written to the resulting build-file.