diff --git a/README.md b/README.md
index 698a22b..1c62682 100644
--- a/README.md
+++ b/README.md
@@ -5,6 +5,7 @@
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
@@ -21,6 +22,7 @@
working on debian or Ubuntu systems. You'll have to update the file if you
use `apt-get` package management.
+
## Release Versioning
Both the bootstrap and full build process create tarballs *and rename
@@ -45,6 +47,7 @@
to perform a full build. DAMHIKT.
+
## Building The Bootstrap Image
1. Log into your build machine, VM, or`docker`image.
@@ -59,25 +62,25 @@
bootstrapping processs, you also initally need some additional
perl module support. On CentOS7:
- `sudo yum -y groupinstall "Development Tools"`
+ sudo yum -y groupinstall "Development Tools"
- `sudo yum -y install perl-Module-Load-Conditional perl-core`
+ sudo yum -y install perl-Module-Load-Conditional perl-core
4. Get the linuxbrew image:
- `make getbrew`
+ make getbrew
5. Build the bootstrap image:
- `make bootstrap-build`
+ make bootstrap-build
6. Build a release tarball and export it:
- `make bootstrap-release`
+ make bootstrap-release
7. Cleanup:
- `make clean`
+ make clean
## Building The Full Tools Set
@@ -93,11 +96,11 @@
Recall that this was saved with a date revision stamp. So, before
proceeding, we have to:
- `cd ${INSTALLDIR} && mv -v ${TOOLS}-YYYYMMDD ${TOOLS}`
+ cd ${INSTALLDIR} && mv -v ${TOOLS}-YYYYMMDD ${TOOLS}
3. Setup the required environment variables:
- `. brewenv`
+ . brewenv
4. Make sure `${MYTOOLS}` and `${PIPMODULES}` include all the
packages you want.
@@ -105,15 +108,15 @@
5. Build the full tool set using the bootstrapped compiler we just
built:
- `make full-build`
+ make full-build
6. Export it for installation elsewhere:
- `make full-release`
+ make full-release
7. Cleanup:
- `make clean`
+ make clean
## Installing The Tools
@@ -128,7 +131,7 @@
libraries and other dependencies. So, if we built the tools
under:
- `/opt/mydir/tools`
+ /opt/mydir/tools
Every installation on other machines must also install them
there (and be added to `$(PATH}` as described in `brewenv`).
@@ -136,7 +139,7 @@
Recall that this procedure actually creates the tools directory
as:
- `/opt/mydir/tools-YYYYMMDD`.
+ /opt/mydir/tools-YYYYMMDD
In this example, you could either symlink `tools` to that
directory or just rename the directory accordingly.
@@ -149,6 +152,7 @@
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
@@ -158,3 +162,67 @@
Just be sure to edit it and change `TOOLSDIR="/opt/TundraWare/tools"`
to wherever your tools installation actually lives.
+
+
+## Do I Have To Do This Every Time I Want Newer Tools?
+
+No! Once you have running installation, you can use `brew` itself to
+do upgrades.
+
+But beware, dragons therein lie (sometimes). When you do this, you
+will only be updating the tools that `brew` knows have changed since
+you did the last build (or update). That's fine for the major things.
+But `brew` doesn't usually know about the `python` modules you've
+installed or custom `perl` modules using `cpan`. It's therefore
+possible to get weird version incompatibilities when an interpreter
+gets upgraded.
+
+It is therefore recommended that you not do manual upgrading yourself,
+but do this instead:
+
+ make upgrade
+
+This will both upgrade any relevant `brew` components, and also
+upgrade the `python` modules it initially installed itself. Obviously,
+it cannot catch things you've installed yourself thereafter. You can
+just add your own component upgrade commands to that same `makefile`
+stanza.
+
+Even so, you should periodically do a complete rebuild from the very
+beginning as outlined above. This will help minimize the accrued
+bitrot from incremental upgrades.
+
+## Important Reminder
+
+**Always** so any builds or upgrades with the destination directory
+named as it is found in the `makefile`. The various release stanzas
+temporarily rename that directory to `YYYYMMDD-myname` for purposes of
+creating release tarballs. You might be tempted to do this therefore:
+
+ ln -s YYYYMMDD-myname myname
+
+That's fine *so long as you make no changes or updates to what is in
+YYYYMMDD-myname*. If you upgrade things or otherwise change them with
+commands like `pip install mymodule`, you are asking for trouble.
+Why? Becase many programs have dependenies on where they are
+installed. Their installers will find their absolute and real path and
+use that for the dependency in your installation.
+
+So, if you create the tools using the `makefile`, it uses `myname` as
+the install location. If you then later use the `YYYYMMDD-myname`
+form with a symlink, and install or upgrade something, some of the
+binaries will depend on one name (the ones originally installed) and
+some will depend the new name (the ones you add or upgrade later).
+This officially causes Great Pain (tm). DAMHIKT.
+
+Just follow these two rules and you'll be fine:
+
+* Any time you are installing, upgrading, deleting or otherwise changing
+ the installation, make sure that the target directory is named `myname`.
+
+* If you are merely *using* the tools there, it's fine to create a symlink
+ like this:
+
+ myname -> YYYYMMDD-myname
+
+ This is handy if you want to work with different builds of the tools.
diff --git a/makefile b/makefile
index 3758418..d79d261 100644
--- a/makefile
+++ b/makefile
@@ -69,6 +69,11 @@
cd ${INSTALLDIR} && tar -czvf ${EXPORTDIR}/${TOOLS}-${DATESTAMP}.tar.gz ${TOOLS}-${DATESTAMP}
cd ${INSTALLDIR} && mv -v ${TOOLS}-${DATESTAMP} ${TOOLS}
+upgrade:
+ brew update
+ brew upgrade
+ pip install ${PIPMODULES} -U --ignore-installed
+
# Housekeeping
@@ -77,7 +82,6 @@
tidyup:
${BREW} config
-# ${BREW} prune
${BREW} cleanup
-${BREW} doctor