+ "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)
+
+For some libraries, we maintain files with public symbols and their
+slot in a transfer vector (important on some platforms). It can be
+declared like this:
+
+ ORDINALS[libcrypto]=crypto
+
+The value is not the name of the file in question, but rather the
+argument to util/mkdef.pl that indicates which file to use.
+
+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 lines has "libfoo" get 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.
+
+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:
+
+ BEGINRAW[Makefile(unix)]
+ haha.h: {- $builddir -}/Makefile
+ echo "/* haha */" > haha.h
+ ENDRAW[Makefile(unix)]
+
+The word withing 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)]
+
+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.
+
+ 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 *without*
+ extension, src2obj() is expected to add that.
+ '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 (also *without*
+ extension) to build this library.
+
+ libobj2shlib - function that produces build file lines to build a
+ shareable object library file ("libfoo.so" in Unix
+ terms) from the corresponding static library file
+ or object files.
+
+ called like this:
+
+ libobj2shlib(shlib => "PATH/TO/shlibfile",
+ lib => "PATH/TO/libfile",
+ objs => [ "PATH/TO/objectfile", ... ],
+ deps => [ "PATH/TO/otherlibfile", ... ],
+ ordinals => [ "word", "/PATH/TO/ordfile" ]);
+
+ 'lib' has the intended library file name *without*
+ extension, libobj2shlib is expected to add that.
+ 'shlib' has the correcponding 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 (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/libeay.num or util/ssleay.num in the
+ source directory.
+
+ This function has a choice; it can use the
+ corresponding static library as input to make the
+ shared library, or the list of object files.
+
+ 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 libobj2shlib, but the
+ intent is to build a shareable library that can be
+ loaded in runtime (a "plugin"...). The differences
+ are subtle, one of the most visible ones is that the
+ resulting shareable library is produced from object
+ files only.
+
+ 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 (also
+ *without* extension) 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 apropriate for the resulting build file. If nothing
+else, end it like this:
+
+ ""; # Make sure no lingering values end up in the Makefile
+ -}
projects / openssl.git / blobdiff