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