diff --git a/Config.in b/Config.in index e47e534e..5ffb93e0 100644 --- a/Config.in +++ b/Config.in @@ -1,3 +1,97 @@ +menu "Branding" + +config INFIX_VENDOR + string "Vendor name" + default "KernelKit" + help + The name of the operating system vendor. This is the name of the + organization or company which produces the OS. + + This name is intended to be exposed in "About this system" UIs or + software update UIs when needed to distinguish the OS vendor from + the OS itself. It is intended to be human readable. + + Used for VENDOR_NAME in /etc/os-release and GNS3 appliance files. + +config INFIX_VENDOR_HOME + string "Vendor URL" + help + The homepage of the OS vendor. The value should be in RFC3986 + format, and should be "http:" or "https:" URLs. Only one URL shall + be listed in the setting. + + Optional, used for VENDOR_HOME in /etc/os-release + +config INFIX_NAME + string "Operating system name" + default "Infix" + help + Mandatory. Used for identifying the OS as NAME in /etc/os-release + and product_name in GNS3 appliance files. + +config INFIX_ID + string "Operating system identifier" + default "infix" + help + A lower-case string (no spaces or other characters outside of 0–9, + a–z, '.', '_' and '-') identifying the operating system, excluding + any version information and suitable for processing by scripts or + usage in generated filenames. + + Mandatory. Used for identifying the OS as ID in /etc/os-release and + in the generated image name: ID-ARCH-VERSION.img + +config INFIX_TAGLINE + string "Operating system tagline" + default "Infix — a Network Operating System" + help + Mandatory. Used for identifying the OS, e.g. as PRETTY_NAME in + /etc/os-release and description in the GNS3 appliance. + + This is also show at boot when the system init process starts. + +config INFIX_DESC + string "Operating system description" + help + Optional. Used for long description texts about the OS. E.g., + the GNS3 appliance file description field. Saved in the file + /etc/os-release as INFIX_DESC. + +config INFIX_HOME + string "Operating system URL" + help + Used for identifying the OS, e.g. as HOME_URL in /etc/os-release + +config INFIX_DOC + string "Operating system docs" + help + Optional. Main documentation URL, will be shown in /etc/os-release + as DOCUMENTATION_URL. + +config INFIX_SUPPORT + string "Operating system support" + help + Main support page for the operating system, if there is any. This + is primarily intended for operating systems which vendors provide + support for. May be a http:, https:, or mailto: URI. + + Optional. Shown, e.g., as SUPPORT_URL in /etc/os-release or + maintainer_email in .gns3a. + +config INFIX_OEM_PATH + string "Path to OEM br2-external" + help + A br2-external using Infix will likely want to version the branded + OS using their own GIT tags. Set this variable to point to the base + directory (absolute path) and the Infix post-build.sh will call `git + describe -C $INFIX_OEM_PATH`. + + Note: for release builds the global variable INFIX_RELEASE overrides + the version information derived from `git describe`. However, the + GIT version is always saved as the BUILD_ID in /etc/os-releases. + +endmenu + # For /etc/os-release, uses CondtionArchitechture= from systemd.unit(5) config INFIX_ARCH string diff --git a/board/common/post-build.sh b/board/common/post-build.sh index 54dced0d..d6b67cdc 100755 --- a/board/common/post-build.sh +++ b/board/common/post-build.sh @@ -7,19 +7,33 @@ if [ -n "${ID_LIKE}" ]; then ID="${ID} ${ID_LIKE}" fi -GIT_VERSION=$(git -C "$BR2_EXTERNAL_INFIX_PATH" describe --always --dirty --tags) +if [ -z "$GIT_VERSION" ]; then + infix_path="$BR2_EXTERNAL_INFIX_PATH" + if [ -n "$INFIX_OEM_PATH" ]; then + # Use version from br2-external OEM:ing Infix + infix_path="$INFIX_OEM_PATH" + fi + GIT_VERSION=$(git -C "$infix_path" describe --always --dirty --tags) +fi + +# Override VERSION in /etc/os-release and filenames for release builds +if [ -n "$INFIX_RELEASE" ]; then + VERSION="$INFIX_RELEASE" +else + VERSION=$GIT_VERSION +fi # This is a symlink to /usr/lib/os-release, so we remove this to keep # original Buildroot information. rm -f "$TARGET_DIR/etc/os-release" { - echo "NAME=\"Infix\"" - echo "VERSION=${GIT_VERSION}" - echo "ID=infix" + echo "NAME=\"$INFIX_NAME\"" + echo "ID=$INFIX_ID" + echo "PRETTY_NAME=\"$INFIX_TAGLINE\"" echo "ID_LIKE=\"${ID}\"" - echo "VERSION_ID=${GIT_VERSION}" - echo "BUILD_ID=\"${NAME} ${VERSION}\"" - echo "PRETTY_NAME=\"Infix by KernelKit\"" + echo "VERSION=\"${VERSION}\"" + echo "VERSION_ID=${VERSION}" + echo "BUILD_ID=\"${GIT_VERSION}\"" if [ "$INFIX_VARIANT_NETCONF" = "y" ]; then echo "VARIANT=\"Managed NETCONF\"" echo "VARIANT_ID=netconf" @@ -28,11 +42,25 @@ rm -f "$TARGET_DIR/etc/os-release" echo "VARIANT_ID=classic" fi echo "ARCHITECTURE=\"${INFIX_ARCH}\"" - echo "HOME_URL=https://github.com/KernelKit" + echo "HOME_URL=$INFIX_HOME" + if [ -n "$INFIX_VENDOR" ]; then + echo "VENDOR_NAME=\"$INFIX_VENDOR\"" + fi + if [ -n "$INFIX_VENDOR_HOME" ]; then + echo "VENDOR_HOME=\"$INFIX_VENDOR_HOME\"" + fi + if [ -n "$INFIX_DOC" ]; then + echo "DOCUMENTATION_URL=\"$INFIX_DOC\"" + fi + if [ -n "$INFIX_SUPPORT" ]; then + echo "SUPPORT_URL=\"$INFIX_SUPPORT\"" + fi + if [ -n "$INFIX_DESC" ]; then + echo "INFIX_DESC=\"$INFIX_DESC\"" + fi } > "$TARGET_DIR/etc/os-release" - -echo "Infix by KernelKit $GIT_VERSION -- $(date +"%b %e %H:%M %Z %Y")" > "$TARGET_DIR/etc/version" +echo "$INFIX_TAGLINE $VERSION -- $(date +"%b %e %H:%M %Z %Y")" > "$TARGET_DIR/etc/version" # Allow pdmenu (setup) and bash to be login shells, bash is added # automatically when selected in menuyconfig, but not when BusyBox diff --git a/doc/branding.md b/doc/branding.md new file mode 100644 index 00000000..fbfa1397 --- /dev/null +++ b/doc/branding.md @@ -0,0 +1,66 @@ +Branding & Releases +=================== + +This document is for projects using Infix as a br2-external, i.e., OEMs. + + +Branding +-------- + +Branding is done in menuconfig, there are several settings affecting +it, most are in the Infix external subsection called "Branding", but +there is also `BR2_TARGET_GENERIC_HOSTNAME`, which deserves a +special mention. + +The hostname is used for the system default `/etc/hostname`, which +is the base name for the "unique:ified" hostname + the last three +octets of the base MAC[^1] address, e.g., `infix-c0-ff-ee`. This in +turn is the hostname that is set at first boot and also advertised +by device discovery protocols like SSDP, mDNS/SD and LLDP. + +See the help texts for the *Infix Branding* settings to understand +which ones are mandatory and which are optional, menuconfig does not +check this for you and you may end up with odd results. + +Verify the result after a build by inspecting: + + - `output/images/*`: names, missing prefix, etc. + - `output/target/etc/os-release`: this file is sourced by + other build scripts, e.g., `mkgns3a.sh`. For reference, see + https://www.freedesktop.org/software/systemd/man/os-release.html + +> **Note:** to get proper GIT revision (hash) from your composed OS, +> remember in menuconfig to set `INFIX_OEM_PATH`. When unset the +> Infix `post-build.sh` script defaults to the Infix base path. The +> revision is stored in the file `/etc/os-release` as BUILD_ID and +> is also in the file `/etc/version`. See below for more info. + +[^1]: The base MAC address is defined in the device's Vital Product + Data (VPD) EEPROM, or similar, which is used by the kernel to + create the system interfaces. This MAC address is usually also + printed on a label on the device. + + +Releases +-------- + +A release build requires the global variable `INFIX_RELEASE` to be set. +It can be derived from GIT, if the source tree is kept in GIT VCS. + +### `INFIX_RELEASE` + +This global variable **must be** a lower-case string (no spaces or +other characters outside of 0–9, a–z, '.', '_' and '-') identifying +the operating system version, excluding any OS name information or +release code name, and suitable for processing by scripts or usage +in generated filenames. + +Used for `VERSION` and `VERSION_ID` in `/etc/os-release` and +generated file names like disk images, etc. + +**Default:** generated using `git describe --always --dirty --tags`, +with an additional `-C $infix_path`. This variable defaults to the +Infix tree and can be changed by setting the menuconfig branding +variable `INFIX_OEM_PATH` to that of the br2-external. It is also +possible to set the `GIT_VERSION` variable in your `post-build.sh` +script to change how the VCS version is extracted.