X-Git-Url: https://git.librecmc.org/?a=blobdiff_plain;f=Configurations%2FREADME.design;h=41c2949d0874c6089ec012a6f4d245549454582a;hb=5f9b64a2fdfd0ccf04d58c8b04d576f13950d63f;hp=574982fb5a2bdb4aff80dfc8c94403ca1e0aaae1;hpb=2a08d1a05db937f8b1a62422b78ffe2fa07d3ead;p=oweals%2Fopenssl.git diff --git a/Configurations/README.design b/Configurations/README.design index 574982fb5a..41c2949d08 100644 --- a/Configurations/README.design +++ b/Configurations/README.design @@ -37,7 +37,9 @@ 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 @@ -91,6 +93,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 +106,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,17 +126,25 @@ 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: @@ -153,13 +164,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 +187,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 +The indexes for SOURCE 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) -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,10 +220,19 @@ 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. @@ -247,23 +274,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" => @@ -271,7 +321,7 @@ section above would be digested into a %unified_info table: ".", "include", ], - "engines/libossltest" => + "engines/ossltest" => [ "include" ], @@ -283,7 +333,27 @@ section above would be digested into a %unified_info table: [ "include", ], + "util/mkbuildinf.pl" => + [ + "util", + ], } + "install" => + { + "engines" => + [ + "engines/dasync", + ], + "libraries" => + [ + "libcrypto", + "libssl", + ], + "programs" => + [ + "apps/openssl", + ], + }, "libraries" => [ "libcrypto", @@ -308,9 +378,6 @@ section above would be digested into a %unified_info table: ], "rawlines" => [ - "crypto/buildinf.h : Makefile", - " perl util/mkbuildinf.h \"\$(CC) \$(CFLAGS)\" \"\$(PLATFORM)\" \\" - " > crypto/buildinf.h" ], "sources" => { @@ -334,11 +401,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", ], @@ -382,6 +457,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. @@ -501,7 +604,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 @@ -509,25 +612,43 @@ 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 => [ ] + ordinals => [ "crypto", "util/libcrypto.num" ]); + + 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.