etc/README.md: updated.

1 files changed, 37 insertions, 19 deletions

diff --git a/etc/README.md b/etc/README.md
index e501b355..92786105 100644
--- a/etc/README.md
+++ b/etc/README.md
@@ -16,6 +16,7 @@ internal repositories required in order to build Midipix.
 	3.2. [Adding a package](#32-adding-a-package)  

 	3.3. [Addressing build failure](#33-addressing-build-failure)  

 	3.4. [Patches and ``vars`` files](#34-patches-and-vars-files)  

+	3.5. [``pkgtool.sh``](#35-pkgtoolsh)  

 4. [Build variables](#4-build-variables)  

 	4.1. [Build steps](#41-build-steps)  

 	4.2. [Package variables](#42-package-variables)  

@@ -284,25 +285,9 @@ package configuration failed or appears relevant, log the configuration process
 in, most usually, ``${PKG_BUILD_DIR}/config.log``.  

 

 If ``--dump-on-abort`` was specified, a subset of the variables set and environment

-variables will be written to ``${BUILD_WORKDIR}/${PKG_NAME}.dump``, which may subsequently

-be used in order to obtain a package build shell environment with ``pkgtool.sh``, e.g.:  

-  

-```

-midipix_build@sandbox:(src/midipix_build)> $ ./pkgtool.sh mc

-==> 2020/03/11 15:46:28 Launching shell `/usr/bin/zsh' within package environment and `/home/midipix_build/midipix/nt64/debug/tmp'.

-==> 2020/03/11 15:46:28 Run $R to rebuild `mc'.

-==> 2020/03/11 15:46:28 Run $RS <step> to restart the specified build step of `mc'

-==> 2020/03/11 15:46:28 Run $D to automatically regenerate the patch for `mc'.

-midipix_build@sandbox:(src/midipix_build)> $

-```

-  

-Consult sections [3.2](#32-adding-a-package), [3.4](#34-patches-and-vars-files), [4](#4-build-variables),

-[4.1](#41-build-steps), and [4.2](#42-package-variables) for further information

-concerning the package build process.  

-  

-> N.B. When using ``pkgtool.sh`` on a build w/ build variables (see section [4](#4-build-variables))

-overriden on the command line or via the environment, ensure that they are included in the

-``pkgtool.sh`` command line or exported, respectively.

+variables exported will be written to ``${BUILD_WORKDIR}/${PKG_NAME}.dump``, which may

+subsequently be used in order to obtain a package build shell environment with the

+``pkgtool.sh`` script (see section [3.5](#35-pkgtoolsh).)

   

 [Back to top](#table-of-contents)

 

@@ -334,6 +319,39 @@ for a list of package build steps and how they are overriden.
 [Back to top](#table-of-contents)

 

 [//]: # "}}}"

+[//]: # "{{{ 3.5. ``pkgtool.sh``"

+## 3.5. ``pkgtool.sh``

+

+When ``build.sh`` is executed with the ``--dump-on-abort`` option, a subset of the

+variables set and environment variables exported will be written to ``${BUILD_WORKDIR}/${PKG_NAME}.dump``

+on build failure, which may subsequently be used in order to obtain a package build shell

+environment with the ``pkgtool.sh`` script, e.g.:  

+  

+```

+midipix_build@sandbox:(src/midipix_build)> $ ./pkgtool.sh -a nt64 -b debug mc

+==> 2020/03/11 15:46:28 Launching shell `/usr/bin/zsh' within package environment and `/home/midipix_build/midipix/nt64/debug/tmp'.

+==> 2020/03/11 15:46:28 Run $R to rebuild `mc'.

+==> 2020/03/11 15:46:28 Run $RS <step> to restart the specified build step of `mc'

+==> 2020/03/11 15:46:28 Run $D to automatically regenerate the patch for `mc'.

+midipix_build@sandbox:(src/midipix_build)> $

+```

+  

+If a package build shell environment is desired for a package that has either not been

+built at all or built successfully, ``pkgshell.sh`` will attempt to rebuild the package

+at build steps up until, by default, ``build``, and then forcibly abort the build and

+write ``${BUILD_WORKDIR}/${PKG_NAME}.dump`` as above prior to entering the shell.  

+  

+Consult sections [3.2](#32-adding-a-package), [3.4](#34-patches-and-vars-files), [4](#4-build-variables),

+[4.1](#41-build-steps), and [4.2](#42-package-variables) for further information

+concerning the package build process.  

+  

+> N.B. When using ``pkgtool.sh`` on a build w/ build variables (see section [4](#4-build-variables))

+overriden on the command line or via the environment, ensure that they are included in the

+``pkgtool.sh`` command line, preceding the package name, or exported, respectively.

+  

+[Back to top](#table-of-contents)

+

+[//]: # "}}}"

 

 [//]: # "{{{ 4. Build variables"

 ## 4. Build variables