This document describes an approach applied to packaging OpenSSL for build2.
In particular, this understanding will be useful when upgrading to a new
upstream version.

The upstream package contains the libcrypto and libssl libraries and the
openssl program that we all package separately (see respective README-DEV
files for details). It also contains dynamically loaded engines and tests that
we currently don't package.

We add the upstream package as a git submodule and symlink the required files
and subdirectories into the build2 package subdirectories. Then, when required,
we "overlay" the upstream with our own headers, placing them into the
library/program directories and their downstream/ subdirectories.

Note that symlinking upstream submodule subdirectories into a build2 package
subdirectory results in creating intermediate build files (.d, .o, etc) inside
upstream directory while building the package in source tree. That's why we
need to make sure that packages do not share upstream source files via
subdirectory symlinks, not to also share the related intermediate files. If
several packages need to compile the same upstream source file, then only one
of them can symlink it via the parent directory while others must symlink it
directly. We also add the `ignore = untracked` configuration option into
.gitmodules to make sure that git ignores the intermediate build files under
upstream/ subdirectory.

Normally, when packaging a project, we need to replace some auto-generated
headers with our own implementations and deduce compilation/linking options.
For autoconf/cmake-based projects we rely on the Makefile.am, CMakeList.txt
and .in/.cmake files for that. For OpenSSL, using its own Perl scripts-based
build infrastructure, that's not an option. Instead, we analyze the
auto-generated files (headers, makefiles, configdata.pm, etc.) and build logs,
produced for multiple platforms/architectures, and use some of them build-time.
For convenience, we have also stashed some of them in upstream-build/.

The upstream package can be configured to expose a specific feature set. We
reproduce the union of features configured for the upstream source package in
Debian and Fedora distributions. The configuration options defining these sets
are specified in the Debian's rules and Fedora's RPM .spec files. These files
can be obtained as follows:

$ wget https://kojipkgs.fedoraproject.org/packages/openssl/1.1.1k/1.fc35/src/openssl-1.1.1k-1.fc35.src.rpm
$ rpm2cpio openssl-1.1.1k-1.fc35.src.rpm | cpio -civ '*.spec'

$ wget http://deb.debian.org/debian/pool/main/o/openssl/openssl_1.1.1k-1.debian.tar.xz
$ tar xf openssl_1.1.1k-1.debian.tar.xz debian/rules

As a side note, on Debian and Fedora the libraries, headers and utility are
packaged as follows:

                libcrypto+libssl  headers        openssl
Debian/Ubuntu:  libssl1.1         libssl-dev     openssl
Fedora/RHEL:    openssl-libs      openssl-devel  openssl

Search for the Debian and Fedora packages at https://packages.debian.org/search
and https://src.fedoraproject.org/.

Here are the discovered configuration options.

Debian:

  no-idea no-mdc2 no-rc5 no-zlib no-ssl3 enable-unit-test no-ssl3-method
  enable-rfc3779 enable-cms no-capieng

Fedora:

  enable-zlib enable-camellia enable-seed enable-rfc3779 enable-sctp
  enable-cms enable-md2 enable-rc5 enable-ssl3 enable-ssl3-method
  enable-weak-ssl-ciphers no-mdc2 no-ec2m no-sm2 no-sm4

The union of these feature sets translates into the following options, after
suppressing the defaults:

  enable-md2 enable-rc5 enable-sctp enable-ssl3 enable-ssl3-method
  enable-weak-ssl-ciphers enable-zlib no-mdc2

We, however, drop the external dependencies that are not packaged for build2.
Besides that, we add no-asm to suppress replacing C code with auto-generated
ASM code for some algorithms. Later, we can potentially pre-generate ASM code
for architectures we support and get rid of this option. Also we add
no-devcryptoeng as devcryptoeng is automatically enabled on BSDs. So the
resulting options are:

  enable-md2 enable-rc5 enable-ssl3 enable-ssl3-method enable-weak-ssl-ciphers
  enable-zlib no-mdc2 no-asm no-devcryptoeng

Note that while we can use the upstream/INSTALL file to understand which of
the 'enable-<feature>' or 'no-<feature>' options are the default ones, it is a
good idea to verify the effective option set printed by the
`./configdata.pm --options` command run in the configuration directory.

Also note that on Windows you would need to additionally pass VC-WIN32 (i386)
or VC-WIN64A (x86_64) as a first argument to the Configure script when
configuring for building with VC (see upstream/INSTALL for details).

To build the upstream package and obtain the build log, run the following
commands in its root directory.

On POSIX and for MinGW GCC:

$ mkdir build
$ cd build
$ ../config enable-md2 enable-rc5 enable-ssl3 enable-ssl3-method \
  enable-weak-ssl-ciphers enable-zlib no-mdc2 no-asm no-devcryptoeng \
  >build.log 2>&1
$ make VERBOSE=1 >>build.log 2>&1

For MSVC:

> mkdir build
> cd build
> perl ../Configure VC-WIN64A enable-md2 enable-rc5 enable-ssl3 ^
  enable-ssl3-method enable-weak-ssl-ciphers enable-zlib no-mdc2 no-asm ^
  no-devcryptoeng >build.log 2>&1
> nmake VERBOSE=1 >>build.log 2>&1

Note that when building with MSVC (as of 16.4) you may need to remove the
/O2 option from the makefile prior to running nmake, to prevent the compiler
from hanging.

When the packaging is complete, build all the project packages in source tree
and make sure that no OpenSSL headers are included from the system, running
the following command from the project root:

$ fgrep -a -e /usr/include/openssl `find . -type f -name '*.d'`