Blame etc/README.md

Lucio Andrés Illanes Albornoz a6970c
> N.B. If you're interested in building Midipix using this script, please join
Lucio Andrés Illanes Albornoz a6970c
the project's IRC channel #midipix on Freenode and ask for the address of the
Lucio Andrés Illanes Albornoz a6970c
internal repositories required in order to build Midipix.
Lucio Andrés Illanes Albornoz a6970c
Lucio Andrés Illanes Albornoz a6970c
[//]: # "{{{ Table of contents"
Lucio Andrés Illanes Albornoz a6970c
# Table of Contents
Lucio Andrés Illanes Albornoz a6970c
Lucio Andrés Illanes Albornoz a6970c
1. [What is midipix, and how is it different?](#1-what-is-midipix-and-how-is-it-different)  
Lucio Andrés Illanes Albornoz ac032e
2. [Building, installing, and using a midipix distribution](#2-building-installing-and-using-a-midipix-distribution)  
Lucio Andrés Illanes Albornoz a6970c
	2.1. [Build-time dependencies](#21-build-time-dependencies)  
Lucio Andrés Illanes Albornoz a6970c
		2.1.1. [Alpine-specific notate bene](#211-alpine-specific-notate-bene)  
Lucio Andrés Illanes Albornoz a6970c
	2.2. [Deployment](#22-deployment)  
Lucio Andrés Illanes Albornoz a6970c
	2.3. [System requirements](#23-system-requirements)  
Lucio Andrés Illanes Albornoz ac032e
	2.4. [Troubleshooting](#24-troubleshooting)  
Lucio Andrés Illanes Albornoz a6970c
3. [Common tasks](#3-common-tasks)  
Lucio Andrés Illanes Albornoz a6970c
	3.1. [Fault-tolerant & highly optimised 3D laser show-equipped usage screen](#31-fault-tolerant--highly-optimised-3d-laser-show-equipped-usage-screen)  
Lucio Andrés Illanes Albornoz a6970c
	3.2. [Adding a package](#32-adding-a-package)  
Lucio Andrés Illanes Albornoz a6970c
	3.3. [Addressing build failure](#33-addressing-build-failure)  
Lucio Andrés Illanes Albornoz a6970c
	3.4. [Patches and ``vars`` files](#34-patches-and-vars-files)  
Lucio Andrés Illanes Albornoz a6970c
	3.5. [``pkgtool.sh``](#35-pkgtoolsh)  
Lucio Andrés Illanes Albornoz a6970c
		3.5.1. [``-s``: package build shell environment](#351-s-package-build-shell-environment)  
Lucio Andrés Illanes Albornoz a6970c
4. [Build variables](#4-build-variables)  
Lucio Andrés Illanes Albornoz a6970c
	4.1. [Build steps](#41-build-steps)  
Lucio Andrés Illanes Albornoz a6970c
	4.2. [Package variables](#42-package-variables)  
Lucio Andrés Illanes Albornoz a6970c
5. [References](#5-references)  
Lucio Andrés Illanes Albornoz a6970c
Lucio Andrés Illanes Albornoz a6970c
[//]: "}}}"
Lucio Andrés Illanes Albornoz a6970c
Lucio Andrés Illanes Albornoz a6970c
[//]: # "{{{ 1. What is midipix, and how is it different?"
Lucio Andrés Illanes Albornoz a6970c
## 1. What is midipix, and how is it different?
Lucio Andrés Illanes Albornoz a6970c
Lucio Andrés Illanes Albornoz a6970c
midipix is a development environment that lets you create programs
Lucio Andrés Illanes Albornoz a6970c
for Windows using the standard C and POSIX APIs. No compromises made,
Lucio Andrés Illanes Albornoz a6970c
no shortcuts taken.  
Lucio Andrés Illanes Albornoz a6970c
  
Lucio Andrés Illanes Albornoz a6970c
If you are interested in cross-platform programming that reclaims
Lucio Andrés Illanes Albornoz a6970c
the notion of write once, compile everywhere; if you believe that the
Lucio Andrés Illanes Albornoz a6970c
'standard' in the C Standard Library should not be a null signifier;
Lucio Andrés Illanes Albornoz a6970c
and if you like cooking your code without #ifdef hell and low-level
Lucio Andrés Illanes Albornoz a6970c
minutiae, then this page is for you.  
Lucio Andrés Illanes Albornoz a6970c
  
Lucio Andrés Illanes Albornoz a6970c
midipix makes cross-platform programming better, simpler and faster,
Lucio Andrés Illanes Albornoz a6970c
specifically by bringing a modern, conforming C Runtime Library to the
Lucio Andrés Illanes Albornoz a6970c
Windows platform. While the idea itself is not new, the approach taken
Lucio Andrés Illanes Albornoz a6970c
in midipix to code portability is radically different from that found
Lucio Andrés Illanes Albornoz a6970c
in other projects.  
Lucio Andrés Illanes Albornoz a6970c
  
Lucio Andrés Illanes Albornoz a6970c
*(reproduced from [[2](https://midipix.org/#sec-midipix)])*
Lucio Andrés Illanes Albornoz a6970c
  
Lucio Andrés Illanes Albornoz a6970c
[Back to top](#table-of-contents)
Lucio Andrés Illanes Albornoz a6970c
Lucio Andrés Illanes Albornoz a6970c
[//]: "}}}"
Lucio Andrés Illanes Albornoz a6970c
Lucio Andrés Illanes Albornoz ac032e
[//]: # "{{{ 2. Building, installing, and using a midipix distribution"
Lucio Andrés Illanes Albornoz ac032e
## 2. Building, installing and using a midipix distribution
Lucio Andrés Illanes Albornoz a6970c
Lucio Andrés Illanes Albornoz a6970c
A Midipix distribution consists of the following:
Lucio Andrés Illanes Albornoz a6970c
* the native Midipix toolchain, consisting of perk, gcc, its dependencies,
Lucio Andrés Illanes Albornoz a6970c
  and binutils,
Lucio Andrés Illanes Albornoz a6970c
* musl, a lightweight, fast, simple, and free libc[[1](https://www.musl-libc.org/faq.html)] used by Midipix,
Lucio Andrés Illanes Albornoz a6970c
* the Midipix runtime components that bridge the gap between the libc and the
Lucio Andrés Illanes Albornoz a6970c
  executive subsystems of all Windows NT-derived Windows OS starting with and
Lucio Andrés Illanes Albornoz a6970c
  including Windows XP, and
Lucio Andrés Illanes Albornoz a6970c
* a steadily increasing number of 3rd party open source packages, as expected in
Lucio Andrés Illanes Albornoz a6970c
  any modern POSIX-compliant \*nix environment, including GNU coreutils, shells,
Lucio Andrés Illanes Albornoz a6970c
  libraries such as ncurses, libressl, as well as Perl and Python.
Lucio Andrés Illanes Albornoz a6970c
Lucio Andrés Illanes Albornoz a6970c
Install the build-time dependencies listed in section [2.1](#21-build-time-dependencies),
Lucio Andrés Illanes Albornoz f4b29e
clone this repository (e.g. ``git clone https://dev.midipix.org/build/midipix_build``)
Lucio Andrés Illanes Albornoz f4b29e
and run the following command line:
Lucio Andrés Illanes Albornoz a6970c
Lucio Andrés Illanes Albornoz a6970c
```shell
Lucio Andrés Illanes Albornoz a6970c
./build.sh -a nt64 -b release -D zipdist -P -v
Lucio Andrés Illanes Albornoz a6970c
```
Lucio Andrés Illanes Albornoz a6970c
Lucio Andrés Illanes Albornoz a6970c
By default, the build will take place within ``${HOME}/midipix/nt64/release``
Lucio Andrés Illanes Albornoz a6970c
and package archive files and/or Git repositores will be downloaded into
Lucio Andrés Illanes Albornoz a6970c
``${HOME}/midipix/dlcache``. Consult sections [3.1](#31-fault-tolerant--highly-optimised-3d-laser-show-equipped-usage-screen), [4](#4-build-variables), and [4.1](#42-package-variables)
Lucio Andrés Illanes Albornoz a6970c
for the list of available build variables and how to override them.  
Lucio Andrés Illanes Albornoz a6970c
Parallelisation is enabled by the above command line for both packages that can
Lucio Andrés Illanes Albornoz a6970c
be built independently of each other and ``make(1)`` via ``-j``, limited to the
Lucio Andrés Illanes Albornoz a6970c
amount of logical processors on the build host divided by two (2).
Lucio Andrés Illanes Albornoz a6970c
  
Lucio Andrés Illanes Albornoz a6970c
[Back to top](#table-of-contents)
Lucio Andrés Illanes Albornoz a6970c
Lucio Andrés Illanes Albornoz a6970c
[//]: # "}}}"
Lucio Andrés Illanes Albornoz a6970c
[//]: # "{{{ 2.1. Build-time dependencies"
Lucio Andrés Illanes Albornoz a6970c
### 2.1. Build-time dependencies
Lucio Andrés Illanes Albornoz a6970c
Lucio Andrés Illanes Albornoz 6bc7e5
* **Alpine Linux**: binutils bzip2 cmake coreutils curl findutils g++ gawk gcc
Lucio Andrés Illanes Albornoz a6970c
		    git grep gzip libc-dev linux-headers lzip make musl-dev
Lucio Andrés Illanes Albornoz a6970c
		    net-tools patch perl perl-xml-parser procps sed tar
Lucio Andrés Illanes Albornoz a6970c
		    util-linux wget xz zip
Lucio Andrés Illanes Albornoz 6bc7e5
* **Debian/-derived Linux**: binutils bzip2 clzip cmake coreutils curl findutils g++ gawk
Lucio Andrés Illanes Albornoz 6bc7e5
			     gcc git grep gzip hostname libc6-dev libxml-parser-perl lzma
Lucio Andrés Illanes Albornoz 6bc7e5
			     make patch perl procps sed tar util-linux wget xz-utils zip
Lucio Andrés Illanes Albornoz a6970c
* **OpenSUSE Linux**: binutils bzip2 cmake coreutils curl findutils gawk gcc
Lucio Andrés Illanes Albornoz a6970c
		      gcc-c++ git grep gzip hostname linux-glibc-devel lzip make
Lucio Andrés Illanes Albornoz a6970c
		      patch perl perl-XML-Parser procps sed tar util-linux wget
Lucio Andrés Illanes Albornoz a6970c
		      xz zip
Lucio Andrés Illanes Albornoz a6970c
  
Lucio Andrés Illanes Albornoz 6bc7e5
> N.B. Busybox is not supported. Awk implementations other than GNU Awk are not supported.
Lucio Andrés Illanes Albornoz a6970c
  
Lucio Andrés Illanes Albornoz a6970c
[Back to top](#table-of-contents)
Lucio Andrés Illanes Albornoz a6970c
Lucio Andrés Illanes Albornoz a6970c
[//]: # "}}}"
Lucio Andrés Illanes Albornoz a6970c
[//]: # "{{{ 2.1.1. Alpine-specific notate bene"
Lucio Andrés Illanes Albornoz a6970c
#### 2.1.1. Alpine-specific notate bene
Lucio Andrés Illanes Albornoz a6970c
Lucio Andrés Illanes Albornoz a6970c
Some packages (*coreutils*, *grep*, and *tar*, among others) override Alpine's
Lucio Andrés Illanes Albornoz a6970c
BusyBox utilities of the same name, as the latter are either non-conformant or
Lucio Andrés Illanes Albornoz a6970c
defective.
Lucio Andrés Illanes Albornoz a6970c
  
Lucio Andrés Illanes Albornoz a6970c
[Back to top](#table-of-contents)
Lucio Andrés Illanes Albornoz a6970c
Lucio Andrés Illanes Albornoz a6970c
[//]: # "}}}"
Lucio Andrés Illanes Albornoz a6970c
[//]: # "{{{ 2.2. Deployment"
Lucio Andrés Illanes Albornoz a6970c
### 2.2. Deployment
Lucio Andrés Illanes Albornoz a6970c
Lucio Andrés Illanes Albornoz a6970c
On successful completion of the build, a ZIP archive containing the Midipix
Lucio Andrés Illanes Albornoz a6970c
distribution will be created inside ``${PREFIX}`` (see section [4](#4-build-variables).)
Lucio Andrés Illanes Albornoz a6970c
Create a directory on the target machine and extract the contents of the distribution
Lucio Andrés Illanes Albornoz a6970c
ZIP archive into it, run ``bash.bat``, and then ``/install.sh`` inside the resulting
Lucio Andrés Illanes Albornoz a6970c
self-contained Midipix installation shell window.  
Lucio Andrés Illanes Albornoz a6970c
  
Lucio Andrés Illanes Albornoz a6970c
> N.B. The pathname of the target directory containing ``bash.bat`` and all other
Lucio Andrés Illanes Albornoz a6970c
distribution files must not contain whitespaces.  
Lucio Andrés Illanes Albornoz a6970c
  
Lucio Andrés Illanes Albornoz a6970c
> N.B. The Midipix installer defaults to ``/dev/fs/c/midipix (C:\midipix)``. If left
Lucio Andrés Illanes Albornoz a6970c
unchanged, the distribution ZIP archive must not be extracted into a directory of the
Lucio Andrés Illanes Albornoz a6970c
same pathname.  
Lucio Andrés Illanes Albornoz a6970c
  
Lucio Andrés Illanes Albornoz 6bc7e5
> N.B. The user installing and using Midipix must have been delegated the ``SeCreateSymbolicLinkPrivilege``
Lucio Andrés Illanes Albornoz 6bc7e5
("Create symbolic links") privilege[[3](https://docs.microsoft.com/en-us/windows/security/threat-protection/security-policy-settings/user-rights-assignment)] and additionally be a non-administrator account
Lucio Andrés Illanes Albornoz 6bc7e5
owing to the UAC-related filtering policy of tokens introduced by Windows Vista[[4](https://docs.microsoft.com/en-us/previous-versions/dotnet/articles/bb530410%28v%3dmsdn%2e10%29)].  
Lucio Andrés Illanes Albornoz 6bc7e5
  
Lucio Andrés Illanes Albornoz a6970c
[Back to top](#table-of-contents)
Lucio Andrés Illanes Albornoz a6970c
Lucio Andrés Illanes Albornoz a6970c
[//]: # "}}}"
Lucio Andrés Illanes Albornoz a6970c
[//]: # "{{{ 2.3. System requirements"
Lucio Andrés Illanes Albornoz a6970c
### 2.3. System requirements
Lucio Andrés Illanes Albornoz a6970c
Lucio Andrés Illanes Albornoz ac032e
The following build-time system requirements are assessed on build hosts
Lucio Andrés Illanes Albornoz ac032e
equipped with the following hardware at minimum:
Lucio Andrés Illanes Albornoz a6970c
* Intel(R) Xeon(R) CPU W3520 @ 2.67GHz (8 cores)
Lucio Andrés Illanes Albornoz a6970c
* 7200 RPM SATA 3.1 HDD
Lucio Andrés Illanes Albornoz a6970c
* 6 GB RAM
Lucio Andrés Illanes Albornoz a6970c
Lucio Andrés Illanes Albornoz a6970c
| Target architecture | Build kind | Distribution kinds selected | Average build time | Disk space required | Peak RAM usage |
Lucio Andrés Illanes Albornoz a6970c
| ------------------- | ---------- | --------------------------- | ------------------ | ------------------- | -------------- |
Lucio Andrés Illanes Albornoz a6970c
| nt64                | debug      | (none)                      | 2 hours            | 57.62 GB            | 3.55 GB        |
Lucio Andrés Illanes Albornoz a6970c
| nt64                | release    | (none)                      | 1 hours 45 minutes | 36.51 GB            | 3.21 GB        |
Lucio Andrés Illanes Albornoz a6970c
Lucio Andrés Illanes Albornoz a6970c
Package archive files and/or Git repositories additionally consume at least
Lucio Andrés Illanes Albornoz a6970c
1.82 GB.
Lucio Andrés Illanes Albornoz a6970c
Lucio Andrés Illanes Albornoz a6970c
*(last update: Thu, 05 Mar 2020 09:25:41 +0000)*
Lucio Andrés Illanes Albornoz ac032e
Lucio Andrés Illanes Albornoz c10b30
These are the Midipix distribution disk space system requirements:
Lucio Andrés Illanes Albornoz ac032e
Lucio Andrés Illanes Albornoz c10b30
| Target architecture | Build kind | Distribution | Installation directory | Archive file |
Lucio Andrés Illanes Albornoz c10b30
| ------------------- | ---------- | ------------ | ---------------------- | ------------ |
Lucio Andrés Illanes Albornoz c10b30
| nt64                | debug      | 7.3 GB       |  2.3 GB                | 2.1 GB       |
Lucio Andrés Illanes Albornoz c10b30
| nt64                | release    | 3.2 GB       |  913 MB                | 830 MB       |
Lucio Andrés Illanes Albornoz c10b30
Lucio Andrés Illanes Albornoz c10b30
The installation directory and archive file may be safely deleted post-installation.
Lucio Andrés Illanes Albornoz c10b30
Lucio Andrés Illanes Albornoz c10b30
*(last update: Thu, 07 Jan 2021 18:20:06 +0000)*
Lucio Andrés Illanes Albornoz ac032e
  
Lucio Andrés Illanes Albornoz ac032e
[Back to top](#table-of-contents)
Lucio Andrés Illanes Albornoz ac032e
Lucio Andrés Illanes Albornoz ac032e
[//]: # "}}}"
Lucio Andrés Illanes Albornoz ac032e
[//]: # "{{{ 2.4. Troubleshooting"
Lucio Andrés Illanes Albornoz ac032e
### 2.4. Troubleshooting
Lucio Andrés Illanes Albornoz ac032e
Lucio Andrés Illanes Albornoz ac032e
Midipix presently provides, inter alia, strace-like functionality via
Lucio Andrés Illanes Albornoz 6ab687
ntctty's logging capabilities. This is available both through the regular
Lucio Andrés Illanes Albornoz 6ab687
``strace(1)`` command as distributed, which however **must** be provided
Lucio Andrés Illanes Albornoz 6ab687
with an absolute pathname without consideration for ``${PATH}``, as well
Lucio Andrés Illanes Albornoz 6ab687
as directly via ``ntctty.exe`` for a session by running ``ntctty.exe``
Lucio Andrés Illanes Albornoz 6ab687
with the ``--log-level 7`` option, e.g.:
Lucio Andrés Illanes Albornoz ac032e
Lucio Andrés Illanes Albornoz ac032e
```shell
Lucio Andrés Illanes Albornoz 6ab687
$ #strace ls -la /        # (incorrect, relative pathname)
Lucio Andrés Illanes Albornoz 6ab687
$ strace /bin/ls -la /    # (correct, absolute pathname)
Lucio Andrés Illanes Albornoz 6ab687
$ ntctty.exe --log-level 7 -e /bin/ls -la /
Lucio Andrés Illanes Albornoz 6ab687
$ ntctty.exe --log-level=7 -e /bin/ls -la /
Lucio Andrés Illanes Albornoz 6ab687
$ ntctty.exe --log-level 7 -e /bin/sh -c "ls -la /"
Lucio Andrés Illanes Albornoz 6ab687
$ ntctty.exe --log-level=7 -e /bin/sh -c "ls -la /"
Lucio Andrés Illanes Albornoz ac032e
```
Lucio Andrés Illanes Albornoz ac032e
Lucio Andrés Illanes Albornoz 6ab687
By default, ``ntctty.exe`` log files are written into the /var/log/ntctty
Lucio Andrés Illanes Albornoz 6ab687
directory; this may be adjusted with the ``--log-dir`` and/or
Lucio Andrés Illanes Albornoz 6ab687
``--log-file`` options. ``strace(1)`` logs to stderr by default.
Lucio Andrés Illanes Albornoz a6970c
  
Lucio Andrés Illanes Albornoz a6970c
[Back to top](#table-of-contents)
Lucio Andrés Illanes Albornoz a6970c
Lucio Andrés Illanes Albornoz a6970c
[//]: # "}}}"
Lucio Andrés Illanes Albornoz a6970c
Lucio Andrés Illanes Albornoz a6970c
[//]: # "{{{ 3. Common tasks"
Lucio Andrés Illanes Albornoz a6970c
## 3. Common tasks
Lucio Andrés Illanes Albornoz a6970c
Lucio Andrés Illanes Albornoz a6970c
Rebuild set of packages in isolation:
Lucio Andrés Illanes Albornoz a6970c
```shell
Lucio Andrés Illanes Albornoz a6970c
./build.sh [ ... ] -r mc,zsh
Lucio Andrés Illanes Albornoz a6970c
```
Lucio Andrés Illanes Albornoz a6970c
  
Lucio Andrés Illanes Albornoz a6970c
Rebuild set of packages along w/ their dependencies, if any, as needed, or forcibly,
Lucio Andrés Illanes Albornoz a6970c
respectively:
Lucio Andrés Illanes Albornoz a6970c
```shell
Lucio Andrés Illanes Albornoz a6970c
./build.sh [ ... ] -r \*mc,zsh
Lucio Andrés Illanes Albornoz a6970c
./build.sh [ ... ] -r \*\*mc,zsh
Lucio Andrés Illanes Albornoz a6970c
```
Lucio Andrés Illanes Albornoz a6970c
  
Lucio Andrés Illanes Albornoz a6970c
Forcibly rebuild all reverse dependencies of a set of packages:
Lucio Andrés Illanes Albornoz a6970c
```shell
Lucio Andrés Illanes Albornoz a6970c
./build.sh [ ... ] -r \*\*\*glib,libflac
Lucio Andrés Illanes Albornoz a6970c
```
Lucio Andrés Illanes Albornoz a6970c
  
Lucio Andrés Illanes Albornoz a6970c
Restart the ``configure``, ``build``, and ``install`` steps of the ``coreutils``
Lucio Andrés Illanes Albornoz a6970c
package:
Lucio Andrés Illanes Albornoz a6970c
```shell
Lucio Andrés Illanes Albornoz a6970c
./build.sh -r coreutils:configure,build,install
Lucio Andrés Illanes Albornoz a6970c
```
Lucio Andrés Illanes Albornoz a6970c
  
Lucio Andrés Illanes Albornoz a6970c
Rebuild entire build groups including or excluding group dependencies, respectively:
Lucio Andrés Illanes Albornoz a6970c
```shell
Lucio Andrés Illanes Albornoz a6970c
./build.sh [ ... ] -r ALL native_runtime
Lucio Andrés Illanes Albornoz a6970c
./build.sh [ ... ] -r ALL =native_runtime
Lucio Andrés Illanes Albornoz a6970c
```
Lucio Andrés Illanes Albornoz a6970c
  
Lucio Andrés Illanes Albornoz a6970c
[Back to top](#table-of-contents)
Lucio Andrés Illanes Albornoz a6970c
Lucio Andrés Illanes Albornoz a6970c
[//]: # "}}}"
Lucio Andrés Illanes Albornoz a6970c
[//]: # "{{{ 3.1. Fault-tolerant & highly optimised 3D laser show-equipped usage screen"
Lucio Andrés Illanes Albornoz a6970c
## 3.1. Fault-tolerant & highly optimised 3D laser show-equipped usage screen
Lucio Andrés Illanes Albornoz a6970c
Lucio Andrés Illanes Albornoz a6970c
```
Lucio Andrés Illanes Albornoz a6970c
usage: ./build.sh [-a nt32|nt64] [-b debug|release] [-C dir[,..]] [-d] [-D kind[,..]]
Lucio Andrés Illanes Albornoz a6970c
                  [-F ipv4|ipv6|offline]    [-h]    [-p jobs]    [-P]   [-r ALL|LAST]
Lucio Andrés Illanes Albornoz a6970c
                  [-r [*[*[*]]]name[,..][:step,..]]  [-R] [-v[v[v[v]]]] [--as-needed]
Lucio Andrés Illanes Albornoz e2bbb8
                  [--debug-minipix] [--dump-on-abort] [--roar]
Lucio Andrés Illanes Albornoz a6970c
                  [[=]<group>|<variable name>=<variable override>[ ..]]
Lucio Andrés Illanes Albornoz a6970c
Lucio Andrés Illanes Albornoz a6970c
        -a nt32|nt64      Selects 32-bit or 64-bit architecture; defaults to nt64.
Lucio Andrés Illanes Albornoz a6970c
        -b debug|release  Selects debug or release build kind; defaults to debug.
Lucio Andrés Illanes Albornoz a6970c
        -C dir[,..]       Clean build directory (build,) ${PREFIX} before processing build
Lucio Andrés Illanes Albornoz a6970c
                          scripts (prefix,) source directory (src,) and/or destination
Lucio Andrés Illanes Albornoz a6970c
                          directory (dest) after successful package builds.
Lucio Andrés Illanes Albornoz a6970c
        -D kind[,..]      Produce minimal midipix distribution directory (minipix,) RPM
Lucio Andrés Illanes Albornoz a6970c
                          binary packages (rpm,) and/or deployable distribution ZIP
Lucio Andrés Illanes Albornoz a6970c
                          archive (zipdist.) zipdist implies minipix.
Lucio Andrés Illanes Albornoz a6970c
        -F ipv4|ipv6|offline
Lucio Andrés Illanes Albornoz a6970c
                          Force IPv4 (ipv4) or IPv6 (ipv6) when downloading package
Lucio Andrés Illanes Albornoz a6970c
                          archives and/or Git repositories or don't download either at all
Lucio Andrés Illanes Albornoz a6970c
                          (offline.)
Lucio Andrés Illanes Albornoz a6970c
        -h                Show this screen.
Lucio Andrés Illanes Albornoz a6970c
        -p jobs           Enables parallelisation at group-level, whenever applicable.
Lucio Andrés Illanes Albornoz a6970c
        -P                The maximum count of jobs defaults to the number of logical
Lucio Andrés Illanes Albornoz a6970c
                          processors on the host system divided by two (2.)
Lucio Andrés Illanes Albornoz a6970c
Lucio Andrés Illanes Albornoz a6970c
                          If -R is not specified and at least one (1) package fails to
Lucio Andrés Illanes Albornoz a6970c
                          build, all remaining package builds will be forcibly aborted.
Lucio Andrés Illanes Albornoz a6970c
Lucio Andrés Illanes Albornoz a6970c
        -r ALL|LAST       Restart all packages or the last failed package and resume
Lucio Andrés Illanes Albornoz a6970c
                          build, resp.
Lucio Andrés Illanes Albornoz a6970c
        -r [*[*[*]]]name[,..][:step,..]
Lucio Andrés Illanes Albornoz a6970c
                          Restart the specified comma-separated package(s) completely or
Lucio Andrés Illanes Albornoz a6970c
                          at optionally specified comma-separated list of build steps.
Lucio Andrés Illanes Albornoz a6970c
Lucio Andrés Illanes Albornoz a6970c
                          Prepend w/ `*' to automatically include dependencies, `**' to
Lucio Andrés Illanes Albornoz a6970c
                          forcibly rebuild all dependencies, and `***` to forcibly rebuild
Lucio Andrés Illanes Albornoz a6970c
                          all packages that depend on the specified package(s).
Lucio Andrés Illanes Albornoz a6970c
Lucio Andrés Illanes Albornoz a6970c
                          Currently defined build steps are:
Lucio Andrés Illanes Albornoz a6970c
                          fetch_wget, fetch_git, fetch_extract, configure_patch_pre,
Lucio Andrés Illanes Albornoz a6970c
                          configure_autotools, configure_patch, configure, build,
Lucio Andrés Illanes Albornoz a6970c
                          install_subdirs, install_make, install_files, install_libs,
Lucio Andrés Illanes Albornoz a6970c
                          install, and install_rpm.
Lucio Andrés Illanes Albornoz a6970c
Lucio Andrés Illanes Albornoz a6970c
        -R                Ignore build failures, skip printing package logs, and continue
Lucio Andrés Illanes Albornoz a6970c
                          building (relaxed mode.)
Lucio Andrés Illanes Albornoz a6970c
        -v[v[v[v]]]       Be verbose; -vv: always print package logs; -vvv: set xtrace
Lucio Andrés Illanes Albornoz a6970c
                          during package builds; -vvvv: logs fileops.
Lucio Andrés Illanes Albornoz a6970c
        --as-needed       Don't build unless the midipix_build repository has received
Lucio Andrés Illanes Albornoz a6970c
                          new commits.
Lucio Andrés Illanes Albornoz a6970c
        --debug-minipix   Don't strip(1) minipix binaries to facilitate debugging minipix.
Lucio Andrés Illanes Albornoz a6970c
        --dump-on-abort   Produce package environment dump files on build failure to be
Lucio Andrés Illanes Albornoz a6970c
                          used in conjuction with pkg_shell.sh script (excludes -R.)
Lucio Andrés Illanes Albornoz a6970c
        <group>[ ..]      One of: dev_packages, dist, host_deps, host_deps_rpm,
Lucio Andrés Illanes Albornoz a6970c
                          host_toolchain, host_tools, minipix, native_packages,
Lucio Andrés Illanes Albornoz a6970c
                          native_runtime, native_toolchain, native_tools.
Lucio Andrés Illanes Albornoz a6970c
Lucio Andrés Illanes Albornoz a6970c
                          Prepend w/ `=' to inhibit group-group dependency expansion.
Lucio Andrés Illanes Albornoz a6970c
Lucio Andrés Illanes Albornoz a6970c
        <variable name>=<variable override>[ ..]
Lucio Andrés Illanes Albornoz a6970c
                          Override build or package variable.
Lucio Andrés Illanes Albornoz a6970c
```
Lucio Andrés Illanes Albornoz a6970c
  
Lucio Andrés Illanes Albornoz a6970c
[Back to top](#table-of-contents)
Lucio Andrés Illanes Albornoz a6970c
Lucio Andrés Illanes Albornoz a6970c
[//]: # "}}}"
Lucio Andrés Illanes Albornoz a6970c
[//]: # "{{{ 3.2. Adding a package"
Lucio Andrés Illanes Albornoz a6970c
## 3.2. Adding a package
Lucio Andrés Illanes Albornoz a6970c
Lucio Andrés Illanes Albornoz a6970c
Packages are grouped into *build groups* according to sets of common package
Lucio Andrés Illanes Albornoz a6970c
variable defaults, such as ``${PKG_CFLAGS_CONFIGURE}, ${PKG_LDFLAGS_CONFIGURE}``
Lucio Andrés Illanes Albornoz a6970c
and ``${PKG_CONFIGURE_ARGS}``, and semantic interrelatedness, such as the
Lucio Andrés Illanes Albornoz a6970c
``native_runtime`` build group comprising the Midipix runtime components.
Lucio Andrés Illanes Albornoz a6970c
Packages may belong to more than one build group such as when subsumed by a shorthand
Lucio Andrés Illanes Albornoz a6970c
build group e.g. the ``dev_packages`` build group, as long as the default set of build
Lucio Andrés Illanes Albornoz a6970c
groups or as overriden on the command line does not entail group membership conflicts.  
Lucio Andrés Illanes Albornoz a6970c
  
Lucio Andrés Illanes Albornoz a6970c
Build groups files beneath ``groups/`` named ``[0-9][0-9][0-9].<group name>.group``
Lucio Andrés Illanes Albornoz a6970c
contain package variable defaults, the alphabetically sorted list of contained
Lucio Andrés Illanes Albornoz a6970c
packages in ``<upper case group name>_PACKAGES``, and their package variables
Lucio Andrés Illanes Albornoz a6970c
sorted alphabetically with the exception of ``${PKG_DEPENDS}`` (if present,)
Lucio Andrés Illanes Albornoz a6970c
``${PKG_SHA256SUM}``, ``${PKG_URL}``, and ``${PKG_VERSION}``, and/or ``${PKG_URLS_GIT}``,
Lucio Andrés Illanes Albornoz a6970c
which are specified in this order.  
Lucio Andrés Illanes Albornoz a6970c
  
Lucio Andrés Illanes Albornoz a6970c
Pick a build group according to the criteria mentioned, add the package to the
Lucio Andrés Illanes Albornoz a6970c
build group's list of contained packages in its corresponding file, and add the
Lucio Andrés Illanes Albornoz a6970c
set of package variables required (see above and section [4.2](#42-package-variables).)  
Lucio Andrés Illanes Albornoz a6970c
Consult section [3.4](#34-patches-and-vars-files) if the package to be added
Lucio Andrés Illanes Albornoz a6970c
requires patches or additional code amending or replacing package build steps
Lucio Andrés Illanes Albornoz a6970c
or the entire package build. Consult section [4.1](#41-build-steps) for a list
Lucio Andrés Illanes Albornoz a6970c
of package build steps and how they are overriden.
Lucio Andrés Illanes Albornoz a6970c
  
Lucio Andrés Illanes Albornoz a6970c
[Back to top](#table-of-contents)
Lucio Andrés Illanes Albornoz a6970c
Lucio Andrés Illanes Albornoz a6970c
[//]: # "}}}"
Lucio Andrés Illanes Albornoz a6970c
[//]: # "{{{ 3.3. Addressing build failure"
Lucio Andrés Illanes Albornoz a6970c
## 3.3. Addressing build failure
Lucio Andrés Illanes Albornoz a6970c
Lucio Andrés Illanes Albornoz a6970c
During package build, standard error and output are redirected into a log file beneath
Lucio Andrés Illanes Albornoz a6970c
``${BUILD_WORKDIR}`` named ``${PKG_NAME}_stderrout.log``, following a package variable
Lucio Andrés Illanes Albornoz a6970c
dump. If ``-vv`` was specified, package logs will additionally be printed to standard
Lucio Andrés Illanes Albornoz a6970c
output. If ``-vvv`` was specified, ``xtrace`` will be set during package builds for
Lucio Andrés Illanes Albornoz a6970c
rudimentary debugging purposes. Additionally, packages using GNU autotools will, if
Lucio Andrés Illanes Albornoz a6970c
package configuration failed or appears relevant, log the configuration process in detail
Lucio Andrés Illanes Albornoz a6970c
in, most usually, ``${PKG_BUILD_DIR}/config.log``.  
Lucio Andrés Illanes Albornoz a6970c
Lucio Andrés Illanes Albornoz a6970c
If ``--dump-on-abort`` was specified, a subset of the variables set and environment
Lucio Andrés Illanes Albornoz a6970c
variables exported will be written to ``${BUILD_WORKDIR}/${PKG_NAME}.dump``, which may
Lucio Andrés Illanes Albornoz a6970c
subsequently be used in order to obtain a package build shell environment with the
Lucio Andrés Illanes Albornoz a6970c
``pkgtool.sh`` script (see sections [3.5](#35-pkgtoolsh)[3.5.1](#351-s-package-build-shell-environment).)
Lucio Andrés Illanes Albornoz a6970c
  
Lucio Andrés Illanes Albornoz a6970c
[Back to top](#table-of-contents)
Lucio Andrés Illanes Albornoz a6970c
Lucio Andrés Illanes Albornoz a6970c
[//]: # "}}}"
Lucio Andrés Illanes Albornoz a6970c
[//]: # "{{{ 3.4. Patches and ``vars`` files"
Lucio Andrés Illanes Albornoz a6970c
## 3.4. Patches and ``vars`` files
Lucio Andrés Illanes Albornoz a6970c
Lucio Andrés Illanes Albornoz a6970c
Package patches are applied prior and/or subsequent to (GNU autotools or simular) package
Lucio Andrés Illanes Albornoz a6970c
configuration during the ``configure_patch_pre`` and/or ``configure_patch`` build steps,
Lucio Andrés Illanes Albornoz a6970c
respectively (see section [4.1](#41-build-steps).) Patch files are searched for beneath
Lucio Andrés Illanes Albornoz a6970c
``patches/`` with the following globs and in-order:
Lucio Andrés Illanes Albornoz a6970c
* ``${PKG_NAME}-${PKG_VERSION}_pre.local.patch``
Lucio Andrés Illanes Albornoz a6970c
  or ``${PKG_NAME}_pre.local.patch`` (for packages lacking ``${PKG_VERSION}``)
Lucio Andrés Illanes Albornoz a6970c
* ``${PKG_NAME}-${PKG_VERSION}_pre.local@${BUILD_HNAME}.patch``
Lucio Andrés Illanes Albornoz a6970c
  or ``${PKG_NAME}_pre.local@${BUILD_HNAME}.patch`` (for packages lacking ``${PKG_VERSION}``)
Lucio Andrés Illanes Albornoz a6970c
* ``${PKG_NAME}/*.patch``
Lucio Andrés Illanes Albornoz a6970c
* ``${PKG_NAME}-${PKG_VERSION}.local.patch``
Lucio Andrés Illanes Albornoz a6970c
  or ``${PKG_NAME}.local.patch`` (for packages lacking ``${PKG_VERSION}``)
Lucio Andrés Illanes Albornoz a6970c
* ``${PKG_NAME}-${PKG_VERSION}.local@${BUILD_HNAME}.patch``
Lucio Andrés Illanes Albornoz a6970c
  or ``${PKG_NAME}.local@${BUILD_HNAME}.patch`` (for packages lacking ``${PKG_VERSION}``)
Lucio Andrés Illanes Albornoz a6970c
* ``${PKG_PATCHES_EXTRA}`` (if set)
Lucio Andrés Illanes Albornoz a6970c
  
Lucio Andrés Illanes Albornoz a6970c
If the default set of package build steps does not suffice, such as if additional commands
Lucio Andrés Illanes Albornoz a6970c
must be executed after package configuration or prior to building, or if an entire or all
Lucio Andrés Illanes Albornoz a6970c
build step must be replaced, overrides may be specified in the form of functions in the
Lucio Andrés Illanes Albornoz a6970c
package's ``vars/${PKG_NAME}.vars`` ``vars`` file. Consult section [4.1](#41-build-steps)
Lucio Andrés Illanes Albornoz a6970c
for a list of package build steps and how they are overriden.
Lucio Andrés Illanes Albornoz a6970c
  
Lucio Andrés Illanes Albornoz a6970c
[Back to top](#table-of-contents)
Lucio Andrés Illanes Albornoz a6970c
Lucio Andrés Illanes Albornoz a6970c
[//]: # "}}}"
Lucio Andrés Illanes Albornoz a6970c
[//]: # "{{{ 3.5. ``pkgtool.sh``"
Lucio Andrés Illanes Albornoz a6970c
## 3.5. ``pkgtool.sh``
Lucio Andrés Illanes Albornoz a6970c
Lucio Andrés Illanes Albornoz a6970c
```
Lucio Andrés Illanes Albornoz 368962
usage: ./pkgtool.sh [-a nt32|nt64] [-b debug|release] [-i|-m <dname1>,<dname2>|-r|-s|-t]
Lucio Andrés Illanes Albornoz 368962
                    [<variable name>=<variable override>[ ..]] name
Lucio Andrés Illanes Albornoz 368962
Lucio Andrés Illanes Albornoz 368962
        -a nt32|nt64          Selects 32-bit or 64-bit architecture; defaults to nt64.
Lucio Andrés Illanes Albornoz 368962
        -b debug|release      Selects debug or release build kind; defaults to debug.
Lucio Andrés Illanes Albornoz 368962
        -i                    List package variables and dependencies of single named package.
Lucio Andrés Illanes Albornoz 368962
        -m <dname1>,<dname2>  Setup package archives mirror in <dname1> and Git repositories mirror in <dname2>
Lucio Andrés Illanes Albornoz 368962
        -r                    List reverse dependencies of single named package.
Lucio Andrés Illanes Albornoz 368962
        -s                    Enter interactive package build shell environment for single
Lucio Andrés Illanes Albornoz 368962
                              named package; requires a package dump file. If the package
Lucio Andrés Illanes Albornoz 368962
                              has not been built yet or built successfully, it will be rebuilt
Lucio Andrés Illanes Albornoz 368962
                              at build steps up until, by default, the `build' build step and
Lucio Andrés Illanes Albornoz 368962
                              forcibly aborted and dumped prior to enterting the shell.
Lucio Andrés Illanes Albornoz 368962
        -t                    Produce tarball of package build root directory and build log
Lucio Andrés Illanes Albornoz 368962
                              file for the purpose of distribution given build failure.
Lucio Andrés Illanes Albornoz a6970c
Lucio Andrés Illanes Albornoz a6970c
        <variable name>=<variable override>[ ..]
Lucio Andrés Illanes Albornoz 368962
                              Override build variable.
Lucio Andrés Illanes Albornoz a6970c
```
Lucio Andrés Illanes Albornoz a6970c
  
Lucio Andrés Illanes Albornoz a6970c
> N.B. When using ``pkgtool.sh`` on a build w/ build variables (see section [4](#4-build-variables))
Lucio Andrés Illanes Albornoz a6970c
overriden on the command line or via the environment, ensure that they are included in the
Lucio Andrés Illanes Albornoz a6970c
``pkgtool.sh`` command line, preceding the package name, or exported, respectively.
Lucio Andrés Illanes Albornoz a6970c
  
Lucio Andrés Illanes Albornoz a6970c
[Back to top](#table-of-contents)
Lucio Andrés Illanes Albornoz a6970c
Lucio Andrés Illanes Albornoz a6970c
[//]: # "}}}"
Lucio Andrés Illanes Albornoz a6970c
[//]: # "{{{ 3.5.1. -s: package build shell environment"
Lucio Andrés Illanes Albornoz a6970c
### 3.5.1. -s: package build shell environment
Lucio Andrés Illanes Albornoz a6970c
Lucio Andrés Illanes Albornoz a6970c
When ``build.sh`` is executed with the ``--dump-on-abort`` option, a subset of the
Lucio Andrés Illanes Albornoz a6970c
variables set and environment variables exported will be written to ``${BUILD_WORKDIR}/${PKG_NAME}.dump``
Lucio Andrés Illanes Albornoz a6970c
on build failure, which may subsequently be used in order to obtain a package build shell
Lucio Andrés Illanes Albornoz a6970c
environment with the ``pkgtool.sh`` script, e.g.:  
Lucio Andrés Illanes Albornoz a6970c
  
Lucio Andrés Illanes Albornoz a6970c
```
Lucio Andrés Illanes Albornoz a6970c
midipix_build@sandbox:(src/midipix_build)> $ ./pkgtool.sh -a nt64 -b debug -s mc
Lucio Andrés Illanes Albornoz a6970c
==> 2020/03/11 15:46:28 Launching shell `/usr/bin/zsh' within package environment and `/home/midipix_build/midipix/nt64/debug/tmp'.
Lucio Andrés Illanes Albornoz a6970c
==> 2020/03/11 15:46:28 Run $R to rebuild `mc'.
Lucio Andrés Illanes Albornoz a6970c
==> 2020/03/11 15:46:28 Run $RS <step> to restart the specified build step of `mc'
Lucio Andrés Illanes Albornoz a6970c
==> 2020/03/11 15:46:28 Run $D to automatically regenerate the patch for `mc'.
Lucio Andrés Illanes Albornoz 6ab687
midipix_build@sandbox:(mc-native-x86_64-nt64-midipix/obj)> $
Lucio Andrés Illanes Albornoz a6970c
```
Lucio Andrés Illanes Albornoz a6970c
  
Lucio Andrés Illanes Albornoz a6970c
If a package build shell environment is desired for a package that has either not been
Lucio Andrés Illanes Albornoz a6970c
built at all or built successfully, ``pkgshell.sh`` will attempt to rebuild the package
Lucio Andrés Illanes Albornoz a6970c
at build steps up until, by default, ``build``, and then forcibly abort the build and
Lucio Andrés Illanes Albornoz a6970c
write ``${BUILD_WORKDIR}/${PKG_NAME}.dump`` as above prior to entering the shell.  
Lucio Andrés Illanes Albornoz a6970c
  
Lucio Andrés Illanes Albornoz a6970c
Consult sections [3.2](#32-adding-a-package), [3.4](#34-patches-and-vars-files), [4](#4-build-variables),
Lucio Andrés Illanes Albornoz a6970c
[4.1](#41-build-steps), and [4.2](#42-package-variables) for further information
Lucio Andrés Illanes Albornoz a6970c
concerning the package build process.  
Lucio Andrés Illanes Albornoz a6970c
  
Lucio Andrés Illanes Albornoz a6970c
[Back to top](#table-of-contents)
Lucio Andrés Illanes Albornoz a6970c
Lucio Andrés Illanes Albornoz a6970c
[//]: # "}}}"
Lucio Andrés Illanes Albornoz a6970c
Lucio Andrés Illanes Albornoz a6970c
[//]: # "{{{ 4. Build variables"
Lucio Andrés Illanes Albornoz a6970c
## 4. Build variables
Lucio Andrés Illanes Albornoz a6970c
Lucio Andrés Illanes Albornoz a6970c
The following variables are primarily defined in ``midipix.env`` and may be
Lucio Andrés Illanes Albornoz 685e16
overriden on a per-build basis on the command-line, the environment, and/or
Lucio Andrés Illanes Albornoz 685e16
``${HOME}/midipix_build.vars``, ``${HOME}/.midipix_build.vars``, and/or
Lucio Andrés Illanes Albornoz 685e16
``../midipix_build.vars``, e.g.:
Lucio Andrés Illanes Albornoz a6970c
Lucio Andrés Illanes Albornoz a6970c
```shell
Lucio Andrés Illanes Albornoz a6970c
./build.sh -a nt64 -b release -D minipix,zipdist -P -v PREFIX_ROOT="${HOME}/midipix_tmp"
Lucio Andrés Illanes Albornoz 6bc7e5
env ARCH=nt64 BUILD_KIND=release PREFIX_ROOT="${HOME}/midipix_tmp" ./build.sh -D minipix,zipdist -P -v
Lucio Andrés Illanes Albornoz a6970c
```
Lucio Andrés Illanes Albornoz a6970c
Lucio Andrés Illanes Albornoz a6970c
| Variable name    | Default value                        | Description                                                                   |
Lucio Andrés Illanes Albornoz a6970c
| ---------------- | ------------------------------------ | ----------------------------------------------------------------------------- |
Lucio Andrés Illanes Albornoz a6970c
| ARCH             | nt64                                 | Target 32-bit (nt32) or 64-bit (nt64) architecture                            |
Lucio Andrés Illanes Albornoz a6970c
| BUILD_DLCACHEDIR | ${PREFIX_ROOT}/dlcache               | Absolute pathname to package downloads cache root directory                   |
Lucio Andrés Illanes Albornoz a6970c
| BUILD_HNAME      | $(hostname)                          | Build system hostname                                                         |
Lucio Andrés Illanes Albornoz a6970c
| BUILD_KIND       | debug                                | Build w/ debugging (debug) or release compiler flags                          |
Lucio Andrés Illanes Albornoz a6970c
| BUILD_WORKDIR    | ${PREFIX}/tmp                        | Absolute pathname to temporary package build root directory                   |
Lucio Andrés Illanes Albornoz a6970c
| PREFIX           | ${PREFIX_ROOT}/${ARCH}/${BUILD_KIND} | Absolute pathname to architecture- & build type-specific build root directory |
Lucio Andrés Illanes Albornoz a6970c
| PREFIX_CROSS     | ${PREFIX}/${DEFAULT_TARGET}          | Absolute pathname to toolchain root directory                                 |
Lucio Andrés Illanes Albornoz a6970c
| PREFIX_MINGW32   | ${PREFIX}/x86_64-w64-mingw32         | Absolute pathname to MinGW toolchain root directory                           |
Lucio Andrés Illanes Albornoz a6970c
| PREFIX_MINIPIX   | ${PREFIX}/minipix                    | Absolute pathname to minipix distribution root directory                      |
Lucio Andrés Illanes Albornoz a6970c
| PREFIX_NATIVE    | ${PREFIX}/native                     | Absolute pathname to cross-compiled packages root directory                   |
Lucio Andrés Illanes Albornoz a6970c
| PREFIX_ROOT      | ${HOME}/midipix                      | Absolute pathname to top-level directory                                      |
Lucio Andrés Illanes Albornoz a6970c
| PREFIX_RPM       | ${PREFIX}/rpm                        | Absolute pathname to package RPM archive root directory                       |
Lucio Andrés Illanes Albornoz a6970c
  
Lucio Andrés Illanes Albornoz a6970c
[Back to top](#table-of-contents)
Lucio Andrés Illanes Albornoz a6970c
Lucio Andrés Illanes Albornoz a6970c
[//]: # "}}}"
Lucio Andrés Illanes Albornoz a6970c
[//]: # "{{{ 4.1. Build steps"
Lucio Andrés Illanes Albornoz a6970c
## 4.1. Build steps
Lucio Andrés Illanes Albornoz a6970c
Lucio Andrés Illanes Albornoz a6970c
Package builds are divided up into consecutively executed build steps until
Lucio Andrés Illanes Albornoz a6970c
completion or aborted on failure unless relaxed mode is enabled by passing
Lucio Andrés Illanes Albornoz a6970c
``-R``.  
Lucio Andrés Illanes Albornoz a6970c
  
Lucio Andrés Illanes Albornoz a6970c
Each build step corresponds to a function in the corresponding ``subr/pkg_*.subr``
Lucio Andrés Illanes Albornoz a6970c
script and may be overriden entirely by a function named ``pkg_<package name>_<build step>()``
Lucio Andrés Illanes Albornoz a6970c
or composed in terms of prior and/or subsequent execution by a function named
Lucio Andrés Illanes Albornoz a6970c
``pkg_<package name>_<build step>_pre()`` and/or ``pkg_<package name>_<build step>_post()``,
Lucio Andrés Illanes Albornoz a6970c
respectively, in the package's ``vars`` file. If a function named ``pkg_<package name>_all()``
Lucio Andrés Illanes Albornoz a6970c
exists, it will override all build steps.  
Lucio Andrés Illanes Albornoz a6970c
  
Lucio Andrés Illanes Albornoz a6970c
Build step status is tracked on a per-package basis by state files beneath
Lucio Andrés Illanes Albornoz a6970c
``${BUILD_WORKDIR}`` following the format ``.<package name>.<build step>``;
Lucio Andrés Illanes Albornoz a6970c
package build completion corresponds to the pseudo-build step ``finish``.
Lucio Andrés Illanes Albornoz a6970c
Lucio Andrés Illanes Albornoz 8a4e16
| Name                | Description                                                                                                                                                                                                                                                                              |
Lucio Andrés Illanes Albornoz 8a4e16
| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------                                                                                                    |
Lucio Andrés Illanes Albornoz 8a4e16
| fetch_download      | Download package archive & verify w/ SHA-256 message digest and/or clone Git repository/ies                                                                                                                                                                                              |
Lucio Andrés Illanes Albornoz 8a4e16
| fetch_extract       | Extract package archive, if any                                                                                                                                                                                                                                                          |
Lucio Andrés Illanes Albornoz 8a4e16
| configure_patch_pre | Apply ``chainport`` patches and/or patches beneath ``patches/`` prior to (GNU autotools or similar) configuration                                                                                                                                                                        |
Lucio Andrés Illanes Albornoz 8a4e16
| configure_autotools | Bootstrap (GNU autools or similar) environment, and install ``config.sub`` and ``config.cache``                                                                                                                                                                                          |
Lucio Andrés Illanes Albornoz 8a4e16
| configure_patch     | Apply patches beneath ``patches/`` and/or set in ``${PKG_PATCHES_EXTRA}`` after (GNU autotools or similar) configuration                                                                                                                                                                 |
Lucio Andrés Illanes Albornoz 8a4e16
| configure           | Perform package (GNU autools or similar) configuration w/ configuration-time set of environment variables                                                                                                                                                                                |
Lucio Andrés Illanes Albornoz 8a4e16
| build               | Call ``make(1)`` w/ build-time set of make variables                                                                                                                                                                                                                                     |
Lucio Andrés Illanes Albornoz 8a4e16
| install_subdirs     | Create default directory hierarchy in ``${PKG_DESTDIR}``, optionally amended w/ ``${PKG_INSTALL_FILES_DESTDIR_EXTRA}``                                                                                                                                                                   |
Lucio Andrés Illanes Albornoz 8a4e16
| install_make        | Call ``make(1)`` w/ ``${PKG_INSTALL_TARGET}`` (defaults to ``install``) and installation-time set of make variables                                                                                                                                                                      |
Lucio Andrés Illanes Albornoz 75bb81
| install_files       | Install ``${PKG_INSTALL_FILES}``, fix directory and file mode bits within ``${PKG_DESTDIR}`` and optionally ``${PKG_DESTDIR_HOST}``, ``pkgconf(1)`` package files, and/or stripped binaries within ``${PKG_DESTDIR}``                                                                    |
Lucio Andrés Illanes Albornoz 8a4e16
| install_libs        | Purge libtool ``.la`` files and install shared objects within ``${PKG_DESTDIR}`` w/ ``perk`` and corresponding symbolic links                                                                                                                                                            |
Lucio Andrés Illanes Albornoz 75bb81
| install             | Install into ``${PKG_PREFIX}``, and optionally ``${PKG_DESTDIR_HOST}`` into ``${PREFIX}``, under mutex, and add package to ``${PREFIX}/pkglist.${PKG_BUILD_TYPE}`` (unless inhibited)                                                                                                    |
Lucio Andrés Illanes Albornoz 8a4e16
| install_rpm         | Build package RPM w/ auto-generated specifiation file based on ``etc/package.spec`` beneath ``${PREFIX_RPM}``                                                                                                                                                                            |
Lucio Andrés Illanes Albornoz 75bb81
| clean               | Clean ``${PKG_BUILD_DIR}`` and/or ``${PKG_DESTDIR}`` and/or ``${PKG_DESTDIR_HOST}`` and/or ``${PKG_BASE_DIR}/${PKG_SUBDIR}`` as per ``-C build,dest,src``, resp., if any                                                                                                                 |
Lucio Andrés Illanes Albornoz a6970c
  
Lucio Andrés Illanes Albornoz a6970c
[Back to top](#table-of-contents)
Lucio Andrés Illanes Albornoz a6970c
Lucio Andrés Illanes Albornoz a6970c
[//]: # "}}}"
Lucio Andrés Illanes Albornoz a6970c
[//]: # "{{{ 4.2. Package variables"
Lucio Andrés Illanes Albornoz a6970c
## 4.2. Package variables
Lucio Andrés Illanes Albornoz a6970c
Lucio Andrés Illanes Albornoz a6970c
The following variables are package-specific and receive their value from either
Lucio Andrés Illanes Albornoz a6970c
top-level defaults defined in ``midipix.env``, build group-specific defaults
Lucio Andrés Illanes Albornoz a6970c
from the build group the package pertains to and defined in its corresponding
Lucio Andrés Illanes Albornoz a6970c
file beneath ``groups/``, or package-specific overrides defined either in the
Lucio Andrés Illanes Albornoz a6970c
latter and/or in its corresponding file beneath ``vars/``, with one of the following
Lucio Andrés Illanes Albornoz a6970c
prefixes:
Lucio Andrés Illanes Albornoz a6970c
Lucio Andrés Illanes Albornoz a6970c
| Variable name prefix				|
Lucio Andrés Illanes Albornoz a6970c
| ---------------------------------------------	|
Lucio Andrés Illanes Albornoz a6970c
| DEFAULT					|
Lucio Andrés Illanes Albornoz a6970c
| DEFAULT_``${BUILD_TYPE}``			|
Lucio Andrés Illanes Albornoz a6970c
| DEFAULT_``${GROUP_NAME}``			|
Lucio Andrés Illanes Albornoz a6970c
| ``${GROUP_NAME}``				|
Lucio Andrés Illanes Albornoz a6970c
| PKG_``${INHERIT_FROM}``			|
Lucio Andrés Illanes Albornoz a6970c
| PKG_``${INHERIT_FROM}``_``${BUILD_KIND}``	|
Lucio Andrés Illanes Albornoz a6970c
| PKG_``${NAME}``				|
Lucio Andrés Illanes Albornoz a6970c
| PKG_``${NAME}``_``${BUILD_KIND}``		|
Lucio Andrés Illanes Albornoz a6970c
Lucio Andrés Illanes Albornoz a6970c
Additionally, overrides may be specified on a per-build basis on the command-
Lucio Andrés Illanes Albornoz 685e16
line, with each variable prefixed w/ ``PKG_``, e.g.:
Lucio Andrés Illanes Albornoz a6970c
``./build.sh [ ... ] PKG_ZSH_CC="/usr/bin/clang"``.  
Lucio Andrés Illanes Albornoz a6970c
  
Lucio Andrés Illanes Albornoz a6970c
The minimum set of package variables that must be provided is ``SHA256SUM, URL,
Lucio Andrés Illanes Albornoz a6970c
VERSION`` and/or ``URLS_GIT``, respectively.
Lucio Andrés Illanes Albornoz a6970c
Lucio Andrés Illanes Albornoz a6970c
| Package variable name       | Description                                                                                                                                 |
Lucio Andrés Illanes Albornoz a6970c
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
Lucio Andrés Illanes Albornoz a6970c
| AR                          | Command- or pathname of toolchain library archive editor ``ar(1)``                                                                          |
Lucio Andrés Illanes Albornoz a6970c
| BASE_DIR                    | Absolute pathname to package build root directory beneath ``${BUILD_WORKDIR}``                                                              |
Lucio Andrés Illanes Albornoz a6970c
| BUILD_DIR                   | Directory name of package build directory beneath ``${PKG_BASE_DIR}``                                                                       |
Lucio Andrés Illanes Albornoz a6970c
| BUILD_STEPS_DISABLE         | List of build steps to disable during package build                                                                                         |
Lucio Andrés Illanes Albornoz 8a4e16
| BUILD_TYPE                  | Cross-compiled toolchain (``cross``,) host (``host``,) or cross-compiled package (``native``) build type                                    |
Lucio Andrés Illanes Albornoz a6970c
| CC                          | Command- or pathname of toolchain C compiler ``cc(1)``                                                                                      |
Lucio Andrés Illanes Albornoz 522027
| CFLAGS_BUILD                | C compiler flags during package ``make(1)``  build                                                                                          |
Lucio Andrés Illanes Albornoz a6970c
| CFLAGS_BUILD_EXTRA          | Additional C compiler flags during package ``make(1)``  build                                                                               |
Lucio Andrés Illanes Albornoz a6970c
| CFLAGS_CONFIGURE            | C compiler flags during package (GNU autotools or similar) configuration                                                                    |
Lucio Andrés Illanes Albornoz a6970c
| CFLAGS_CONFIGURE_EXTRA      | Additional C compiler flags during package (GNU autotools or similar) configuration                                                         |
Lucio Andrés Illanes Albornoz a6970c
| CONFIG_CACHE                | List of GNU autotools configuration cache variables                                                                                         |
Lucio Andrés Illanes Albornoz a6970c
| CONFIG_CACHE_EXTRA          | Additional list of GNU autotools configuration cache variables                                                                              |
Lucio Andrés Illanes Albornoz a6970c
| CONFIG_CACHE_LOCAL          | Additional list of GNU autotools configuration cache variables                                                                              |
Lucio Andrés Illanes Albornoz a6970c
| CONFIGURE                   | Command- or pathname to package (GNU autotools or similar) configuration script                                                             |
Lucio Andrés Illanes Albornoz a6970c
| CONFIGURE_ARGS              | List of arguments to package (GNU autotools or similar) configuration script                                                                |
Lucio Andrés Illanes Albornoz a6970c
| CONFIGURE_ARGS_EXTRA        | Additional list of arguments to package (GNU autotools or similar) configuration script                                                     |
Lucio Andrés Illanes Albornoz a6970c
| CXX                         | Command- or pathname of toolchain C++ compiler ``c++(1)``                                                                                   |
Lucio Andrés Illanes Albornoz a6970c
| CXXFLAGS_CONFIGURE          | List of C++ compiler flags during package (GNU autotools or similar) configuration                                                          |
Lucio Andrés Illanes Albornoz a6970c
| CXXFLAGS_CONFIGURE_EXTRA    | Additional list of C++ compiler flags during package (GNU autotools or similar) configuration                                               |
Lucio Andrés Illanes Albornoz a6970c
| DEPENDS                     | List of package-package dependencies                                                                                                        |
Lucio Andrés Illanes Albornoz a6970c
| DESTDIR                     | Directory name of package installation destination directory beneath ``${PKG_BASE_DIR}``                                                    |
Lucio Andrés Illanes Albornoz 8a4e16
| DESTDIR_HOST                | Directory name of optional host package installation destination directory beneath ``${PKG_BASE_DIR}``                                      |
Lucio Andrés Illanes Albornoz a6970c
| DISABLED                    | Disable package                                                                                                                             |
Lucio Andrés Illanes Albornoz a6970c
| ENV_VARS_EXTRA              | List of double colon-separated environment variable equality sign-separated name-value pairs to set during package build                    |
Lucio Andrés Illanes Albornoz a6970c
| FNAME                       | Filename of package archive file                                                                                                            |
Lucio Andrés Illanes Albornoz a6970c
| FORCE_AUTORECONF            | Forcibly run ``autoreconf -fiv`` prior to package (GNU autotools or similar) configuration                                                  |
Lucio Andrés Illanes Albornoz a6970c
| GITROOT                     | midipix packages Git URL prefix                                                                                                             |
Lucio Andrés Illanes Albornoz a6970c
| INHERIT_FROM                | Inherit variables from named package                                                                                                        |
Lucio Andrés Illanes Albornoz a6970c
| INSTALL_FILES               | Whitespace-separated list of files to manually install into the package installation destination directory beneath ``${PKG_BASE_DIR}``      |
Lucio Andrés Illanes Albornoz a6970c
| INSTALL_FILES_DESTDIR       | Whitespace-separated list of files to initialise the package installation destination directory beneath ``${PKG_BASE_DIR}`` with            |
Lucio Andrés Illanes Albornoz a6970c
| INSTALL_FILES_DESTDIR_EXTRA | Additional whitespace-separated list of files to initialise the package installation destination directory beneath ``${PKG_BASE_DIR}`` with |
Lucio Andrés Illanes Albornoz a6970c
| INSTALL_TARGET              | Name of package build ``make(1)`` installation target                                                                                       |
Lucio Andrés Illanes Albornoz a6970c
| INSTALL_TARGET_EXTRA        | Additional name of package build ``make(1)`` installation target                                                                            |
Lucio Andrés Illanes Albornoz a6970c
| IN_TREE                     | Build package in-tree within ``${PKG_SUBDIR}``                                                                                              |
Lucio Andrés Illanes Albornoz a6970c
| LDFLAGS_BUILD_EXTRA         | Additional linker flags during package ``make(1)``  build                                                                                   |
Lucio Andrés Illanes Albornoz a6970c
| LDFLAGS_CONFIGURE           | Linker flags during package (GNU autotools or similar) configuration                                                                        |
Lucio Andrés Illanes Albornoz a6970c
| LDFLAGS_CONFIGURE_EXTRA     | Additional linker flags during package (GNU autotools or similar) configuration                                                             |
Lucio Andrés Illanes Albornoz a6970c
| LIBTOOL                     | Command- or pathname of ``libtool(1)`` (defaults to ``slibtool``)                                                                           |
Lucio Andrés Illanes Albornoz a6970c
| MAKE                        | Command line of ``make(1)``                                                                                                                 |
Lucio Andrés Illanes Albornoz 522027
| MAKE_SUBDIRS                | List of ``make(1)`` subdirectories to exclusively build                                                                                     |
Lucio Andrés Illanes Albornoz a6970c
| MAKEFLAGS_BUILD             | List of ``make(1)`` flags during package ``make(1)``  build                                                                                 |
Lucio Andrés Illanes Albornoz a6970c
| MAKEFLAGS_BUILD_EXTRA       | Additional list of ``make(1)`` flags during package ``make(1)``  build                                                                      |
Lucio Andrés Illanes Albornoz a6970c
| MAKEFLAGS_INSTALL           | List of ``make(1)`` flags during package ``make(1)``  installation                                                                          |
Lucio Andrés Illanes Albornoz a6970c
| MAKEFLAGS_INSTALL_EXTRA     | Additional list of ``make(1)`` flags during package ``make(1)``  installation                                                               |
Lucio Andrés Illanes Albornoz a6970c
| MAKEFLAGS_VERBOSITY         | Variable-value pair to pass to ``make(1)`` in order to force echo-back of command lines prior to execution                                  |
Lucio Andrés Illanes Albornoz a6970c
| MAKE_INSTALL_VNAME          | Variable name of ``make(1)`` installation destination directory variable during package ``make(1)``  installation                           |
Lucio Andrés Illanes Albornoz 368962
| MIRRORS                     | List of package archive mirror base URLs to attempt downloading from; cf. ``pkgtool.sh -m <dname>``                                         |
Lucio Andrés Illanes Albornoz 368962
| MIRRORS_GIT                 | List of package Git repository mirror base URLs to attempt cloning from; cf. ``pkgtool.sh -m <dname>``                                      |
Lucio Andrés Illanes Albornoz a6970c
| NO_CLEAN                    | Inhibit cleaning of package build directory beneath ``${PKG_BASE_DIR}`` pre-finish                                                          |
Lucio Andrés Illanes Albornoz a6970c
| NO_CLEAN_BASE_DIR           | Inhibit cleaning of package build root directory beneath ``${BUILD_WORKDIR}``                                                               |
Lucio Andrés Illanes Albornoz a6970c
| NO_LOG_VARS                 | Inhibit logging of build & package variables pre-package build                                                                              |
Lucio Andrés Illanes Albornoz a6970c
| PATCHES_EXTRA               | Additional list of patches to apply                                                                                                         |
Lucio Andrés Illanes Albornoz a6970c
| PKG_CONFIG                  | Command- or pathname of ``pkg-config(1)``                                                                                                   |
Lucio Andrés Illanes Albornoz a6970c
| PKG_CONFIG_LIBDIR           | ``pkg-config(1)`` search directory                                                                                                          |
Lucio Andrés Illanes Albornoz a6970c
| PKGLIST_DISABLE             | Inhibit inclusion into ``${PREFIX}/pkglist.${PKG_BUILD_TYPE}``                                                                              |
Lucio Andrés Illanes Albornoz a6970c
| PREFIX                      | Absolute pathname of top-level installation directory and package search path                                                               |
Lucio Andrés Illanes Albornoz a6970c
| PYTHON                      | Command- or pathname of Python                                                                                                              |
Lucio Andrés Illanes Albornoz a6970c
| RANLIB                      | Command- or pathname of toolchain library archive index generator ``ranlib(1)``                                                             |
Lucio Andrés Illanes Albornoz a6970c
| RPM_DISABLE                 | Inhibit creation of RPM archive                                                                                                             |
Lucio Andrés Illanes Albornoz a6970c
| SHA256SUM                   | SHA-256 message digest of package archive                                                                                                   |
Lucio Andrés Illanes Albornoz a6970c
| SUBDIR                      | Name of extracted archive or git-{clone,pull}(1)'d directory                                                                                |
Lucio Andrés Illanes Albornoz a6970c
| TARGET                      | Dash-separated {build,host,target} triplet                                                                                                  |
Lucio Andrés Illanes Albornoz 512248
| URL                         | URL to package archive, optionally appended with whitespace-separated list of alternative URLs                                              |
Lucio Andrés Illanes Albornoz a6970c
| URLS_GIT                    | List of package Git URL(s) (``*name*=*URL*@*branch*``)                                                                                      |
Lucio Andrés Illanes Albornoz a6970c
| VERSION                     | Package version                                                                                                                             |
Lucio Andrés Illanes Albornoz a6970c
  
Lucio Andrés Illanes Albornoz a6970c
[Back to top](#table-of-contents)
Lucio Andrés Illanes Albornoz a6970c
Lucio Andrés Illanes Albornoz a6970c
[//]: # "}}}"
Lucio Andrés Illanes Albornoz a6970c
Lucio Andrés Illanes Albornoz a6970c
[//]: # "{{{ 5. References"
Lucio Andrés Illanes Albornoz a6970c
## 5. References
Lucio Andrés Illanes Albornoz a6970c
Lucio Andrés Illanes Albornoz a6970c
* ``Sun, 25 Apr 2016 09:04:08 +0000 [1]`` musl FAQ  
Lucio Andrés Illanes Albornoz a6970c
* ``Wed, 04 Mar 2020 13:36:19 +0000 [2]`` midipix - what is midipix, and how is it different?  
Lucio Andrés Illanes Albornoz 6bc7e5
* ``Wed, 29 Apr 2020 23:33:34 +0100 [3]`` User Rights Assignment (Windows 10) - Windows security | Microsoft Docs  
Lucio Andrés Illanes Albornoz 6bc7e5
* ``Wed, 29 Apr 2020 23:33:50 +0100 [4]`` Windows Vista Application Development Requirements for User Account Control Compatibility | Microsoft Docs  
Lucio Andrés Illanes Albornoz a6970c
  
Lucio Andrés Illanes Albornoz a6970c
[Back to top](#table-of-contents)
Lucio Andrés Illanes Albornoz a6970c
Lucio Andrés Illanes Albornoz a6970c
[//]: # "}}}"
Lucio Andrés Illanes Albornoz a6970c
  
Lucio Andrés Illanes Albornoz a6970c
[modeline]: # ( vim: set tw=0: )