# Build Standard Tools

This is automation support for the linuxbrew-based tools procedure
documented at:

    https://www.tundraware.com/TechnicalNotes/Divorce-Your-Linux-Admin

## How To Use The Makefile

This `makefile` handles both the bootstrapping and then the full release of
a custom linuxbrew based toolset, installed at any location you wish
(so long as you have write permission there).

Before doing anything, edit the variables as the top of the `makefile`
to reflect where you want the built tarballs to be exported, where you
intend to install the tools, and what set of tools you want installed.

## Release Versioning

Both the bootstrap and full build process create tarballs *and rename
the tools directory* with a version stamp in the form, `YYYYMMDD`.  The
idea is to allow multiple verisons of your toolsets to exist under
`${INSTALLDIR}`.  You simply create a symlink in that directory named
`${TOOLS}` to point to the version you want.  This makes certain
automation use cases with `tsshbatch` or `ansible` somewhat simpler.

HOWEVER, during the actual build process described here, *it is
important that the directory be named canonically*.  That is, it
should be located and named *where you intend to deploy it*. The
binaries care - a lot - about where to look for their libraries and
such.  So, for instance, if you are deploying to `/foo/bar/tools`,
don't build it under `/foo/bar/tools-20180324`.  You build under
`/foo/bar/tools`.  The release process will create a tarball that
contains `foo/bar/tools-YYYYMMDD` which you can untar to other
machines (under `/foo/bar/`).  You can then either just rename it to
`tools`, or create a symlink called `tools` that points to it.

Paying attention to this most likely bite you the first time you untar
a bootstrap tarball to perform a full build.  DAMHIKT.


## Building The Bootstrap Image

1. Log into your build machine, VM, or`docker`image.

2. Make sure you have write permission to the installation directory.

3. Make sure the native OS compiler tools are installed. *Do not
   include the tools directories in your `${PATH}` at this time.* We
   want this phase of the build to be done entirely with system tools.

4. Get the linuxbrew image:

     `make getbrew`

5. Build the bootstrap image:

     `make bootstrap-build`

6. Build a release tarball and export it:

     `make bootstrap-release`

7. Cleanup:

     `make clean`


## Building The Full Tools Set

1. Log into your build machine, VM, or`docker`image.  *Make sure this
   machine does *not* have native OS compilers and development tools
   installed and/or in `${PATH}`*!  We want to use only the compiler and
   tools created in the previous step. `Docker` containers are handy here:
   One for the bootstrap build, another for the self compiling
   full tools build.

   However, there are a few things that *are* required in the OS load,
   because of boneheaded assumptions made by some open source packages
   about where things live.  So:

     `sudo yum -y install autoconf automake perl   # Or whatever package management system you use`

2. Un-tar the bootstrap tarball created above into the proper location.
   Recall that this was saved with a date revision stamp.  So, before
   proceeding, we have to:

     `cd ${INSTALLDIR} && mv -v ${TOOLS}-YYYYMMDD ${TOOLS}`

3. Setup the required environment variables:

     `. brewenv`

4. Make sure `${MYTOOLS}` and `${PIPMODULES}` include all the
   packages you want.

5. Build the full tool set using the bootstrapped compiler we just
   built:

     `make full-build`

6. Export it for installation elsewhere:

     `make full-release`

7. Cleanup:

     `make clean`


## Installing The Tools

We've just created a tarball that has all the tools we want precompiled
and ready for distribution.  We just untar the full tools tarball onto
any other machine.  The only restrictions are:

  1. We must un-tar *so that the tools directory ends up in the same
     location in the filesystem as where it was built.*  The binaries
     created above make assumptions about where to find their
     libraries and other dependencies.  So, if we built the tools
     under:

       `/opt/mydir/tools`

     Every installation on other machines must also install them
     there (and be added to `$(PATH}` as described in `brewenv`).

     Recall that this procedure actually creates the tools directory
     as:

       `/opt/mydir/tools-YYYYMMDD`.

     In this example, you could either symlink `tools` to that
     directory or just rename the directory accordingly.

  2. The build- and target machines must have reasonably close kernel
     versions.  That's because the bootstrap phase makes use of native
     OS header files that are kernel-dependent.  If, say, you try to
     build this on a CentOS 7 instance, but then attempt to deploy to
     CentOS 5, expect problems.  *Always build your deploy image on an
     OS that is substantially the same as your targets.*  Again,
     `docker` is your friend here.

## The `brewenv` File

The `brewenv` file documents the environment variables that need to be
set in order to access your installed binaries and support files.  You
may find this useful when doing the full build.  You certainly will want
these variables set when running a final installation of your tools.

Just be sure to edit it and change `TOOLSDIR="/opt/TundraWare/tools"`
to wherever your tools installation actually lives.