X-Git-Url: https://git.openssl.org/gitweb/?p=openssl.git;a=blobdiff_plain;f=Configurations%2FREADME;h=a5a006e46a348b28132c47b21ce17a6773bd358d;hp=c031884896065fe25bdccfa2f9b53ee1b5fb534b;hb=2a08d1a05db937f8b1a62422b78ffe2fa07d3ead;hpb=84af1bae68950a6993b56e39beff905d23fb74c8 diff --git a/Configurations/README b/Configurations/README index c031884896..a5a006e46a 100644 --- a/Configurations/README +++ b/Configurations/README @@ -28,30 +28,6 @@ In each table entry, the following keys are significant: given here, they MUST be as an array of the string such as "MACRO=value", or just "MACRO" for definitions without value. - debug_cflags => Extra compilation flags used when making a - debug build (when Configure receives the - --debug option). Typically something like - "-g -O0". - debug_defines => Similarly to `debug_cflags', this gets - combined with `defines' during a debug - build. The value here MUST also be an - array of the same form as for `defines'. - 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". - release_defines => Similarly to `release_cflags', this gets - combined with `defines' during a release - build. The value here MUST also be an - array of the same form as for `defines'. - thread_cflags => Extra compilation flags used when - compiling with threading enabled. - Explained further below. [2] - thread_defines => Similarly to `thread_cflags', this gets - combined with `defines' when threading is - enabled. The value here MUST also be an - array of the same form as for `defines'. shared_cflag => Extra compilation flags used when compiling for shared libraries, typically something like "-fPIC". @@ -70,9 +46,6 @@ In each table entry, the following keys are significant: ex_libs => Extra libraries that are needed when linking. - debug_lflags => Like debug_cflags, but used when linking. - release_lflags => Like release_cflags, but used when linking. - ar => The library archive command, the default is "ar". (NOTE: this is here for future use, it's @@ -97,6 +70,14 @@ In each table entry, the following keys are significant: this is here for future use, it's not implemented yet) + 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 @@ -119,7 +100,7 @@ In each table entry, the following keys are significant: string in the list is the name of the build scheme. Currently recognised build schemes are - "mk1mf" and "unixmake" and "unified". + "unixmake" and "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 @@ -216,7 +197,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. @@ -265,7 +246,7 @@ 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. @@ -377,13 +358,32 @@ 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 -It's possible to have raw build file lines, between BEGINRAW and -ENDRAW lines as follows: +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 the the first +item muct 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. + +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 @@ -409,6 +409,18 @@ configuration items: 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. @@ -480,6 +492,26 @@ 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", ... ] + 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. 'deps' is a list of explicit + dependencies. '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. @@ -530,7 +562,7 @@ They are all expected to return a string with the lines they produce. 'lib' has the intended library file name *without* extension, libobj2shlib is expected to add that. - 'shlib' has the correcponding shared library name + '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 @@ -596,7 +628,7 @@ 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 apropriate for the resulting build file. If nothing +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