                 Regenerating the Symas OpenLDAP RPMs from SRPMs,
                        Creating an Installation Tarball
                                     and
                            Using Debugging Symbols

Introduction
------------
The bs.sh and bt.sh shell scripts work together to patch, build, test, and then
package Symas's OpenLDAP package into a set of binary RPMs and, optionally, a
an installation tarball. The tarball packaging method completely eliminates
the need for root privileges and both packaging methods allow you to change
the locations where Symas OpenLDAP is installed.

It's important to understand that these scripts are not designed to build
OpenLDAP from raw Project source- rather, they rebuild Symas OpenLDAP from 
source RPMs (SRPMs) that have been obtained from Symas's repositories.

When to Use These Scripts
-------------------------
Most users will not need to use these scripts. Instead, they can download,
install, and upgrade Symas OpenLDAP directly from Symas's online repository
using standard operating system tools such as yum and dnf. There are, however,
certain cases where using this script will be helpful:
    * Root privileges are not available on the systems where you intend to
      run Symas OpenLDAP
    * It is necessary to change Symas OpenLDAP's installation location
    * Your organization requires building Symas OpenLDAP from source

Software produced with this method has the following limitations:
    * Copies of Symas OpenLDAP installed from regenerated RPMs or tarballs
      produced with this method cannot be updated from Symas's online
      repositories. You must upgrade the packages from fresh RPMs or tarballs
      produced with these scripts.

What's Included
---------------
The package consists of the following files:
    * bs.sh - downloads, patches, and compiles all of the various source
      RPMs and then produces a new set of binary RPMs
    * bt.sh - unpacks those binary RPMs to create a tarball from which Symas
      OpenLDAP can be installed
    * common.sh - a file that contains utilities and scripts that are common
      used by both scripts
    * bvars.vars - contains settings and variables that are shared by both
      scripts
    * README - this file

Prerequisites
-------------
You will need the following items to build Symas OpenLDAP:
    * A system running Red Hat 7 or 8 (or an equivlent such as Alma Linux)
      with the development libraries and tools installed.
    * A small number of OS development libraries (complete list TBD)

Building the Symas OpenLDAP RPMs
--------------------------------
Follow the steps below to build and package Symas OpenLDAP from source, and
to optionally produce a tarball.

    1. Edit bvars.vars to match your needs. Key variables are:
       * Package version numbers
       * Repository addresses

    2. Obtain the SRPM files. If your build machine has access to the Internet
       you can simply set the repository address (soldRepoUrl) to the URL of
       the appropriate Symas repository and the bs.sh script will automatically
       download the SRPM files. Common URLs are listed in the bvars.vars file.

       If your build machine does not have access to the Internet, you'll
       need to manually download the SRPM files from the appropriate
       repository. The URLs for the testing and release repositories are
       listed in the release copy of bvars.vars
	
       You'll need the following SRPM files:
	    symas-cyrus-sasl-<version>.el8.src.rpm
	    symas-heimdal-<version>.el8.src.rpm
	    symas-libargon2-<version>.el8.src.rpm
	    symas-libevent-<version>.el8.src.rpm
	    symas-openldap-<version>.el8.src.rpm
	    symas-openldap-pw-bcrypt-<version>.el8.src.rpm
	    symas-openssl-<version>.el8.src.rpm

       Where <version> is the specific version of the SRPM file that you need.
       If you encounter multiple versions of the same SRPM, you should choose
       the newest one, Just make sure to update the corresponding version
       numbers match in the bvars.vars file.

    3. Add any patch files that will be needed for the build. Symas will
       occasionally supply patch files to correct defects in OpenLDAP. When
       this happens, add the patch file to the appropriate subdirectory of
       patch directory (patchDir). See bvars.vars file for additional
       information. Note that patch files are often obsoleted in subsequent
       releases of Symas OpenLDAP, so it is usually not necessary to carry them
       forward when you build a later release. The CHANGES file in the SRPM
       file lists defects that have been fixed in a release.
 
    4. Run the bs.sh script to rebuild Symas OpenLDAP and create a new set of
       binary RPMs.

       $ nohup bs.sh > build.log 2>&1 &
       $ tail -f build.log

       The script will do some basic checking and then compile, test, and
       generate new binary RPMs. The script will exit on errors, so make sure
       it completes. It is normal for a few warnings to be generated during
       the compilation and other processing phases.

       The new RPMs can be found in the directory ~/rpmbuild/RPMS/x86_64

    5. Review the build log. The bs.sh script will print this message when
       it completes sucessfully:
         "Symas OpenLDAP binary RPM creation is complete."
       It's always a good idea to review the build log for anomalies. Here
       are some key things to look for:
       * Expected patches were applied. Check to make sure expected patches
         were applied. Look for the string "Adding post-release patches" and
         review the following lines, looking for the names of the patches
         you expected to be applied.
       * Compilation errors (warnings are normal and can be ignored)
       * Test failures. These will terminate the build process, so they're
         relatively easy to spot. Contact Symas support for assistance.
       * Error messages from utilities such as cp, tar, etc.

       If you only need new binary RPMs you can stop here. Otherwise, continue
       to the next step to produce a tarball installer.

    6. Run the bt.sh script to create the tarball installer.

       $ nohup bt.sh >> build.log 2>&1 &

       The script will extract the necessary files from the binary RPMS,
       produce the installation tarball, and store it the user's home
       directory.

       You can now unpack the tarball relative to the directory specified
       by bt.sh when it completes. Note that creating the var directory and
       its subdirectories is your responsibility. You will also need to see
       to placement of the necessary systemd control files, as that's not
       something that the tarball installer will do.

