midipix / build / midipix_build

Forked from build/midipix_build 4 years ago
Clone

Blame etc/README.md

Lucio Andrés Illanes Albornoz 6d9a3c
> N.B. If you're interested in building Midipix using this script, please join
Lucio Andrés Illanes Albornoz 6d9a3c
the project's IRC channel #midipix on Freenode and ask for the address of the
Lucio Andrés Illanes Albornoz 6d9a3c
internal repositories required in order to build Midipix.
Lucio Andrés Illanes Albornoz 6d9a3c

Lucio Andrés Illanes Albornoz 6d9a3c
[//]: # "{{{ Table of contents"
Lucio Andrés Illanes Albornoz 4a70bb
# Table of Contents
Lucio Andrés Illanes Albornoz 6d9a3c

Lucio Andrés Illanes Albornoz 6d9a3c
1. [What is midipix, and how is it different?](#1-what-is-midipix-and-how-is-it-different)  
Lucio Andrés Illanes Albornoz 6d9a3c
2. [Building a midipix distribution](#2-building-a-midipix-distribution)  
Lucio Andrés Illanes Albornoz 23f3c2
	2.1. [Build-time dependencies](#21-build-time-dependencies)  
Lucio Andrés Illanes Albornoz 23f3c2
		2.1.1. [Alpine-specific notate bene](#211-alpine-specific-notate-bene)  
Lucio Andrés Illanes Albornoz 23f3c2
	2.2. [Deployment](#22-deployment)  
Lucio Andrés Illanes Albornoz 23f3c2
	2.3. [System requirements](#23-system-requirements)  
Lucio Andrés Illanes Albornoz 6d9a3c
3. [Common tasks](#3-common-tasks)  
Lucio Andrés Illanes Albornoz 23f3c2
	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 5b1e55
	3.2. [Adding a package](#32-adding-a-package)  
Lucio Andrés Illanes Albornoz 5b1e55
	3.3. [Addressing build failure](#33-addressing-build-failure)  
Lucio Andrés Illanes Albornoz 5b1e55
	3.4. [Patches and ``vars`` files](#34-patches-and-vars-files)  
Lucio Andrés Illanes Albornoz f3459e
	3.5. [``pkgtool.sh``](#35-pkgtoolsh)  
Lucio Andrés Illanes Albornoz 60fba6
		3.5.1. [``-s``: package build shell environment](#351-s-package-build-shell-environment)  
Lucio Andrés Illanes Albornoz 23f3c2
4. [Build variables](#4-build-variables)  
Lucio Andrés Illanes Albornoz 5b1e55
	4.1. [Build steps](#41-build-steps)  
Lucio Andrés Illanes Albornoz 5b1e55
	4.2. [Package variables](#42-package-variables)  
Lucio Andrés Illanes Albornoz 23f3c2
5. [References](#5-references)  
Lucio Andrés Illanes Albornoz 6d9a3c

Lucio Andrés Illanes Albornoz 6d9a3c
[//]: "}}}"
Lucio Andrés Illanes Albornoz 6d9a3c

Lucio Andrés Illanes Albornoz 6d9a3c
[//]: # "{{{ 1. What is midipix, and how is it different?"
Lucio Andrés Illanes Albornoz 23f3c2
## 1. What is midipix, and how is it different?
Lucio Andrés Illanes Albornoz 6d9a3c

Lucio Andrés Illanes Albornoz 2a4027
midipix is a development environment that lets you create programs
Lucio Andrés Illanes Albornoz 2a4027
for Windows using the standard C and POSIX APIs. No compromises made,
Lucio Andrés Illanes Albornoz 2a4027
no shortcuts taken.  
Lucio Andrés Illanes Albornoz 2a4027
  
Lucio Andrés Illanes Albornoz 2a4027
If you are interested in cross-platform programming that reclaims
Lucio Andrés Illanes Albornoz 2a4027
the notion of write once, compile everywhere; if you believe that the
Lucio Andrés Illanes Albornoz 2a4027
'standard' in the C Standard Library should not be a null signifier;
Lucio Andrés Illanes Albornoz 2a4027
and if you like cooking your code without #ifdef hell and low-level
Lucio Andrés Illanes Albornoz 2a4027
minutiae, then this page is for you.  
Lucio Andrés Illanes Albornoz 2a4027
  
Lucio Andrés Illanes Albornoz 6d9a3c
midipix makes cross-platform programming better, simpler and faster,
Lucio Andrés Illanes Albornoz 2a4027
specifically by bringing a modern, conforming C Runtime Library to the
Lucio Andrés Illanes Albornoz 2a4027
Windows platform. While the idea itself is not new, the approach taken
Lucio Andrés Illanes Albornoz 2a4027
in midipix to code portability is radically different from that found
Lucio Andrés Illanes Albornoz 2a4027
in other projects.  
Lucio Andrés Illanes Albornoz 2a4027
  
Lucio Andrés Illanes Albornoz 05a64f
*(reproduced from [[2](https://midipix.org/#sec-midipix)])*
Lucio Andrés Illanes Albornoz 6d9a3c
  
Lucio Andrés Illanes Albornoz 6d9a3c
[Back to top](#table-of-contents)
Lucio Andrés Illanes Albornoz 6d9a3c

Lucio Andrés Illanes Albornoz 6d9a3c
[//]: "}}}"
Lucio Andrés Illanes Albornoz 6d9a3c

Lucio Andrés Illanes Albornoz 6d9a3c
[//]: # "{{{ 2. Building a midipix distribution"
Lucio Andrés Illanes Albornoz 6d9a3c
## 2. Building a midipix distribution
Lucio Andrés Illanes Albornoz 6d9a3c

Lucio Andrés Illanes Albornoz 6d9a3c
A Midipix distribution consists of the following:
Lucio Andrés Illanes Albornoz 6d9a3c
* the native Midipix toolchain, consisting of perk, gcc, its dependencies,
Lucio Andrés Illanes Albornoz 6d9a3c
  and binutils,
Lucio Andrés Illanes Albornoz 05a64f
* musl, a lightweight, fast, simple, and free libc[[1](https://www.musl-libc.org/faq.html)] used by Midipix,
Lucio Andrés Illanes Albornoz 6d9a3c
* the Midipix runtime components that bridge the gap between the libc and the
Lucio Andrés Illanes Albornoz 6d9a3c
  executive subsystems of all Windows NT-derived Windows OS starting with and
Lucio Andrés Illanes Albornoz 6d9a3c
  including Windows XP, and
Lucio Andrés Illanes Albornoz 6d9a3c
* a steadily increasing number of 3rd party open source packages, as expected in
Lucio Andrés Illanes Albornoz 6d9a3c
  any modern POSIX-compliant \*nix environment, including GNU coreutils, shells,
Lucio Andrés Illanes Albornoz 6d9a3c
  libraries such as ncurses, libressl, as well as Perl and Python.
Lucio Andrés Illanes Albornoz 6d9a3c

Lucio Andrés Illanes Albornoz 23f3c2
Install the build-time dependencies listed in section [2.1](#21-build-time-dependencies),
Lucio Andrés Illanes Albornoz 6d9a3c
clone this repository, and run the following command line:
Lucio Andrés Illanes Albornoz 6d9a3c

Lucio Andrés Illanes Albornoz 6d9a3c
```shell
Lucio Andrés Illanes Albornoz ed7b28
./build.sh -a nt64 -b release -D zipdist -P -v
Lucio Andrés Illanes Albornoz 6d9a3c
```
Lucio Andrés Illanes Albornoz 6d9a3c

Lucio Andrés Illanes Albornoz 6d9a3c
By default, the build will take place within ``${HOME}/midipix/nt64/release``
Lucio Andrés Illanes Albornoz 6d9a3c
and package archive files and/or Git repositores will be downloaded into
Lucio Andrés Illanes Albornoz 5b1e55
``${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 2a4027
for the list of available build variables and how to override them.  
Lucio Andrés Illanes Albornoz 5b1e55
Parallelisation is enabled by the above command line for both packages that can
Lucio Andrés Illanes Albornoz 5b1e55
be built independently of each other and ``make(1)`` via ``-j``, limited to the
Lucio Andrés Illanes Albornoz 5b1e55
amount of logical processors on the build host divided by two (2).
Lucio Andrés Illanes Albornoz 6d9a3c
  
Lucio Andrés Illanes Albornoz 6d9a3c
[Back to top](#table-of-contents)
Lucio Andrés Illanes Albornoz 6d9a3c

Lucio Andrés Illanes Albornoz 6d9a3c
[//]: # "}}}"
Lucio Andrés Illanes Albornoz 6d9a3c
[//]: # "{{{ 2.1. Build-time dependencies"
Lucio Andrés Illanes Albornoz 6d9a3c
### 2.1. Build-time dependencies
Lucio Andrés Illanes Albornoz 6d9a3c

Lucio Andrés Illanes Albornoz 60fba6
* **Alpine Linux**: awk binutils bzip2 cmake coreutils curl findutils g++ gcc
Lucio Andrés Illanes Albornoz 6d9a3c
		    git grep gzip libc-dev linux-headers lzip make musl-dev
Lucio Andrés Illanes Albornoz 6d9a3c
		    net-tools patch perl perl-xml-parser procps sed tar
Lucio Andrés Illanes Albornoz 6d9a3c
		    util-linux wget xz zip
Lucio Andrés Illanes Albornoz 60fba6
* **Debian/-derived Linux**: awk binutils bzip2 clzip cmake coreutils curl findutils
Lucio Andrés Illanes Albornoz 60fba6
			     g++ gcc git grep gzip hostname libc6-dev libxml-parser-perl
Lucio Andrés Illanes Albornoz 60fba6
			     lzma make patch perl procps sed tar util-linux wget xz-utils zip
Lucio Andrés Illanes Albornoz 6d9a3c
* **OpenSUSE Linux**: binutils bzip2 cmake coreutils curl findutils gawk gcc
Lucio Andrés Illanes Albornoz 6d9a3c
		      gcc-c++ git grep gzip hostname linux-glibc-devel lzip make
Lucio Andrés Illanes Albornoz 6d9a3c
		      patch perl perl-XML-Parser procps sed tar util-linux wget
Lucio Andrés Illanes Albornoz 6d9a3c
		      xz zip
Lucio Andrés Illanes Albornoz 60fba6
  
Lucio Andrés Illanes Albornoz 6d9a3c
> N.B. Busybox is not supported.
Lucio Andrés Illanes Albornoz 6d9a3c
  
Lucio Andrés Illanes Albornoz 6d9a3c
[Back to top](#table-of-contents)
Lucio Andrés Illanes Albornoz 6d9a3c

Lucio Andrés Illanes Albornoz 6d9a3c
[//]: # "}}}"
Lucio Andrés Illanes Albornoz 6d9a3c
[//]: # "{{{ 2.1.1. Alpine-specific notate bene"
Lucio Andrés Illanes Albornoz 6d9a3c
#### 2.1.1. Alpine-specific notate bene
Lucio Andrés Illanes Albornoz 6d9a3c

Lucio Andrés Illanes Albornoz 6d9a3c
Some packages (*coreutils*, *grep*, and *tar*, among others) override Alpine's
Lucio Andrés Illanes Albornoz 6d9a3c
BusyBox utilities of the same name, as the latter are either non-conformant or
Lucio Andrés Illanes Albornoz 6d9a3c
defective.
Lucio Andrés Illanes Albornoz 6d9a3c
  
Lucio Andrés Illanes Albornoz 6d9a3c
[Back to top](#table-of-contents)
Lucio Andrés Illanes Albornoz 6d9a3c

Lucio Andrés Illanes Albornoz 6d9a3c
[//]: # "}}}"
Lucio Andrés Illanes Albornoz 6d9a3c
[//]: # "{{{ 2.2. Deployment"
Lucio Andrés Illanes Albornoz 6d9a3c
### 2.2. Deployment
Lucio Andrés Illanes Albornoz 6d9a3c

Lucio Andrés Illanes Albornoz 6d9a3c
On successful completion of the build, a ZIP archive containing the Midipix
Lucio Andrés Illanes Albornoz 5b1e55
distribution will be created inside ``${PREFIX}`` (see section [4](#4-build-variables).)
Lucio Andrés Illanes Albornoz 60fba6
Create a directory on the target machine and extract the contents of the distribution
Lucio Andrés Illanes Albornoz 60fba6
ZIP archive into it, run ``bash.bat``, and then ``/install.sh`` inside the resulting
Lucio Andrés Illanes Albornoz 60fba6
self-contained Midipix installation shell window.  
Lucio Andrés Illanes Albornoz e03059
  
Lucio Andrés Illanes Albornoz ed7b28
> N.B. The pathname of the target directory containing ``bash.bat`` and all other
Lucio Andrés Illanes Albornoz 60fba6
distribution files must not contain whitespaces.  
Lucio Andrés Illanes Albornoz 60fba6
  
Lucio Andrés Illanes Albornoz 60fba6
> N.B. The Midipix installer defaults to ``/dev/fs/c/midipix (C:\midipix)``. If left
Lucio Andrés Illanes Albornoz 60fba6
unchanged, the distribution ZIP archive must not be extracted into a directory of the
Lucio Andrés Illanes Albornoz 60fba6
same pathname.  
Lucio Andrés Illanes Albornoz 6d9a3c
  
Lucio Andrés Illanes Albornoz 6d9a3c
[Back to top](#table-of-contents)
Lucio Andrés Illanes Albornoz 6d9a3c

Lucio Andrés Illanes Albornoz 6d9a3c
[//]: # "}}}"
Lucio Andrés Illanes Albornoz 6d9a3c
[//]: # "{{{ 2.3. System requirements"
Lucio Andrés Illanes Albornoz 6d9a3c
### 2.3. System requirements
Lucio Andrés Illanes Albornoz 6d9a3c

Lucio Andrés Illanes Albornoz 6d9a3c
The following system requirements are assessed on build hosts equipped with the
Lucio Andrés Illanes Albornoz 6d9a3c
following hardware at minimum:
Lucio Andrés Illanes Albornoz 6d9a3c
* Intel(R) Xeon(R) CPU W3520 @ 2.67GHz (8 cores)
Lucio Andrés Illanes Albornoz 6d9a3c
* 7200 RPM SATA 3.1 HDD
Lucio Andrés Illanes Albornoz 6d9a3c
* 6 GB RAM
Lucio Andrés Illanes Albornoz 6d9a3c

Lucio Andrés Illanes Albornoz 5b1e55
| Target architecture | Build type | Distribution kinds selected | Average build time | Disk space required | Peak RAM usage |
Lucio Andrés Illanes Albornoz 5b1e55
| ------------------- | ---------- | --------------------------- | ------------------ | ------------------- | -------------- |
Lucio Andrés Illanes Albornoz 5b1e55
| nt64                | debug      | (none)                      | 2 hours            | 57.62 GB            | 3.55 GB        |
Lucio Andrés Illanes Albornoz 5b1e55
| nt64                | release    | (none)                      | 1 hours 45 minutes | 36.51 GB            | 3.21 GB        |
Lucio Andrés Illanes Albornoz 6d9a3c

Lucio Andrés Illanes Albornoz 6d9a3c
Package archive files and/or Git repositories additionally consume at least
Lucio Andrés Illanes Albornoz 5b1e55
1.82 GB.
Lucio Andrés Illanes Albornoz 6d9a3c

Lucio Andrés Illanes Albornoz 5b1e55
*(last update: Thu, 05 Mar 2020 09:25:41 +0000)*
Lucio Andrés Illanes Albornoz 6d9a3c
  
Lucio Andrés Illanes Albornoz 6d9a3c
[Back to top](#table-of-contents)
Lucio Andrés Illanes Albornoz 6d9a3c

Lucio Andrés Illanes Albornoz 6d9a3c
[//]: # "}}}"
Lucio Andrés Illanes Albornoz 6d9a3c

Lucio Andrés Illanes Albornoz 6d9a3c
[//]: # "{{{ 3. Common tasks"
Lucio Andrés Illanes Albornoz 6d9a3c
## 3. Common tasks
Lucio Andrés Illanes Albornoz 6d9a3c

Lucio Andrés Illanes Albornoz b6a9a1
Rebuild set of packages in isolation:
Lucio Andrés Illanes Albornoz 6d9a3c
```shell
Lucio Andrés Illanes Albornoz 6d9a3c
./build.sh [ ... ] -r mc,zsh
Lucio Andrés Illanes Albornoz b6a9a1
```
Lucio Andrés Illanes Albornoz b6a9a1
  
Lucio Andrés Illanes Albornoz b6a9a1
Rebuild set of packages along w/ their dependencies, if any, as needed, or forcibly,
Lucio Andrés Illanes Albornoz b6a9a1
respectively:
Lucio Andrés Illanes Albornoz b6a9a1
```shell
Lucio Andrés Illanes Albornoz 6d9a3c
./build.sh [ ... ] -r \*mc,zsh
Lucio Andrés Illanes Albornoz 6d9a3c
./build.sh [ ... ] -r \*\*mc,zsh
Lucio Andrés Illanes Albornoz 6d9a3c
```
Lucio Andrés Illanes Albornoz b6a9a1
  
Lucio Andrés Illanes Albornoz b6a9a1
Forcibly rebuild all reverse dependencies of a set of packages:
Lucio Andrés Illanes Albornoz b6a9a1
```shell
Lucio Andrés Illanes Albornoz b6a9a1
./build.sh [ ... ] -r \*\*\*glib,libflac
Lucio Andrés Illanes Albornoz b6a9a1
```
Lucio Andrés Illanes Albornoz b6a9a1
  
Lucio Andrés Illanes Albornoz 6d9a3c
Restart the ``configure``, ``build``, and ``install`` steps of the ``coreutils``
Lucio Andrés Illanes Albornoz ed7b28
package:
Lucio Andrés Illanes Albornoz 6d9a3c
```shell
Lucio Andrés Illanes Albornoz 6d9a3c
./build.sh -r coreutils:configure,build,install
Lucio Andrés Illanes Albornoz 6d9a3c
```
Lucio Andrés Illanes Albornoz b6a9a1
  
Lucio Andrés Illanes Albornoz ed7b28
Rebuild entire build groups including or excluding group dependencies, respectively:
Lucio Andrés Illanes Albornoz 6d9a3c
```shell
Lucio Andrés Illanes Albornoz 6d9a3c
./build.sh [ ... ] -r ALL native_runtime
Lucio Andrés Illanes Albornoz b6a9a1
./build.sh [ ... ] -r ALL =native_runtime
Lucio Andrés Illanes Albornoz 6d9a3c
```
Lucio Andrés Illanes Albornoz 6d9a3c
  
Lucio Andrés Illanes Albornoz 6d9a3c
[Back to top](#table-of-contents)
Lucio Andrés Illanes Albornoz 6d9a3c

Lucio Andrés Illanes Albornoz 6d9a3c
[//]: # "}}}"
Lucio Andrés Illanes Albornoz 6d9a3c
[//]: # "{{{ 3.1. Fault-tolerant & highly optimised 3D laser show-equipped usage screen"
Lucio Andrés Illanes Albornoz 6d9a3c
## 3.1. Fault-tolerant & highly optimised 3D laser show-equipped usage screen
Lucio Andrés Illanes Albornoz 6d9a3c

Lucio Andrés Illanes Albornoz 6d9a3c
```
Lucio Andrés Illanes Albornoz 8a27f9
usage: ./build.sh [-a nt32|nt64] [-b debug|release] [-C dir[,..]] [-d] [-D kind[,..]]
Lucio Andrés Illanes Albornoz 8a27f9
                  [-F ipv4|ipv6|offline]    [-h]    [-p jobs]    [-P]   [-r ALL|LAST]
Lucio Andrés Illanes Albornoz 8a27f9
                  [-r [*[*[*]]]name[,..][:step,..]]  [-R] [-v[v[v[v]]]] [--as-needed]
Lucio Andrés Illanes Albornoz 8a27f9
                  [--debug-minipix] [--dump-on-abort]
Lucio Andrés Illanes Albornoz b6a9a1
                  [[=]<group>|<variable name>=<variable override>[ ..]]
Lucio Andrés Illanes Albornoz 6d9a3c

Lucio Andrés Illanes Albornoz 6d9a3c
        -a nt32|nt64      Selects 32-bit or 64-bit architecture; defaults to nt64.
Lucio Andrés Illanes Albornoz 6d9a3c
        -b debug|release  Selects debug or release build; defaults to debug.
Lucio Andrés Illanes Albornoz 6d9a3c
        -C dir[,..]       Clean build directory (build,) ${PREFIX} before processing build
Lucio Andrés Illanes Albornoz 5b1e55
                          scripts (prefix,) source directory (src,) and/or destination
Lucio Andrés Illanes Albornoz 5b1e55
                          directory (dest) after successful package builds.
Lucio Andrés Illanes Albornoz 5b1e55
        -D kind[,..]      Produce minimal midipix distribution directory (minipix,) RPM
Lucio Andrés Illanes Albornoz 5b1e55
                          binary packages (rpm,) and/or deployable distribution ZIP
Lucio Andrés Illanes Albornoz 5b1e55
                          archive (zipdist.) zipdist implies minipix.
Lucio Andrés Illanes Albornoz 6d9a3c
        -F ipv4|ipv6|offline
Lucio Andrés Illanes Albornoz 5b1e55
                          Force IPv4 (ipv4) or IPv6 (ipv6) when downloading package
Lucio Andrés Illanes Albornoz 5b1e55
                          archives and/or Git repositories or don't download either at all
Lucio Andrés Illanes Albornoz 5b1e55
                          (offline.)
Lucio Andrés Illanes Albornoz 6d9a3c
        -h                Show this screen.
Lucio Andrés Illanes Albornoz 6d9a3c
        -p jobs           Enables parallelisation at group-level, whenever applicable.
Lucio Andrés Illanes Albornoz 6d9a3c
        -P                The maximum count of jobs defaults to the number of logical
Lucio Andrés Illanes Albornoz 6d9a3c
                          processors on the host system divided by two (2.)
Lucio Andrés Illanes Albornoz 5b1e55

Lucio Andrés Illanes Albornoz 5b1e55
                          If -R is not specified and at least one (1) package fails to
Lucio Andrés Illanes Albornoz 5b1e55
                          build, all remaining package builds will be forcibly aborted.
Lucio Andrés Illanes Albornoz 5b1e55

Lucio Andrés Illanes Albornoz 5b1e55
        -r ALL|LAST       Restart all packages or the last failed package and resume
Lucio Andrés Illanes Albornoz 5b1e55
                          build, resp.
Lucio Andrés Illanes Albornoz 487c40
        -r [*[*[*]]]name[,..][:step,..]
Lucio Andrés Illanes Albornoz 5b1e55
                          Restart the specified comma-separated package(s) completely or
Lucio Andrés Illanes Albornoz 5b1e55
                          at optionally specified comma-separated list of build steps.
Lucio Andrés Illanes Albornoz 5b1e55

Lucio Andrés Illanes Albornoz 7bed88
                          Prepend w/ `*' to automatically include dependencies, `**' to
Lucio Andrés Illanes Albornoz 7bed88
                          forcibly rebuild all dependencies, and `***` to forcibly rebuild
Lucio Andrés Illanes Albornoz 7bed88
                          all packages that depend on the specified package(s).
Lucio Andrés Illanes Albornoz 6d9a3c

Lucio Andrés Illanes Albornoz 5b1e55
                          Currently defined build steps are:
Lucio Andrés Illanes Albornoz 5b1e55
                          fetch_wget, fetch_git, fetch_extract, configure_patch_pre,
Lucio Andrés Illanes Albornoz 5b1e55
                          configure_autotools, configure_patch, configure, build,
Lucio Andrés Illanes Albornoz 5b1e55
                          install_subdirs, install_make, install_files, install_libs,
Lucio Andrés Illanes Albornoz 5b1e55
                          install, and install_rpm.
Lucio Andrés Illanes Albornoz 5b1e55

Lucio Andrés Illanes Albornoz 6d9a3c
        -R                Ignore build failures, skip printing package logs, and continue
Lucio Andrés Illanes Albornoz 6d9a3c
                          building (relaxed mode.)
Lucio Andrés Illanes Albornoz 5b1e55
        -v[v[v[v]]]       Be verbose; -vv: always print package logs; -vvv: set xtrace
Lucio Andrés Illanes Albornoz 5b1e55
                          during package builds; -vvvv: logs fileops.
Lucio Andrés Illanes Albornoz 5b1e55
        --as-needed       Don't build unless the midipix_build repository has received
Lucio Andrés Illanes Albornoz 5b1e55
                          new commits.
Lucio Andrés Illanes Albornoz 6d9a3c
        --debug-minipix   Don't strip(1) minipix binaries to facilitate debugging minipix.
Lucio Andrés Illanes Albornoz 8a27f9
        --dump-on-abort   Produce package environment dump files on build failure to be
Lucio Andrés Illanes Albornoz 5f8a15
                          used in conjuction with pkg_shell.sh script (excludes -R.)
Lucio Andrés Illanes Albornoz 5b1e55
        <group>[ ..]      One of: dev_packages, dist, host_deps, host_deps_rpm,
Lucio Andrés Illanes Albornoz 7bed88
                          host_toolchain, host_tools, minipix, native_packages,
Lucio Andrés Illanes Albornoz 5b1e55
                          native_runtime, native_toolchain, native_tools.
Lucio Andrés Illanes Albornoz 487c40

Lucio Andrés Illanes Albornoz b6a9a1
                          Prepend w/ `=' to inhibit group-group dependency expansion.
Lucio Andrés Illanes Albornoz 8a27f9

Lucio Andrés Illanes Albornoz 8a27f9
        <variable name>=<variable override>[ ..]
Lucio Andrés Illanes Albornoz 8a27f9
                          Override build or package variable.
Lucio Andrés Illanes Albornoz 6d9a3c
```
Lucio Andrés Illanes Albornoz 6d9a3c
  
Lucio Andrés Illanes Albornoz 6d9a3c
[Back to top](#table-of-contents)
Lucio Andrés Illanes Albornoz 6d9a3c

Lucio Andrés Illanes Albornoz 6d9a3c
[//]: # "}}}"
Lucio Andrés Illanes Albornoz 5b1e55
[//]: # "{{{ 3.2. Adding a package"
Lucio Andrés Illanes Albornoz 5b1e55
## 3.2. Adding a package
Lucio Andrés Illanes Albornoz 5b1e55

Lucio Andrés Illanes Albornoz 5b1e55
Packages are grouped into *build groups* according to sets of common package
Lucio Andrés Illanes Albornoz 5b1e55
variable defaults, such as ``${PKG_CFLAGS_CONFIGURE}, ${PKG_LDFLAGS_CONFIGURE}``
Lucio Andrés Illanes Albornoz b6a9a1
and ``${PKG_CONFIGURE_ARGS}``, and semantic interrelatedness, such as the
Lucio Andrés Illanes Albornoz b6a9a1
``native_runtime`` build group comprising the Midipix runtime components.
Lucio Andrés Illanes Albornoz b6a9a1
Packages may belong to more than one build group such as when subsumed by a shorthand
Lucio Andrés Illanes Albornoz b6a9a1
build group e.g. the ``dev_packages`` build group, as long as the default set of build
Lucio Andrés Illanes Albornoz b6a9a1
groups or as overriden on the command line does not entail group membership conflicts.  
Lucio Andrés Illanes Albornoz 5b1e55
  
Lucio Andrés Illanes Albornoz 5b1e55
Build groups files beneath ``groups/`` named ``[0-9][0-9][0-9].<group name>.group``
Lucio Andrés Illanes Albornoz 5b1e55
contain package variable defaults, the alphabetically sorted list of contained
Lucio Andrés Illanes Albornoz 5b1e55
packages in ``<upper case group name>_PACKAGES``, and their package variables
Lucio Andrés Illanes Albornoz 5b1e55
sorted alphabetically with the exception of ``${PKG_DEPENDS}`` (if present,)
Lucio Andrés Illanes Albornoz 5b1e55
``${PKG_SHA256SUM}``, ``${PKG_URL}``, and ``${PKG_VERSION}``, and/or ``${PKG_URLS_GIT}``,
Lucio Andrés Illanes Albornoz 5b1e55
which are specified in this order.  
Lucio Andrés Illanes Albornoz 5b1e55
  
Lucio Andrés Illanes Albornoz 5b1e55
Pick a build group according to the criteria mentioned, add the package to the
Lucio Andrés Illanes Albornoz 5b1e55
build group's list of contained packages in its corresponding file, and add the
Lucio Andrés Illanes Albornoz 5b1e55
set of package variables required (see above and section [4.2](#42-package-variables).)  
Lucio Andrés Illanes Albornoz 5b1e55
Consult section [3.4](#34-patches-and-vars-files) if the package to be added
Lucio Andrés Illanes Albornoz 5b1e55
requires patches or additional code amending or replacing package build steps
Lucio Andrés Illanes Albornoz 5b1e55
or the entire package build. Consult section [4.1](#41-build-steps) for a list
Lucio Andrés Illanes Albornoz 5b1e55
of package build steps and how they are overriden.
Lucio Andrés Illanes Albornoz 5b1e55
  
Lucio Andrés Illanes Albornoz 5b1e55
[Back to top](#table-of-contents)
Lucio Andrés Illanes Albornoz 5b1e55

Lucio Andrés Illanes Albornoz 5b1e55
[//]: # "}}}"
Lucio Andrés Illanes Albornoz 5b1e55
[//]: # "{{{ 3.3. Addressing build failure"
Lucio Andrés Illanes Albornoz 5b1e55
## 3.3. Addressing build failure
Lucio Andrés Illanes Albornoz 5b1e55

Lucio Andrés Illanes Albornoz 4a70bb
During package build, standard error and output are redirected into a log file beneath
Lucio Andrés Illanes Albornoz 4a70bb
``${BUILD_WORKDIR}`` named ``${PKG_NAME}_stderrout.log``, following a package variable
Lucio Andrés Illanes Albornoz 4a70bb
dump. If ``-vv`` was specified, package logs will additionally be printed to standard
Lucio Andrés Illanes Albornoz 4a70bb
output. If ``-vvv`` was specified, ``xtrace`` will be set during package builds for
Lucio Andrés Illanes Albornoz 4a70bb
rudimentary debugging purposes. Additionally, packages using GNU autotools will, if
Lucio Andrés Illanes Albornoz 4a70bb
package configuration failed or appears relevant, log the configuration process in detail
Lucio Andrés Illanes Albornoz 4a70bb
in, most usually, ``${PKG_BUILD_DIR}/config.log``.  
Lucio Andrés Illanes Albornoz 8a27f9

Lucio Andrés Illanes Albornoz 8a27f9
If ``--dump-on-abort`` was specified, a subset of the variables set and environment
Lucio Andrés Illanes Albornoz f3459e
variables exported will be written to ``${BUILD_WORKDIR}/${PKG_NAME}.dump``, which may
Lucio Andrés Illanes Albornoz f3459e
subsequently be used in order to obtain a package build shell environment with the
Lucio Andrés Illanes Albornoz 60fba6
``pkgtool.sh`` script (see sections [3.5](#35-pkgtoolsh)[3.5.1](#351-s-package-build-shell-environment).)
Lucio Andrés Illanes Albornoz 5b1e55
  
Lucio Andrés Illanes Albornoz 5b1e55
[Back to top](#table-of-contents)
Lucio Andrés Illanes Albornoz 5b1e55

Lucio Andrés Illanes Albornoz 5b1e55
[//]: # "}}}"
Lucio Andrés Illanes Albornoz 5b1e55
[//]: # "{{{ 3.4. Patches and ``vars`` files"
Lucio Andrés Illanes Albornoz 5b1e55
## 3.4. Patches and ``vars`` files
Lucio Andrés Illanes Albornoz 5b1e55

Lucio Andrés Illanes Albornoz 5b1e55
Package patches are applied prior and/or subsequent to (GNU autotools or simular) package
Lucio Andrés Illanes Albornoz 5b1e55
configuration during the ``configure_patch_pre`` and/or ``configure_patch`` build steps,
Lucio Andrés Illanes Albornoz 5b1e55
respectively (see section [4.1](#41-build-steps).) Patch files are searched for beneath
Lucio Andrés Illanes Albornoz 5b1e55
``patches/`` with the following globs and in-order:
Lucio Andrés Illanes Albornoz 5b1e55
* ``${PKG_NAME}-${PKG_VERSION}_pre.local.patch``
Lucio Andrés Illanes Albornoz 5b1e55
  or ``${PKG_NAME}_pre.local.patch`` (for packages lacking ``${PKG_VERSION}``)
Lucio Andrés Illanes Albornoz 5b1e55
* ``${PKG_NAME}-${PKG_VERSION}_pre.local@${BUILD_HNAME}.patch``
Lucio Andrés Illanes Albornoz 5b1e55
  or ``${PKG_NAME}_pre.local@${BUILD_HNAME}.patch`` (for packages lacking ``${PKG_VERSION}``)
Lucio Andrés Illanes Albornoz 5b1e55
* ``${PKG_NAME}/*.patch``
Lucio Andrés Illanes Albornoz 5b1e55
* ``${PKG_NAME}-${PKG_VERSION}.local.patch``
Lucio Andrés Illanes Albornoz 5b1e55
  or ``${PKG_NAME}.local.patch`` (for packages lacking ``${PKG_VERSION}``)
Lucio Andrés Illanes Albornoz 5b1e55
* ``${PKG_NAME}-${PKG_VERSION}.local@${BUILD_HNAME}.patch``
Lucio Andrés Illanes Albornoz 5b1e55
  or ``${PKG_NAME}.local@${BUILD_HNAME}.patch`` (for packages lacking ``${PKG_VERSION}``)
Lucio Andrés Illanes Albornoz 5b1e55
* ``${PKG_PATCHES_EXTRA}`` (if set)
Lucio Andrés Illanes Albornoz 5b1e55
  
Lucio Andrés Illanes Albornoz 5b1e55
If the default set of package build steps does not suffice, such as if additional commands
Lucio Andrés Illanes Albornoz 5b1e55
must be executed after package configuration or prior to building, or if an entire or all
Lucio Andrés Illanes Albornoz 5b1e55
build step must be replaced, overrides may be specified in the form of functions in the
Lucio Andrés Illanes Albornoz 5b1e55
package's ``vars/${PKG_NAME}.vars`` ``vars`` file. Consult section [4.1](#41-build-steps)
Lucio Andrés Illanes Albornoz 5b1e55
for a list of package build steps and how they are overriden.
Lucio Andrés Illanes Albornoz 5b1e55
  
Lucio Andrés Illanes Albornoz 5b1e55
[Back to top](#table-of-contents)
Lucio Andrés Illanes Albornoz 5b1e55

Lucio Andrés Illanes Albornoz 5b1e55
[//]: # "}}}"
Lucio Andrés Illanes Albornoz f3459e
[//]: # "{{{ 3.5. ``pkgtool.sh``"
Lucio Andrés Illanes Albornoz f3459e
## 3.5. ``pkgtool.sh``
Lucio Andrés Illanes Albornoz f3459e

Lucio Andrés Illanes Albornoz 60fba6
```
Lucio Andrés Illanes Albornoz 60fba6
usage: ./pkgtool.sh [-a nt32|nt64] [-b debug|release] [-i|-r|-s|-t]
Lucio Andrés Illanes Albornoz 60fba6
                    [<variable name>=<variable override>[ ..]] name
Lucio Andrés Illanes Albornoz 60fba6

Lucio Andrés Illanes Albornoz 60fba6
        -a nt32|nt64      Selects 32-bit or 64-bit architecture; defaults to nt64.
Lucio Andrés Illanes Albornoz 60fba6
        -b debug|release  Selects debug or release build; defaults to debug.
Lucio Andrés Illanes Albornoz 60fba6
        -i                List package variables and dependencies of single named package.
Lucio Andrés Illanes Albornoz 60fba6
        -r                List reverse dependencies of single named package.
Lucio Andrés Illanes Albornoz 60fba6
        -s                Enter interactive package build shell environment for single
Lucio Andrés Illanes Albornoz 60fba6
                          named package; requires a package dump file. If the package
Lucio Andrés Illanes Albornoz 60fba6
                          has not been built yet or built successfully, it will be rebuilt
Lucio Andrés Illanes Albornoz 60fba6
                          at build steps up until, by default, the `build' build step and
Lucio Andrés Illanes Albornoz 60fba6
                          forcibly aborted and dumped prior to enterting the shell.
Lucio Andrés Illanes Albornoz 60fba6
        -t                Produce tarball of package build root directory and build log
Lucio Andrés Illanes Albornoz 60fba6
                          file for the purpose of distribution given build failure.
Lucio Andrés Illanes Albornoz 60fba6

Lucio Andrés Illanes Albornoz 60fba6
        <variable name>=<variable override>[ ..]
Lucio Andrés Illanes Albornoz 60fba6
                          Override build variable.
Lucio Andrés Illanes Albornoz 60fba6
```
Lucio Andrés Illanes Albornoz 60fba6
  
Lucio Andrés Illanes Albornoz 60fba6
> N.B. When using ``pkgtool.sh`` on a build w/ build variables (see section [4](#4-build-variables))
Lucio Andrés Illanes Albornoz 60fba6
overriden on the command line or via the environment, ensure that they are included in the
Lucio Andrés Illanes Albornoz 60fba6
``pkgtool.sh`` command line, preceding the package name, or exported, respectively.
Lucio Andrés Illanes Albornoz 60fba6
  
Lucio Andrés Illanes Albornoz 60fba6
[Back to top](#table-of-contents)
Lucio Andrés Illanes Albornoz 60fba6

Lucio Andrés Illanes Albornoz 60fba6
[//]: # "}}}"
Lucio Andrés Illanes Albornoz 60fba6
[//]: # "{{{ 3.5.1. -s: package build shell environment"
Lucio Andrés Illanes Albornoz 60fba6
### 3.5.1. -s: package build shell environment
Lucio Andrés Illanes Albornoz 60fba6

Lucio Andrés Illanes Albornoz f3459e
When ``build.sh`` is executed with the ``--dump-on-abort`` option, a subset of the
Lucio Andrés Illanes Albornoz f3459e
variables set and environment variables exported will be written to ``${BUILD_WORKDIR}/${PKG_NAME}.dump``
Lucio Andrés Illanes Albornoz f3459e
on build failure, which may subsequently be used in order to obtain a package build shell
Lucio Andrés Illanes Albornoz f3459e
environment with the ``pkgtool.sh`` script, e.g.:  
Lucio Andrés Illanes Albornoz f3459e
  
Lucio Andrés Illanes Albornoz f3459e
```
Lucio Andrés Illanes Albornoz 60fba6
midipix_build@sandbox:(src/midipix_build)> $ ./pkgtool.sh -a nt64 -b debug -s mc
Lucio Andrés Illanes Albornoz f3459e
==> 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 f3459e
==> 2020/03/11 15:46:28 Run $R to rebuild `mc'.
Lucio Andrés Illanes Albornoz f3459e
==> 2020/03/11 15:46:28 Run $RS <step> to restart the specified build step of `mc'
Lucio Andrés Illanes Albornoz f3459e
==> 2020/03/11 15:46:28 Run $D to automatically regenerate the patch for `mc'.
Lucio Andrés Illanes Albornoz f3459e
midipix_build@sandbox:(src/midipix_build)> $
Lucio Andrés Illanes Albornoz f3459e
```
Lucio Andrés Illanes Albornoz f3459e
  
Lucio Andrés Illanes Albornoz f3459e
If a package build shell environment is desired for a package that has either not been
Lucio Andrés Illanes Albornoz f3459e
built at all or built successfully, ``pkgshell.sh`` will attempt to rebuild the package
Lucio Andrés Illanes Albornoz f3459e
at build steps up until, by default, ``build``, and then forcibly abort the build and
Lucio Andrés Illanes Albornoz f3459e
write ``${BUILD_WORKDIR}/${PKG_NAME}.dump`` as above prior to entering the shell.  
Lucio Andrés Illanes Albornoz f3459e
  
Lucio Andrés Illanes Albornoz f3459e
Consult sections [3.2](#32-adding-a-package), [3.4](#34-patches-and-vars-files), [4](#4-build-variables),
Lucio Andrés Illanes Albornoz f3459e
[4.1](#41-build-steps), and [4.2](#42-package-variables) for further information
Lucio Andrés Illanes Albornoz f3459e
concerning the package build process.  
Lucio Andrés Illanes Albornoz f3459e
  
Lucio Andrés Illanes Albornoz f3459e
[Back to top](#table-of-contents)
Lucio Andrés Illanes Albornoz f3459e

Lucio Andrés Illanes Albornoz f3459e
[//]: # "}}}"
Lucio Andrés Illanes Albornoz 6d9a3c

Lucio Andrés Illanes Albornoz 23f3c2
[//]: # "{{{ 4. Build variables"
Lucio Andrés Illanes Albornoz 23f3c2
## 4. Build variables
Lucio Andrés Illanes Albornoz 6d9a3c

Lucio Andrés Illanes Albornoz 6d9a3c
The following variables are primarily defined in ``midipix.env`` and may be
Lucio Andrés Illanes Albornoz 5b1e55
overriden on a per-build basis on the command-line after the last option
Lucio Andrés Illanes Albornoz 8a27f9
argument, if any, the environment, and/or ``${HOME}/midipix_build.vars``,
Lucio Andrés Illanes Albornoz 8a27f9
``${HOME}/.midipix_build.vars``, and/or ``../midipix_build.vars``, e.g.:
Lucio Andrés Illanes Albornoz 6d9a3c

Lucio Andrés Illanes Albornoz 6d9a3c
```shell
Lucio Andrés Illanes Albornoz 6d9a3c
./build.sh -a nt64 -b release -D minipix,zipdist -P -v PREFIX_ROOT="${HOME}/midipix_tmp"
Lucio Andrés Illanes Albornoz 8a27f9
env ARCH=nt64 BUILD=release PREFIX_ROOT="${HOME}/midipix_tmp" ./build.sh -D minipix,zipdist -P -v
Lucio Andrés Illanes Albornoz 6d9a3c
```
Lucio Andrés Illanes Albornoz 6d9a3c

Lucio Andrés Illanes Albornoz 6d9a3c
| Variable name    | Default value                   | Description                                                                   |
Lucio Andrés Illanes Albornoz 6d9a3c
| ---------------- | ------------------------------- | ----------------------------------------------------------------------------- |
Lucio Andrés Illanes Albornoz 6d9a3c
| ARCH             | nt64                            | Target 32-bit (nt32) or 64-bit (nt64) architecture                            |
Lucio Andrés Illanes Albornoz 6d9a3c
| BUILD            | debug                           | Build w/ debugging (debug) or release compiler flags                          |
Lucio Andrés Illanes Albornoz 6d9a3c
| BUILD_DLCACHEDIR | ${PREFIX_ROOT}/dlcache          | Absolute pathname to package downloads cache root directory                   |
Lucio Andrés Illanes Albornoz 9b5d49
| BUILD_HNAME      | $(hostname)                     | Build system hostname                                                         |
Lucio Andrés Illanes Albornoz 6d9a3c
| BUILD_WORKDIR    | ${PREFIX}/tmp                   | Absolute pathname to temporary package build root directory                   |
Lucio Andrés Illanes Albornoz 6d9a3c
| PREFIX           | ${PREFIX_ROOT}/${ARCH}/${BUILD} | Absolute pathname to architecture- & build type-specific build root directory |
Lucio Andrés Illanes Albornoz 6d9a3c
| PREFIX_CROSS     | ${PREFIX}/${DEFAULT_TARGET}     | Absolute pathname to toolchain root directory                                 |
Lucio Andrés Illanes Albornoz 6d9a3c
| PREFIX_MINGW32   | ${PREFIX}/x86_64-w64-mingw32    | Absolute pathname to MinGW toolchain root directory                           |
Lucio Andrés Illanes Albornoz 6d9a3c
| PREFIX_MINIPIX   | ${PREFIX}/minipix               | Absolute pathname to minipix distribution root directory                      |
Lucio Andrés Illanes Albornoz 6d9a3c
| PREFIX_NATIVE    | ${PREFIX}/native                | Absolute pathname to cross-compiled packages root directory                   |
Lucio Andrés Illanes Albornoz 6d9a3c
| PREFIX_ROOT      | ${HOME}/midipix                 | Absolute pathname to top-level directory                                      |
Lucio Andrés Illanes Albornoz 6d9a3c
| PREFIX_RPM       | ${PREFIX}/rpm                   | Absolute pathname to package RPM archive root directory                       |
Lucio Andrés Illanes Albornoz 6d9a3c
  
Lucio Andrés Illanes Albornoz 6d9a3c
[Back to top](#table-of-contents)
Lucio Andrés Illanes Albornoz 6d9a3c

Lucio Andrés Illanes Albornoz 6d9a3c
[//]: # "}}}"
Lucio Andrés Illanes Albornoz 5b1e55
[//]: # "{{{ 4.1. Build steps"
Lucio Andrés Illanes Albornoz 5b1e55
## 4.1. Build steps
Lucio Andrés Illanes Albornoz 5b1e55

Lucio Andrés Illanes Albornoz 5b1e55
Package builds are divided up into consecutively executed build steps until
Lucio Andrés Illanes Albornoz 5b1e55
completion or aborted on failure unless relaxed mode is enabled by passing
Lucio Andrés Illanes Albornoz 5b1e55
``-R``.  
Lucio Andrés Illanes Albornoz 5b1e55
  
Lucio Andrés Illanes Albornoz 5b1e55
Each build step corresponds to a function in the corresponding ``subr/pkg_*.subr``
Lucio Andrés Illanes Albornoz 5b1e55
script and may be overriden entirely by a function named ``pkg_<package name>_<build step>()``
Lucio Andrés Illanes Albornoz 5b1e55
or composed in terms of prior and/or subsequent execution by a function named
Lucio Andrés Illanes Albornoz 5b1e55
``pkg_<package name>_<build step>_pre()`` and/or ``pkg_<package name>_<build step>_post()``,
Lucio Andrés Illanes Albornoz 5b1e55
respectively, in the package's ``vars`` file. If a function named ``pkg_<package name>_all()``
Lucio Andrés Illanes Albornoz 5b1e55
exists, it will override all build steps.  
Lucio Andrés Illanes Albornoz 5b1e55
  
Lucio Andrés Illanes Albornoz 5b1e55
Build step status is tracked on a per-package basis by state files beneath
Lucio Andrés Illanes Albornoz 5b1e55
``${BUILD_WORKDIR}`` following the format ``.<package name>.<build step>``;
Lucio Andrés Illanes Albornoz 5b1e55
package build completion corresponds to the pseudo-build step ``finish``.
Lucio Andrés Illanes Albornoz 5b1e55

Lucio Andrés Illanes Albornoz 5b1e55
| Name                | Description                                                                                                                                                                           |
Lucio Andrés Illanes Albornoz 5b1e55
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
Lucio Andrés Illanes Albornoz 5b1e55
| fetch_download      | Download package archive & verify w/ SHA-256 message digest and/or clone Git repository/ies                                                                                           |
Lucio Andrés Illanes Albornoz 5b1e55
| fetch_extract       | Extract package archive, if any                                                                                                                                                       |
Lucio Andrés Illanes Albornoz 5b1e55
| configure_patch_pre | Apply ``chainport`` patches and/or patches beneath ``patches/`` prior to (GNU autotools or similar) configuration                                                                     |
Lucio Andrés Illanes Albornoz 5b1e55
| configure_autotools | Bootstrap (GNU autools or similar) environment, and install ``config.sub`` and ``config.cache``                                                                                       |
Lucio Andrés Illanes Albornoz 5b1e55
| configure_patch     | Apply patches beneath ``patches/`` and/or set in ``${PKG_PATCHES_EXTRA}`` after (GNU autotools or similar) configuration                                                              |
Lucio Andrés Illanes Albornoz 5b1e55
| configure           | Perform package (GNU autools or similar) configuration w/ configuration-time set of environment variables                                                                             |
Lucio Andrés Illanes Albornoz 5b1e55
| build               | Call ``make(1)`` w/ build-time set of make variables                                                                                                                                  |
Lucio Andrés Illanes Albornoz 5b1e55
| install_subdirs     | Create default directory hierarchy in ``${PKG_DESTDIR}``, optionally amended w/ ``${PKG_INSTALL_FILES_DESTDIR_EXTRA}``                                                                |
Lucio Andrés Illanes Albornoz 5b1e55
| install_make        | Call ``make(1)`` w/ ``${PKG_INSTALL_TARGET}`` (defaults to ``install``) and installation-time set of make variables                                                                   |
Lucio Andrés Illanes Albornoz 5b1e55
| install_files       | Install ``${PKG_INSTALL_FILES}``, ``pkgconf(1)`` package files, and/or stripped binaries within ``${PKG_DESTDIR}``                                                                    |
Lucio Andrés Illanes Albornoz 5b1e55
| install_libs        | Purge libtool ``.la`` files and install shared objects within ``${PKG_DESTDIR}`` w/ ``perk`` and corresponding symbolic links                                                         |
Lucio Andrés Illanes Albornoz 5b1e55
| install             | Fix directory and file mode bits within ``${PKG_DESTDIR}``, install into ``${PKG_PREFIX}`` under mutex, and add package to ``${PREFIX}/pkglist.${PKG_BUILD_TYPE}`` (unless inhibited) |
Lucio Andrés Illanes Albornoz 5b1e55
| install_rpm         | Build package RPM w/ auto-generated specifiation file based on ``etc/package.spec`` beneath ``${PREFIX_RPM}``                                                                         |
Lucio Andrés Illanes Albornoz 5b1e55
| clean               | Clean ``${PKG_BUILD_DIR}`` and/or ``${PKG_DESTDIR}`` and/or ``${PKG_BASE_DIR}/${PKG_SUBDIR}`` as per ``-C build,dest,src``, resp., if any                                             |
Lucio Andrés Illanes Albornoz 5b1e55
  
Lucio Andrés Illanes Albornoz 5b1e55
[Back to top](#table-of-contents)
Lucio Andrés Illanes Albornoz 5b1e55

Lucio Andrés Illanes Albornoz 5b1e55
[//]: # "}}}"
Lucio Andrés Illanes Albornoz 5b1e55
[//]: # "{{{ 4.2. Package variables"
Lucio Andrés Illanes Albornoz 5b1e55
## 4.2. Package variables
Lucio Andrés Illanes Albornoz 6d9a3c

Lucio Andrés Illanes Albornoz 6d9a3c
The following variables are package-specific and receive their value from either
Lucio Andrés Illanes Albornoz 6d9a3c
top-level defaults defined in ``midipix.env``, build group-specific defaults
Lucio Andrés Illanes Albornoz 6d9a3c
from the build group the package pertains to and defined in its corresponding
Lucio Andrés Illanes Albornoz 6d9a3c
file beneath ``groups/``, or package-specific overrides defined either in the
Lucio Andrés Illanes Albornoz 5b1e55
latter and/or in its corresponding file beneath ``vars/``.  
Lucio Andrés Illanes Albornoz 5b1e55
Additionally, overrides may be specified on a per-build basis on the command-
Lucio Andrés Illanes Albornoz 5b1e55
line after the last argument, with each variable prefixed w/ ``PKG_``, e.g.:
Lucio Andrés Illanes Albornoz 5b1e55
``./build.sh [ ... ] PKG_ZSH_CC="/usr/bin/clang"``.  
Lucio Andrés Illanes Albornoz 6d9a3c
  
Lucio Andrés Illanes Albornoz 6d9a3c
The minimum set of package variables that must be provided is ``SHA256SUM, URL,
Lucio Andrés Illanes Albornoz 6d9a3c
VERSION`` and/or ``URLS_GIT``, respectively.
Lucio Andrés Illanes Albornoz 6d9a3c

Lucio Andrés Illanes Albornoz 5b1e55
| Package variable name       | Description                                                                                                                                 |
Lucio Andrés Illanes Albornoz 5b1e55
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
Lucio Andrés Illanes Albornoz 5b1e55
| AR                          | Command- or pathname of toolchain library archive editor ``ar(1)``)                                                                         |
Lucio Andrés Illanes Albornoz 5b1e55
| BASE_DIR                    | Absolute pathname to package build root directory beneath ``${BUILD_WORKDIR}``                                                              |
Lucio Andrés Illanes Albornoz 5b1e55
| BUILD_DIR                   | Directory name of package build directory beneath ``${PKG_BASE_DIR}``                                                                       |
Lucio Andrés Illanes Albornoz 5b1e55
| BUILD_STEPS_DISABLE         | List of build steps to disable during package build                                                                                         |
Lucio Andrés Illanes Albornoz 5b1e55
| BUILD_TYPE                  | Cross-compiled toolchain (``cross``,) host (``host```,) or cross-compiled package (``native``) build type                                   |
Lucio Andrés Illanes Albornoz 5b1e55
| CC                          | Command- or pathname of toolchain C compiler ``cc(1)``)                                                                                     |
Lucio Andrés Illanes Albornoz 5b1e55
| CFLAGS_BUILD_EXTRA          | Additional C compiler flags during package ``make(1)``) build                                                                               |
Lucio Andrés Illanes Albornoz 5b1e55
| CFLAGS_CONFIGURE            | C compiler flags during package (GNU autotools or similar) configuration                                                                    |
Lucio Andrés Illanes Albornoz 5b1e55
| CFLAGS_CONFIGURE_EXTRA      | Additional C compiler flags during package (GNU autotools or similar) configuration                                                         |
Lucio Andrés Illanes Albornoz 5b1e55
| CONFIG_CACHE                | List of GNU autotools configuration cache variables                                                                                         |
Lucio Andrés Illanes Albornoz 5b1e55
| CONFIG_CACHE_EXTRA          | Additional list of GNU autotools configuration cache variables                                                                              |
Lucio Andrés Illanes Albornoz 5b1e55
| CONFIG_CACHE_LOCAL          | Additional list of GNU autotools configuration cache variables                                                                              |
Lucio Andrés Illanes Albornoz 5b1e55
| CONFIGURE                   | Command- or pathname to package (GNU autotools or similar) configuration script                                                             |
Lucio Andrés Illanes Albornoz 5b1e55
| CONFIGURE_ARGS              | List of arguments to package (GNU autotools or similar) configuration script                                                                |
Lucio Andrés Illanes Albornoz 5b1e55
| CONFIGURE_ARGS_EXTRA        | Additional list of arguments to package (GNU autotools or similar) configuration script                                                     |
Lucio Andrés Illanes Albornoz 5b1e55
| CXX                         | Command- or pathname of toolchain C++ compiler ``c++(1)``)                                                                                  |
Lucio Andrés Illanes Albornoz 5b1e55
| CXXFLAGS_CONFIGURE          | List of C++ compiler flags during package (GNU autotools or similar) configuration                                                          |
Lucio Andrés Illanes Albornoz 5b1e55
| CXXFLAGS_CONFIGURE_EXTRA    | Additional list of C++ compiler flags during package (GNU autotools or similar) configuration                                               |
Lucio Andrés Illanes Albornoz 5b1e55
| DEPENDS                     | List of package-package dependencies                                                                                                        |
Lucio Andrés Illanes Albornoz 5b1e55
| DESTDIR                     | Directory name of package installation destination directory beneath ``${PKG_BASE_DIR}``                                                    |
Lucio Andrés Illanes Albornoz 5b1e55
| DISABLED                    | Disable package                                                                                                                             |
Lucio Andrés Illanes Albornoz 5b1e55
| 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 5b1e55
| FNAME                       | Filename of package archive file                                                                                                            |
Lucio Andrés Illanes Albornoz 5b1e55
| FORCE_AUTORECONF            | Forcibly run ``autoreconf -fiv`` prior to package (GNU autotools or similar) configuration                                                  |
Lucio Andrés Illanes Albornoz 5b1e55
| GITROOT                     | midipix packages Git URL prefix                                                                                                             |
Lucio Andrés Illanes Albornoz 5b1e55
| INHERIT_FROM                | Inherit variables from named package                                                                                                        |
Lucio Andrés Illanes Albornoz 5b1e55
| 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 5b1e55
| 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 5b1e55
| 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 5b1e55
| INSTALL_TARGET              | Name of package build ``make(1)`` installation target                                                                                       |
Lucio Andrés Illanes Albornoz 5b1e55
| INSTALL_TARGET_EXTRA        | Additional name of package build ``make(1)`` installation target                                                                            |
Lucio Andrés Illanes Albornoz 5b1e55
| IN_TREE                     | Build package in-tree within ``${PKG_SUBDIR}``                                                                                              |
Lucio Andrés Illanes Albornoz 5b1e55
| LDFLAGS_BUILD_EXTRA         | Additional linker flags during package ``make(1)``) build                                                                                   |
Lucio Andrés Illanes Albornoz 5b1e55
| LDFLAGS_CONFIGURE           | Linker flags during package (GNU autotools or similar) configuration                                                                        |
Lucio Andrés Illanes Albornoz 5b1e55
| LDFLAGS_CONFIGURE_EXTRA     | Additional linker flags during package (GNU autotools or similar) configuration                                                             |
Lucio Andrés Illanes Albornoz 5b1e55
| LIBTOOL                     | Command- or pathname of ``libtool(1)`` (defaults to ``slibtool``)                                                                           |
Lucio Andrés Illanes Albornoz 5b1e55
| MAKE                        | Command line of ``make(1)``                                                                                                                 |
Lucio Andrés Illanes Albornoz 5b1e55
| MAKEFLAGS_BUILD             | List of ``make(1)`` flags during package ``make(1)``) build                                                                                 |
Lucio Andrés Illanes Albornoz 5b1e55
| MAKEFLAGS_BUILD_EXTRA       | Additional list of ``make(1)`` flags during package ``make(1)``) build                                                                      |
Lucio Andrés Illanes Albornoz 5b1e55
| MAKEFLAGS_INSTALL           | List of ``make(1)`` flags during package ``make(1)``) installation                                                                          |
Lucio Andrés Illanes Albornoz 5b1e55
| MAKEFLAGS_INSTALL_EXTRA     | Additional list of ``make(1)`` flags during package ``make(1)``) installation                                                               |
Lucio Andrés Illanes Albornoz 175e92
| 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 5b1e55
| MAKE_INSTALL_VNAME          | Variable name of ``make(1)`` installation destination directory variable during package ``make(1)``) installation                           |
Lucio Andrés Illanes Albornoz 5b1e55
| NO_CLEAN                    | Inhibit cleaning of package build directory beneath ``${PKG_BASE_DIR}`` pre-finish                                                          |
Lucio Andrés Illanes Albornoz 5b1e55
| NO_CLEAN_BASE_DIR           | Inhibit cleaning of package build root directory beneath ``${BUILD_WORKDIR}``                                                               |
Lucio Andrés Illanes Albornoz 5b1e55
| NO_LOG_VARS                 | Inhibit logging of build & package variables pre-package build                                                                              |
Lucio Andrés Illanes Albornoz 5b1e55
| PATCHES_EXTRA               | Additional list of patches to apply                                                                                                         |
Lucio Andrés Illanes Albornoz 5b1e55
| PKG_CONFIG                  | Command- or pathname of ``pkg-config(1)``                                                                                                   |
Lucio Andrés Illanes Albornoz 703f24
| PKG_CONFIG_LIBDIR           | ``pkg-config(1)`` search directory                                                                                                          |
Lucio Andrés Illanes Albornoz 5b1e55
| PKGLIST_DISABLE             | Inhibit inclusion into ``${PREFIX}/pkglist.${PKG_BUILD_TYPE}``                                                                              |
Lucio Andrés Illanes Albornoz 5b1e55
| PREFIX                      | Absolute pathname of top-level installation directory and package search path                                                               |
Lucio Andrés Illanes Albornoz 5b1e55
| PYTHON                      | Command- or pathname of Python                                                                                                              |
Lucio Andrés Illanes Albornoz 5b1e55
| RANLIB                      | Command- or pathname of toolchain library archive index generator ``ranlib(1)``)                                                            |
Lucio Andrés Illanes Albornoz 5b1e55
| RPM_DISABLE                 | Inhibit creation of RPM archive                                                                                                             |
Lucio Andrés Illanes Albornoz 5b1e55
| SHA256SUM                   | SHA-256 message digest of package archive                                                                                                   |
Lucio Andrés Illanes Albornoz 5b1e55
| SUBDIR                      | Name of extracted archive or git-{clone,pull}(1)'d directory                                                                                |
Lucio Andrés Illanes Albornoz 5b1e55
| TARGET                      | Dash-separated {build,host,target} triplet                                                                                                  |
Lucio Andrés Illanes Albornoz 5b1e55
| URL                         | URL to package archive                                                                                                                      |
Lucio Andrés Illanes Albornoz 5b1e55
| URLS_GIT                    | List of package Git URL(s) (``*name*=*URL*@*branch*``)                                                                                      |
Lucio Andrés Illanes Albornoz 5b1e55
| VERSION                     | Package version                                                                                                                             |
Lucio Andrés Illanes Albornoz 6d9a3c
  
Lucio Andrés Illanes Albornoz 6d9a3c
[Back to top](#table-of-contents)
Lucio Andrés Illanes Albornoz 6d9a3c

Lucio Andrés Illanes Albornoz 6d9a3c
[//]: # "}}}"
Lucio Andrés Illanes Albornoz 6d9a3c

Lucio Andrés Illanes Albornoz 23f3c2
[//]: # "{{{ 5. References"
Lucio Andrés Illanes Albornoz 23f3c2
## 5. References
Lucio Andrés Illanes Albornoz 6d9a3c

Lucio Andrés Illanes Albornoz 6d9a3c
* ``Sun, 25 Apr 2016 09:04:08 +0000 [1]`` musl FAQ  
Lucio Andrés Illanes Albornoz 5b1e55
* ``Wed, 04 Mar 2020 13:36:19 +0000 [2]`` midipix - what is midipix, and how is it different?  
Lucio Andrés Illanes Albornoz 6d9a3c
  
Lucio Andrés Illanes Albornoz 6d9a3c
[Back to top](#table-of-contents)
Lucio Andrés Illanes Albornoz 6d9a3c

Lucio Andrés Illanes Albornoz 6d9a3c
[//]: # "}}}"
Lucio Andrés Illanes Albornoz 6d9a3c
  
Lucio Andrés Illanes Albornoz 6d9a3c
[modeline]: # ( vim: set ff=dos tw=0: )