starlingx/docs
Code Issues Proposed changes

Consolidate build guides into single guide

Browse Source 
R1 and R2 build guides were identified as being nearly identical.
Based on this, they were consolidated into a single guide.

- Updated link to reference consolidated guide
- Updated index page to reference consolidated guide
- Removed old versioned guides
- Basic formatting cleanup (remove $prompts, lists, indentation)

Change-Id: I83aea4d76147fbc56d555dff3ce768737d15c4e2
Signed-off-by: Kristal Dale <kristal.dale@intel.com>
This commit is contained in:
Kristal Dale
2019-10-09 17:15:52 -07:00
parent 3fdb20d65b
commit 4a5f40a03d
4 changed files with 204 additions and 1061 deletions
Download Patch File Download Diff File Expand all files Collapse all files

410
doc/source/contributor/build_guides/r2_release/index.rst → doc/source/contributor/build_guide.rst
View File

@@ -1,9 +1,8 @@
========================== =====================
Build guide StarlingX R2.0 StarlingX Build Guide
========================== =====================
This section describes the steps for building a StarlingX ISO from the R2.0 This section describes the steps for building an ISO image from a StarlingX release.
StarlingX release.
------------ ------------
Requirements Requirements
@@ -15,10 +14,10 @@ Hardware requirements
A workstation computer with: A workstation computer with:
- Processor: x86_64 is the only supported architecture * Processor: x86_64 is the only supported architecture
- Memory: At least 32GB RAM * Memory: At least 32GB RAM
- Hard Disk: 500GB HDD * Hard Disk: 500GB HDD
- Network: Network adapter with active Internet connection * Network: Network adapter with active Internet connection
********************* *********************
Software requirements Software requirements
@@ -26,26 +25,22 @@ Software requirements
A workstation computer with: A workstation computer with:
- Operating System: Ubuntu 16.04 LTS 64-bit * Operating System: Ubuntu 16.04 LTS 64-bit
- Docker * Docker
- Android Repo Tool * Android Repo Tool
- Proxy settings configured (if required) * Proxy settings configured, if required (See
http://lists.starlingx.io/pipermail/starlingx-discuss/2018-July/000136.html for more details)
- See * Public SSH key
http://lists.starlingx.io/pipermail/starlingx-discuss/2018-July/000136.html
for more details
- Public SSH key
----------------------------- -----------------------------
Development environment setup Development environment setup
----------------------------- -----------------------------
This section describes how to set up a StarlingX development system on a This section describes how to set up a StarlingX development system on a
workstation computer. After completing these steps, you can workstation computer. After completing these steps, you can build a StarlingX
build a StarlingX ISO image on the following Linux distribution: ISO image on the following Linux distribution:
- Ubuntu 16.04 LTS 64-bit * Ubuntu 16.04 LTS 64-bit
**************************** ****************************
Update your operating system Update your operating system
@@ -54,100 +49,83 @@ Update your operating system
Before proceeding with the build, ensure your Ubuntu distribution is up to date. Before proceeding with the build, ensure your Ubuntu distribution is up to date.
You first need to update the local database list of available packages: You first need to update the local database list of available packages:
.. code:: sh ::
$ sudo apt-get update sudo apt-get update
****************************************** ******************************************
Installation requirements and dependencies Installation requirements and dependencies
****************************************** ******************************************
^^^^ #. Set up <user>.
User
^^^^
1. Make sure you are a non-root user with sudo enabled when you build the Make sure you are a non-root user with sudo privileges enabled when you build
StarlingX ISO. You also need to either use your existing user or create a the StarlingX ISO.
separate *<user>*:
.. code:: sh Use either your existing user or create a separate *<user>*:
$ sudo useradd -m -d /home/<user> <user> ::
2. Your *<user>* should have sudo privileges: sudo useradd -m -d /home/<user> <user>
sudo sh -c "echo '<user> ALL=(ALL:ALL) ALL' >> /etc/sudoers"
sudo su -c <user>
.. code:: sh
$ sudo sh -c "echo '<user> ALL=(ALL:ALL) ALL' >> /etc/sudoers" #. Set up Git.
$ sudo su -c <user>
^^^ Install the required Git packages on the Ubuntu host system:
Git
^^^
3. Install the required packages on the Ubuntu host system: ::
.. code:: sh sudo apt-get install make git curl
$ sudo apt-get install make git curl Set up your identity in git using your actual name and email address:
4. Make sure to set up your identity using the following two commands. ::
Be sure to provide your actual name and email address:
.. code:: sh git config --global user.name "Name LastName"
git config --global user.email "Email Address"
$ git config --global user.name "Name LastName"
$ git config --global user.email "Email Address"
^^^^^^^^^ #. Install the required Docker CE packages in the Ubuntu host system.
Docker CE
^^^^^^^^^
5. Install the required Docker CE packages in the Ubuntu host system. See See
`Get Docker CE for `Get Docker CE for Ubuntu <https://docs.docker.com/install/linux/docker-ce/ubuntu/#os-requirements>`__ for more information.
Ubuntu <https://docs.docker.com/install/linux/docker-ce/ubuntu/#os-requirements>`__
for more information.
6. Log out and log in to add your *<user>* to the Docker group: Make sure to log out and log in to add your *<user>* to the Docker group:
.. code:: sh ::
$ sudo usermod -aG docker <user> sudo usermod -aG docker <user>
^^^^^^^^^^^^^^^^^ #. Install the Android Repo Tool in the Ubuntu host system.
Android Repo Tool
^^^^^^^^^^^^^^^^^
7. Install the required Android Repo Tool in the Ubuntu host system. Follow Follow the steps in the
the steps in the `Installing `Installing Repo <https://source.android.com/setup/build/downloading#installing-repo>`__
Repo <https://source.android.com/setup/build/downloading#installing-repo>`__
section. section.
********************** **********************
Install public SSH key Install public SSH key
********************** **********************
#. Follow these instructions on GitHub to `Generate a Public SSH Follow these instructions on GitHub to
Key <https://help.github.com/articles/connecting-to-github-with-ssh>`__. `Generate a Public SSH Key <https://help.github.com/articles/connecting-to-github-with-ssh>`__.
Then upload your public key to your GitHub and Gerrit account Then upload your public key to your GitHub and Gerrit account profiles:
profiles:
- `Upload to * `Upload to Github <https://help.github.com/articles/adding-a-new-ssh-key-to-your-github-account>`__
Github <https://help.github.com/articles/adding-a-new-ssh-key-to-your-github-account>`__
- `Upload to * `Upload to Gerrit <https://review.openstack.org/#/settings/ssh-keys>`__
Gerrit <https://review.openstack.org/#/settings/ssh-keys>`__
**************************** ****************************
Create a workspace directory Create a workspace directory
**************************** ****************************
#. Create a *starlingx* workspace directory on your system. Create a *starlingx* workspace directory on your system. Best practices dictate
Best practices dictate creating the workspace directory creating the workspace directory in your $HOME directory:
in your $HOME directory:
.. code:: sh ::
$ mkdir -p $HOME/starlingx/ mkdir -p $HOME/starlingx/
********************* *********************
Install tools project Install tools project
@@ -155,17 +133,17 @@ Install tools project
#. Under your $HOME directory, clone the <tools> project: #. Under your $HOME directory, clone the <tools> project:
.. code:: sh ::
$ cd $HOME cd $HOME
$ git clone https://opendev.org/starlingx/tools.git git clone https://opendev.org/starlingx/tools.git
#. Navigate to the *<$HOME/tools>* project #. Navigate to the *<$HOME/tools>* project
directory: directory:
.. code:: sh ::
$ cd $HOME/tools/ cd $HOME/tools/
----------------------------- -----------------------------
Prepare the base Docker image Prepare the base Docker image
@@ -182,10 +160,10 @@ Configuration values
You can customize values for the StarlingX base Docker image using a You can customize values for the StarlingX base Docker image using a
text-based configuration file named ``localrc``: text-based configuration file named ``localrc``:
- ``HOST_PREFIX`` points to the directory that hosts the 'designer' * ``HOST_PREFIX`` points to the directory that hosts the 'designer'
subdirectory for source code, the 'loadbuild' subdirectory for subdirectory for source code, the 'loadbuild' subdirectory for
the build environment, generated RPMs, and the ISO image. the build environment, generated RPMs, and the ISO image.
- ``HOST_MIRROR_DIR`` points to the directory that hosts the CentOS mirror * ``HOST_MIRROR_DIR`` points to the directory that hosts the CentOS mirror
repository. repository.
^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -194,7 +172,7 @@ localrc configuration file
Create your ``localrc`` configuration file. For example: Create your ``localrc`` configuration file. For example:
.. code:: sh ::
# tbuilder localrc # tbuilder localrc
MYUNAME=<your user name> MYUNAME=<your user name>
@@ -212,7 +190,7 @@ to build the base Docker image.
#. If necessary, you might have to set http/https proxy in your #. If necessary, you might have to set http/https proxy in your
Dockerfile before building the docker image: Dockerfile before building the docker image:
.. code:: sh ::
ENV http_proxy " http://your.actual_http_proxy.com:your_port " ENV http_proxy " http://your.actual_http_proxy.com:your_port "
ENV https_proxy " https://your.actual_https_proxy.com:your_port " ENV https_proxy " https://your.actual_https_proxy.com:your_port "
@@ -221,7 +199,7 @@ to build the base Docker image.
#. The ``tb.sh`` script automates the base Docker image build: #. The ``tb.sh`` script automates the base Docker image build:
.. code:: sh ::
./tb.sh create ./tb.sh create
@@ -237,14 +215,14 @@ this CentOS mirror repository.
Run repository Docker container Run repository Docker container
******************************* *******************************
| Run the following commands under a terminal identified as "**One**": Run the following commands under a terminal identified as "**One**":
#. Navigate to the *$HOME/tools/centos-mirror-tool* project #. Navigate to the *$HOME/tools/centos-mirror-tool* project
directory: directory:
.. code:: sh ::
$ cd $HOME/tools/centos-mirror-tools/ cd $HOME/tools/centos-mirror-tools/
#. Launch the Docker container using the previously created base Docker image #. Launch the Docker container using the previously created base Docker image
*<repository>:<tag>*. As /localdisk is defined as the workdir of the *<repository>:<tag>*. As /localdisk is defined as the workdir of the
@@ -253,9 +231,9 @@ Run repository Docker container
this directory. The container runs from the same directory in which the this directory. The container runs from the same directory in which the
scripts are stored. scripts are stored.
.. code:: sh ::
$ docker run -it --volume $(pwd):/localdisk local/$USER-stx-builder:7.4 bash docker run -it --volume $(pwd):/localdisk local/$USER-stx-builder:7.4 bash
***************** *****************
Download packages Download packages
@@ -266,7 +244,7 @@ Download packages
:: ::
# cd localdisk && bash download_mirror.sh cd localdisk && bash download_mirror.sh
#. Monitor the download of packages until it is complete. When the download #. Monitor the download of packages until it is complete. When the download
is complete, the following message appears: is complete, the following message appears:
@@ -289,8 +267,8 @@ Verify packages
:: ::
# cat logs/*_missing_*.log cat logs/*_missing_*.log
# cat logs/*_failmoved_*.log cat logs/*_failmoved_*.log
#. In case missing or failed packages do exist, which is usually caused by #. In case missing or failed packages do exist, which is usually caused by
network instability (or timeout), you need to download the packages network instability (or timeout), you need to download the packages
@@ -333,17 +311,17 @@ as "**Two**", run the following commands:
#. From terminal identified as "**Two**", create a *mirror/CentOS* #. From terminal identified as "**Two**", create a *mirror/CentOS*
directory under your *starlingx* workspace directory: directory under your *starlingx* workspace directory:
.. code:: sh ::
$ mkdir -p $HOME/starlingx/mirror/CentOS/ mkdir -p $HOME/starlingx/mirror/CentOS/
#. Copy the built CentOS mirror repository built under #. Copy the built CentOS mirror repository built under
*$HOME/tools/centos-mirror-tool* to the *$HOME/starlingx/mirror/* *$HOME/tools/centos-mirror-tool* to the *$HOME/starlingx/mirror/*
workspace directory: workspace directory:
.. code:: sh ::
$ cp -r $HOME/tools/centos-mirror-tools/output/stx-r1/ $HOME/starlingx/mirror/CentOS/ cp -r $HOME/tools/centos-mirror-tools/output/stx-r1/ $HOME/starlingx/mirror/CentOS/
------------------------- -------------------------
@@ -356,33 +334,33 @@ Run building Docker container
#. From the terminal identified as "**Two**", create the workspace folder: #. From the terminal identified as "**Two**", create the workspace folder:
.. code:: sh ::
$ mkdir -p $HOME/starlingx/workspace mkdir -p $HOME/starlingx/workspace
#. Navigate to the *$HOME/tools* project directory: #. Navigate to the *$HOME/tools* project directory:
.. code:: sh ::
$ cd $HOME/tools cd $HOME/tools
#. Verify environment variables: #. Verify environment variables:
.. code:: sh ::
$ bash tb.sh env bash tb.sh env
#. Run the building Docker container: #. Run the building Docker container:
.. code:: sh ::
$ bash tb.sh run bash tb.sh run
#. Execute the buiding Docker container: #. Execute the buiding Docker container:
.. code:: sh ::
$ bash tb.sh exec bash tb.sh exec
********************************* *********************************
Download source code repositories Download source code repositories
@@ -391,48 +369,57 @@ Download source code repositories
#. From the terminal identified as "**Two**", which is now inside the #. From the terminal identified as "**Two**", which is now inside the
building Docker container, start the internal environment: building Docker container, start the internal environment:
.. code:: sh ::
$ eval $(ssh-agent) eval $(ssh-agent)
$ ssh-add ssh-add
#. Use the repo tool to create a local clone of the manifest #. Use the repo tool to create a local clone of the manifest
Git repository based on the "master" branch: Git repository based on the "master" branch:
.. code:: sh ::
$ cd $MY_REPO_ROOT_DIR cd $MY_REPO_ROOT_DIR
$ repo init -u https://opendev.org/starlingx/manifest -m default.xml repo init -u https://opendev.org/starlingx/manifest -m default.xml
Optionally, specify a specific branch to clone, for example the R2.0 release
branch:
::
cd $MY_REPO_ROOT_DIR
repo init -u https://opendev.org/starlingx/manifest -m default.xml -b r/stx.2.0
#. Synchronize the repository: #. Synchronize the repository:
.. code:: sh ::
$ repo sync -j`nproc` repo sync -j`nproc`
#. Create a tarballs repository: #. Create a tarballs repository:
.. code:: sh ::
$ ln -s /import/mirrors/CentOS/stx-r1/CentOS/pike/downloads/ $MY_REPO/stx/ ln -s /import/mirrors/CentOS/stx-r1/CentOS/pike/downloads/ $MY_REPO/stx/
Alternatively, you can run the "populate_downloads.sh" script to copy Alternatively, you can run the "populate_downloads.sh" script to copy
the tarballs instead of using a symlink: the tarballs instead of using a symlink:
.. code:: sh ::
$ populate_downloads.sh /import/mirrors/CentOS/stx-r1/CentOS/pike/ populate_downloads.sh /import/mirrors/CentOS/stx-r1/CentOS/pike/
Outside the container Outside the container
#. From another terminal identified as "**Three**", create mirror binaries: #. From another terminal identified as "**Three**", create mirror binaries:
.. code:: sh ::
$ mkdir -p $HOME/starlingx/mirror/CentOS/stx-installer mkdir -p $HOME/starlingx/mirror/CentOS/stx-installer
$ cp $HOME/starlingx/mirror/CentOS/stx-r1/CentOS/pike/Binary/images/pxeboot/initrd.img $HOME/starlingx/mirror/CentOS/stx-installer/initrd.img cp $HOME/starlingx/mirror/CentOS/stx-r1/CentOS/pike/Binary/images/pxeboot/initrd.img $HOME/starlingx/mirror/CentOS/stx-installer/initrd.img
$ cp $HOME/starlingx/mirror/CentOS/stx-r1/CentOS/pike/Binary/images/pxeboot/vmlinuz $HOME/starlingx/mirror/CentOS/stx-installer/vmlinuz cp $HOME/starlingx/mirror/CentOS/stx-r1/CentOS/pike/Binary/images/pxeboot/vmlinuz $HOME/starlingx/mirror/CentOS/stx-installer/vmlinuz
$ cp $HOME/starlingx/mirror/CentOS/stx-r1/CentOS/pike/Binary/LiveOS/squashfs.img $HOME/starlingx/mirror/CentOS/stx-installer/squashfs.img cp $HOME/starlingx/mirror/CentOS/stx-r1/CentOS/pike/Binary/LiveOS/squashfs.img $HOME/starlingx/mirror/CentOS/stx-installer/squashfs.img
************** **************
Build packages Build packages
@@ -449,15 +436,15 @@ Build packages
#. Update the symbolic links: #. Update the symbolic links:
.. code:: sh ::
$ generate-cgcs-centos-repo.sh /import/mirrors/CentOS/stx-r1/CentOS/pike/ generate-cgcs-centos-repo.sh /import/mirrors/CentOS/stx-r1/CentOS/pike/
#. Build the packages: #. Build the packages:
.. code:: sh ::
$ build-pkgs build-pkgs
#. **Optional!** Generate-Cgcs-Tis-Repo: #. **Optional!** Generate-Cgcs-Tis-Repo:
@@ -467,19 +454,19 @@ Build packages
need to execute the following command after building modified or new need to execute the following command after building modified or new
packages. packages.
.. code:: sh ::
$ generate-cgcs-tis-repo generate-cgcs-tis-repo
------------------- -------------------
Build StarlingX ISO Build StarlingX ISO
------------------- -------------------
#. Build the image: Build the image:
.. code:: sh ::
$ build-iso build-iso
--------------- ---------------
Build installer Build installer
@@ -493,15 +480,15 @@ every time you upgrade the kernel.
After running "build-iso", run: After running "build-iso", run:
.. code:: sh ::
$ build-pkgs --installer build-pkgs --installer
This builds *rpm* and *anaconda* packages. Then run: This builds *rpm* and *anaconda* packages. Then run:
.. code:: sh ::
$ update-pxe-network-installer update-pxe-network-installer
The *update-pxe-network-installer* covers the steps detailed in The *update-pxe-network-installer* covers the steps detailed in
*$MY_REPO/stx/stx-metal/installer/initrd/README*. This script *$MY_REPO/stx/stx-metal/installer/initrd/README*. This script
@@ -532,11 +519,11 @@ Two ways exist for using these files:
Recreate the *pxe-network-installer* package and rebuild the image: Recreate the *pxe-network-installer* package and rebuild the image:
.. code:: sh ::
$ build-pkgs --clean pxe-network-installer build-pkgs --clean pxe-network-installer
$ build-pkgs pxe-network-installer build-pkgs pxe-network-installer
$ build-iso build-iso
Your ISO image should be able to boot. Your ISO image should be able to boot.
@@ -544,13 +531,11 @@ Your ISO image should be able to boot.
Additional notes Additional notes
**************** ****************
- In order to get the first boot working, this complete procedure needs * In order to get the first boot working, this complete procedure needs to be
to be done. However, once the init files are created, these can be done. However, once the init files are created, these can be stored in a shared location where different developers can make use of them. Updating these files
stored in a shared location where different developers can make use is not a frequent task and should be done whenever the kernel is upgraded.
of them. Updating these files is not a frequent task and should be * StarlingX is in active development. Consequently, it is possible that a
done whenever the kernel is upgraded. future version will change to a more generic solution.
- StarlingX is in active development. Consequently, it is possible that in the
future the **0.2** version will change to a more generic solution.
--------------- ---------------
Build avoidance Build avoidance
@@ -560,26 +545,22 @@ Build avoidance
Purpose Purpose
******* *******
Greatly reduce build times after using "repo" to syncronized a local Greatly reduce build times after using "repo" to syncronized a local repository
repository with an upstream source (i.e. "repo sync"). with an upstream source (i.e. "repo sync"). Build avoidance works well for
Build avoidance works well for designers working designers working within a regional office. Starting from a new workspace,
within a regional office. Starting from a new workspace, "build-pkgs" "build-pkgs" typically requires three or more hours to complete. Build avoidance
typically requires three or more hours to complete. Build avoidance
reduces this step to approximately 20 minutes. reduces this step to approximately 20 minutes.
*********** ***********
Limitations Limitations
*********** ***********
- Little or no benefit for designers who refresh a pre-existing * Little or no benefit for designers who refresh a pre-existing workspace at
workspace at least daily (e.g. download_mirror.sh, repo sync, least daily (e.g. download_mirror.sh, repo sync, generate-cgcs-centos-repo.sh, build-pkgs, build-iso). In these cases, an incremental build (i.e. reuse of
generate-cgcs-centos-repo.sh, build-pkgs, build-iso). In these cases, same workspace without a :command:`build-pkgs --clean`) is often just as
an incremental build (i.e. reuse of same workspace without a "build-pkgs efficient.
--clean") is often just as efficient. * Not likely to be useful to solo designers, or teleworkers that wish to compile
- Not likely to be useful to solo designers, or teleworkers that wish on using their home computers. Build avoidance downloads build artifacts from a reference build, and WAN speeds are generally too slow.
to compile on using their home computers. Build avoidance downloads build
artifacts from a reference build, and WAN speeds are generally too
slow.
***************** *****************
Method (in brief) Method (in brief)
@@ -587,27 +568,23 @@ Method (in brief)
#. Reference builds #. Reference builds
- A server in the regional office performs regular (e.g. daily) * A server in the regional office performs regular (e.g. daily) automated
automated builds using existing methods. These builds are called builds using existing methods. These builds are called "reference builds".
"reference builds". * The builds are timestamped and preserved for some time (i.e. a number of weeks).
- The builds are timestamped and preserved for some time (i.e. a * A build CONTEXT, which is a file produced by "build-pkgs" at location
number of weeks). *$MY_WORKSPACE/CONTEXT*, is captured. It is a bash script that can cd to
- A build CONTEXT, which is a file produced by "build-pkgs" each and every Git and checkout the SHA that contributed to the build.
at location *$MY_WORKSPACE/CONTEXT*, is captured. It is a bash script that can * For each package built, a file captures the md5sums of all the source code
cd to each and every Git and checkout the SHA that contributed to inputs required to build that package. These files are also produced by
the build. "build-pkgs" at location *$MY_WORKSPACE//rpmbuild/SOURCES//srpm_reference.md5*.
- For each package built, a file captures the md5sums of all the * All these build products are accessible locally (e.g. a regional office)
source code inputs required to build that package. These files are using "rsync".
also produced by "build-pkgs" at location
*$MY_WORKSPACE//rpmbuild/SOURCES//srpm_reference.md5*.
- All these build products are accessible locally (e.g. a regional
office) using "rsync".
**NOTE:** Other protocols can be added later. **NOTE:** Other protocols can be added later.
#. Designers #. Designers
- Request a build avoidance build. Recommended after you have * Request a build avoidance build. Recommended after you have
done synchronized the repository (i.e. "repo sync"). done synchronized the repository (i.e. "repo sync").
:: ::
@@ -617,11 +594,11 @@ Method (in brief)
populate_downloads.sh populate_downloads.sh
build-pkgs --build-avoidance build-pkgs --build-avoidance
- Use combinations of additional arguments, environment variables, and a * Use combinations of additional arguments, environment variables, and a
configuration file unique to the regional office to specify an URL configuration file unique to the regional office to specify an URL
to the reference builds. to the reference builds.
- Using a configuration file to specify the location of your reference build: * Using a configuration file to specify the location of your reference build:
:: ::
@@ -642,16 +619,15 @@ Method (in brief)
BUILD_AVOIDANCE_DIR="/localdisk/loadbuild/jenkins/StarlingX_Reference_Build" BUILD_AVOIDANCE_DIR="/localdisk/loadbuild/jenkins/StarlingX_Reference_Build"
EOF EOF
- Using command-line arguments to specify the location of your reference * Using command-line arguments to specify the location of your reference
build: build:
:: ::
build-pkgs --build-avoidance --build-avoidance-dir /localdisk/loadbuild/jenkins/StarlingX_Reference_Build --build-avoidance-host stx-builder.mycompany.com --build-avoidance-user jenkins build-pkgs --build-avoidance --build-avoidance-dir /localdisk/loadbuild/jenkins/StarlingX_Reference_Build --build-avoidance-host stx-builder.mycompany.com --build-avoidance-user jenkins
- Prior to your build attempt, you need to accept the host key. * Prior to your build attempt, you need to accept the host key. Doing so
Doing so prevents "rsync" failures on a "yes/no" prompt. prevents "rsync" failures on a "yes/no" prompt. You only have to do this once.
You only have to do this once.
:: ::
@@ -661,56 +637,52 @@ Method (in brief)
fi fi
- "build-pkgs" does the following: * "build-pkgs" does the following:
- From newest to oldest, scans the CONTEXTs of the various * From newest to oldest, scans the CONTEXTs of the various reference builds.
reference builds. Selects the first (i.e. most recent) context that Selects the first (i.e. most recent) context that satisfies the following
satisfies the following requirement: every Git the SHA requirement: every Git the SHA specifies in the CONTEXT is present.
specifies in the CONTEXT is present. * The selected context might be slightly out of date, but not by more than
- The selected context might be slightly out of date, but not by a day. This assumes daily reference builds are run.
more than a day. This assumes daily reference builds are run. * If the context has not been previously downloaded, then download it now.
- If the context has not been previously downloaded, then This means you need to download select portions of the reference build
download it now. This means you need to download select portions of the workspace into the designer's workspace. This includes all the SRPMS,
reference build workspace into the designer's workspace. This RPMS, MD5SUMS, and miscellaneous supporting files. Downloading these files
includes all the SRPMS, RPMS, MD5SUMS, and miscellaneous supporting usually takes about 10 minutes over an office LAN.
files. Downloading these files usually takes about 10 minutes * The designer could have additional commits or uncommitted changes not
over an office LAN. present in the reference builds. Affected packages are identified by the
- The designer could have additional commits or uncommitted changes differing md5sum's. In these cases, the packages are re-built. Re-builds
not present in the reference builds. Affected packages are usually take five or more minutes, depending on the packages that have changed.
identified by the differing md5sum's. In these cases, the packages
are re-built. Re-builds usually take five or more minutes,
depending on the packages that have changed.
- What if no valid reference build is found? Then build-pkgs will fall * What if no valid reference build is found? Then build-pkgs will fall back
back to a regular build. to a regular build.
**************** ****************
Reference builds Reference builds
**************** ****************
- The regional office implements an automated build that pulls the * The regional office implements an automated build that pulls the latest
latest StarlingX software and builds it on a regular basis (e.g. StarlingX software and builds it on a regular basis (e.g. daily builds).
daily builds). Jenkins, cron, or similar tools can trigger these builds. Jenkins, cron, or similar tools can trigger these builds.
- Each build is saved to a unique directory, and preserved for a time * Each build is saved to a unique directory, and preserved for a time that is
that is reflective of how long a designer might be expected to work reflective of how long a designer might be expected to work on a private branch
on a private branch without syncronizing with the master branch. without syncronizing with the master branch. This takes about two weeks.
This takes about two weeks.
- The *MY_WORKSPACE* directory for the build shall have a common root * The *MY_WORKSPACE* directory for the build shall have a common root
directory, and a leaf directory that is a sortable time stamp. The directory, and a leaf directory that is a sortable time stamp. The
suggested format is *YYYYMMDDThhmmss*. suggested format is *YYYYMMDDThhmmss*.
.. code:: sh ::
$ sudo apt-get update sudo apt-get update
BUILD_AVOIDANCE_DIR="/localdisk/loadbuild/jenkins/StarlingX_Reference_Build" BUILD_AVOIDANCE_DIR="/localdisk/loadbuild/jenkins/StarlingX_Reference_Build"
BUILD_TIMESTAMP=$(date -u '+%Y%m%dT%H%M%SZ') BUILD_TIMESTAMP=$(date -u '+%Y%m%dT%H%M%SZ')
MY_WORKSPACE=${BUILD_AVOIDANCE_DIR}/${BUILD_TIMESTAMP} MY_WORKSPACE=${BUILD_AVOIDANCE_DIR}/${BUILD_TIMESTAMP}
- Designers can access all build products over the internal network of * Designers can access all build products over the internal network of the
the regional office. The current prototype employs "rsync". Other regional office. The current prototype employs "rsync". Other protocols that
protocols that can efficiently share, copy, or transfer large directories can efficiently share, copy, or transfer large directories of content can be
of content can be added as needed. added as needed.
^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^
Advanced usage Advanced usage

828
doc/source/contributor/build_guides/r1_release/index.rst
View File

@@ -1,828 +0,0 @@
==========================
Build guide StarlingX R1.0
==========================
This section describes the steps for building a StarlingX ISO from the R1.0
StarlingX release.
------------
Requirements
------------
The recommended minimum requirements include:
*********************
Hardware requirements
*********************
A workstation computer with:
- Processor: x86_64 is the only supported architecture
- Memory: At least 32GB RAM
- Hard Disk: 500GB HDD
- Network: Network adapter with active Internet connection
*********************
Software requirements
*********************
A workstation computer with:
- Operating System: Ubuntu 16.04 LTS 64-bit
- Docker
- Android Repo Tool
- Proxy settings configured (if required)
- See
http://lists.starlingx.io/pipermail/starlingx-discuss/2018-July/000136.html
for more details
- Public SSH key
-----------------------------
Development environment setup
-----------------------------
This section describes how to set up a StarlingX development system on a
workstation computer. After completing these steps, you can
build a StarlingX ISO image on the following Linux distribution:
- Ubuntu 16.04 LTS 64-bit
****************************
Update your operating system
****************************
Before proceeding with the build, ensure your Ubuntu distribution is up to date.
You first need to update the local database list of available packages:
.. code:: sh
$ sudo apt-get update
******************************************
Installation requirements and dependencies
******************************************
^^^^
User
^^^^
1. Make sure you are a non-root user with sudo enabled when you build the
StarlingX ISO. You also need to either use your existing user or create a
separate *<user>*:
.. code:: sh
$ sudo useradd -m -d /home/<user> <user>
2. Your *<user>* should have sudo privileges:
.. code:: sh
$ sudo sh -c "echo '<user> ALL=(ALL:ALL) ALL' >> /etc/sudoers"
$ sudo su -c <user>
^^^
Git
^^^
3. Install the required packages on the Ubuntu host system:
.. code:: sh
$ sudo apt-get install make git curl
4. Make sure to set up your identity using the following two commands.
Be sure to provide your actual name and email address:
.. code:: sh
$ git config --global user.name "Name LastName"
$ git config --global user.email "Email Address"
^^^^^^^^^
Docker CE
^^^^^^^^^
5. Install the required Docker CE packages in the Ubuntu host system. See
`Get Docker CE for
Ubuntu <https://docs.docker.com/install/linux/docker-ce/ubuntu/#os-requirements>`__
for more information.
6. Log out and log in to add your *<user>* to the Docker group:
.. code:: sh
$ sudo usermod -aG docker <user>
^^^^^^^^^^^^^^^^^
Android Repo Tool
^^^^^^^^^^^^^^^^^
7. Install the required Android Repo Tool in the Ubuntu host system. Follow
the steps in the `Installing
Repo <https://source.android.com/setup/build/downloading#installing-repo>`__
section.
**********************
Install public SSH key
**********************
#. Follow these instructions on GitHub to `Generate a Public SSH
Key <https://help.github.com/articles/connecting-to-github-with-ssh>`__.
Then upload your public key to your GitHub and Gerrit account
profiles:
- `Upload to
Github <https://help.github.com/articles/adding-a-new-ssh-key-to-your-github-account>`__
- `Upload to
Gerrit <https://review.openstack.org/#/settings/ssh-keys>`__
****************************
Create a workspace directory
****************************
#. Create a *starlingx* workspace directory on your system.
Best practices dictate creating the workspace directory
in your $HOME directory:
.. code:: sh
$ mkdir -p $HOME/starlingx/
*************************
Install stx-tools project
*************************
#. Under your $HOME directory, clone the <stx-tools> project:
.. code:: sh
$ cd $HOME
$ git clone https://git.starlingx.io/stx-tools
#. Navigate to the *<$HOME/stx-tools>* project
directory:
.. code:: sh
$ cd $HOME/stx-tools/
-----------------------------
Prepare the base Docker image
-----------------------------
StarlingX base Docker image handles all steps related to StarlingX ISO
creation. This section describes how to customize the base Docker image
building process.
********************
Configuration values
********************
You can customize values for the StarlingX base Docker image using a
text-based configuration file named ``localrc``:
- ``HOST_PREFIX`` points to the directory that hosts the 'designer'
subdirectory for source code, the 'loadbuild' subdirectory for
the build environment, generated RPMs, and the ISO image.
- ``HOST_MIRROR_DIR`` points to the directory that hosts the CentOS mirror
repository.
^^^^^^^^^^^^^^^^^^^^^^^^^^
localrc configuration file
^^^^^^^^^^^^^^^^^^^^^^^^^^
Create your ``localrc`` configuration file. For example:
.. code:: sh
# tbuilder localrc
MYUNAME=<your user name>
PROJECT=starlingx
HOST_PREFIX=$HOME/starlingx/workspace
HOST_MIRROR_DIR=$HOME/starlingx/mirror
***************************
Build the base Docker image
***************************
Once the ``localrc`` configuration file has been customized, it is time
to build the base Docker image.
#. If necessary, you might have to set http/https proxy in your
Dockerfile before building the docker image:
.. code:: sh
ENV http_proxy " http://your.actual_http_proxy.com:your_port "
ENV https_proxy " https://your.actual_https_proxy.com:your_port "
ENV ftp_proxy " http://your.actual_ftp_proxy.com:your_port "
RUN echo " proxy=http://your-proxy.com:port " >> /etc/yum.conf
#. The ``tb.sh`` script automates the Base Docker image build:
.. code:: sh
./tb.sh create
----------------------------------
Build the CentOS mirror repository
----------------------------------
The creation of the StarlingX ISO relies on a repository of RPM Binaries,
RPM Sources, and Tar Compressed files. This section describes how to build
this CentOS mirror repository.
*******************************
Run repository Docker container
*******************************
| Run the following commands under a terminal identified as "**One**":
#. Navigate to the *$HOME/stx-tools/centos-mirror-tool* project
directory:
.. code:: sh
$ cd $HOME/stx-tools/centos-mirror-tools/
#. Launch the Docker container using the previously created base Docker image
*<repository>:<tag>*. As /localdisk is defined as the workdir of the
container, you should use the same folder name to define the volume.
The container starts to run and populate 'logs' and 'output' folders in
this directory. The container runs from the same directory in which the
scripts are stored.
.. code:: sh
$ docker run -it --volume $(pwd):/localdisk local/$USER-stx-builder:7.4 bash
*****************
Download packages
*****************
#. Inside the Docker container, enter the following commands to download
the required packages to populate the CentOS mirror repository:
::
# cd localdisk && bash download_mirror.sh
#. Monitor the download of packages until it is complete. When the download
is complete, the following message appears:
::
totally 17 files are downloaded!
step #3: done successfully
IMPORTANT: The following 3 files are just bootstrap versions. Based on them, the workable images
for StarlingX could be generated by running "update-pxe-network-installer" command after "build-iso"
- out/stx-r1/CentOS/pike/Binary/LiveOS/squashfs.img
- out/stx-r1/CentOS/pike/Binary/images/pxeboot/initrd.img
- out/stx-r1/CentOS/pike/Binary/images/pxeboot/vmlinuz
***************
Verify packages
***************
#. Verify no missing or failed packages exist:
::
# cat logs/*_missing_*.log
# cat logs/*_failmove_*.log
#. In case missing or failed packages do exist, which is usually caused by
network instability (or timeout), you need to download the packages
manually.
Doing so assures you get all RPMs listed in
*rpms_3rdparties.lst*/*rpms_centos.lst*/*rpms_centos3rdparties.lst*.
******************
Packages structure
******************
The following is a general overview of the packages structure resulting
from downloading the packages:
::
/home/<user>/stx-tools/centos-mirror-tools/output
└── stx-r1
└── CentOS
└── pike
├── Binary
│   ├── EFI
│   ├── images
│   ├── isolinux
│   ├── LiveOS
│   ├── noarch
│   └── x86_64
├── downloads
│   ├── integrity
│   └── puppet
└── Source
*******************************
Create CentOS mirror repository
*******************************
Outside your Repository Docker container, in another terminal identified
as "**Two**", run the following commands:
#. From terminal identified as "**Two**", create a *mirror/CentOS*
directory under your *starlingx* workspace directory:
.. code:: sh
$ mkdir -p $HOME/starlingx/mirror/CentOS/
#. Copy the built CentOS Mirror Repository built under
*$HOME/stx-tools/centos-mirror-tool* to the *$HOME/starlingx/mirror/*
workspace directory:
.. code:: sh
$ cp -r $HOME/stx-tools/centos-mirror-tools/output/stx-r1/ $HOME/starlingx/mirror/CentOS/
-------------------------
Create StarlingX packages
-------------------------
*****************************
Run building Docker container
*****************************
#. From the terminal identified as "**Two**", create the workspace folder:
.. code:: sh
$ mkdir -p $HOME/starlingx/workspace
#. Navigate to the *$HOME/stx-tools* project directory:
.. code:: sh
$ cd $HOME/stx-tools
#. Verify environment variables:
.. code:: sh
$ bash tb.sh env
#. Run the building Docker container:
.. code:: sh
$ bash tb.sh run
#. Execute the buiding Docker container:
.. code:: sh
$ bash tb.sh exec
*********************************
Download source code repositories
*********************************
#. From the terminal identified as "**Two**", which is now inside the
Building Docker container, start the internal environment:
.. code:: sh
$ eval $(ssh-agent)
$ ssh-add
#. Use the repo tool to create a local clone of the stx-manifest
Git repository based on the "r/2018.10" branch:
.. code:: sh
$ cd $MY_REPO_ROOT_DIR
$ repo init -u https://git.starlingx.io/stx-manifest -m default.xml -b r/2018.10
#. Synchronize the repository:
.. code:: sh
$ repo sync -j`nproc`
#. Create a tarballs repository:
.. code:: sh
$ ln -s /import/mirrors/CentOS/stx-r1/CentOS/pike/downloads/ $MY_REPO/stx/
Alternatively, you can run the "populate_downloads.sh" script to copy
the tarballs instead of using a symlink:
.. code:: sh
$ populate_downloads.sh /import/mirrors/CentOS/stx-r1/CentOS/pike/
Outside the container
#. From another terminal identified as "**Three**", create mirror binaries:
.. code:: sh
$ mkdir -p $HOME/starlingx/mirror/CentOS/stx-installer
$ cp $HOME/starlingx/mirror/CentOS/stx-r1/CentOS/pike/Binary/images/pxeboot/initrd.img $HOME/starlingx/mirror/CentOS/stx-installer/initrd.img
$ cp $HOME/starlingx/mirror/CentOS/stx-r1/CentOS/pike/Binary/images/pxeboot/vmlinuz $HOME/starlingx/mirror/CentOS/stx-installer/vmlinuz
$ cp $HOME/starlingx/mirror/CentOS/stx-r1/CentOS/pike/Binary/LiveOS/squashfs.img $HOME/starlingx/mirror/CentOS/stx-installer/squashfs.img
**************
Build packages
**************
#. Go back to the terminal identified as "**Two**", which is the Building Docker container.
#. **Temporal!** Build-Pkgs Errors. Be prepared to have some missing /
corrupted rpm and tarball packages generated during
`Build the CentOS Mirror Repository`_, which will cause the next step
to fail. If that step does fail, manually download those missing /
corrupted packages.
#. Update the symbolic links:
.. code:: sh
$ generate-cgcs-centos-repo.sh /import/mirrors/CentOS/stx-r1/CentOS/pike/
#. Build the packages:
.. code:: sh
$ build-pkgs
#. **Optional!** Generate-Cgcs-Tis-Repo:
While this step is optional, it improves performance on subsequent
builds. The cgcs-tis-repo has the dependency information that
sequences the build order. To generate or update the information, you
need to execute the following command after building modified or new
packages.
.. code:: sh
$ generate-cgcs-tis-repo
-------------------
Build StarlingX ISO
-------------------
#. Build the image:
.. code:: sh
$ build-iso
---------------
Build installer
---------------
To get your StarlingX ISO ready to use, you must create the initialization
files used to boot the ISO, additional controllers, and compute nodes.
**NOTE:** You only need this procedure during your first build and
every time you upgrade the kernel.
After running "build-iso", run:
.. code:: sh
$ build-pkgs --installer
This builds *rpm* and *anaconda* packages. Then run:
.. code:: sh
$ update-pxe-network-installer
The *update-pxe-network-installer* covers the steps detailed in
*$MY_REPO/stx/stx-metal/installer/initrd/README*. This script
creates three files on
*/localdisk/loadbuild/pxe-network-installer/output*.
::
new-initrd.img
new-squashfs.img
new-vmlinuz
Rename the files as follows:
::
initrd.img
squashfs.img
vmlinuz
Two ways exist for using these files:
#. Store the files in the */import/mirror/CentOS/stx-installer/* folder
for future use.
#. Store the files in an arbitrary location and modify the
*$MY_REPO/stx/stx-metal/installer/pxe-network-installer/centos/build_srpm.data*
file to point to these files.
Recreate the *pxe-network-installer* package and rebuild the image:
.. code:: sh
$ build-pkgs --clean pxe-network-installer
$ build-pkgs pxe-network-installer
$ build-iso
Your ISO image should be able to boot.
****************
Additional notes
****************
- In order to get the first boot working, this complete procedure needs
to be done. However, once the init files are created, these can be
stored in a shared location where different developers can make use
of them. Updating these files is not a frequent task and should be
done whenever the kernel is upgraded.
- StarlingX is in active development. Consequently, it is possible that in the
future the **0.2** version will change to a more generic solution.
---------------
Build avoidance
---------------
*******
Purpose
*******
Greatly reduce build times after using "repo" to syncronized a local
repository with an upstream source (i.e. "repo sync").
Build avoidance works well for designers working
within a regional office. Starting from a new workspace, "build-pkgs"
typically requires three or more hours to complete. Build avoidance
reduces this step to approximately 20 minutes.
***********
Limitations
***********
- Little or no benefit for designers who refresh a pre-existing
workspace at least daily (e.g. download_mirror.sh, repo sync,
generate-cgcs-centos-repo.sh, build-pkgs, build-iso). In these cases,
an incremental build (i.e. reuse of same workspace without a "build-pkgs
--clean") is often just as efficient.
- Not likely to be useful to solo designers, or teleworkers that wish
to compile on using their home computers. Build avoidance downloads build
artifacts from a reference build, and WAN speeds are generally too
slow.
*****************
Method (in brief)
*****************
#. Reference Builds
- A server in the regional office performs regular (e.g. daily)
automated builds using existing methods. These builds are called
"reference builds".
- The builds are timestamped and preserved for some time (i.e. a
number of weeks).
- A build CONTEXT, which is a file produced by "build-pkgs"
at location *$MY_WORKSPACE/CONTEXT*, is captured. It is a bash script that can
cd to each and every Git and checkout the SHA that contributed to
the build.
- For each package built, a file captures the md5sums of all the
source code inputs required to build that package. These files are
also produced by "build-pkgs" at location
*$MY_WORKSPACE//rpmbuild/SOURCES//srpm_reference.md5*.
- All these build products are accessible locally (e.g. a regional
office) using "rsync".
**NOTE:** Other protocols can be added later.
#. Designers
- Request a build avoidance build. Recommended after you have
done synchronized the repository (i.e. "repo sync").
::
repo sync
generate-cgcs-centos-repo.sh
populate_downloads.sh
build-pkgs --build-avoidance
- Use combinations of additional arguments, environment variables, and a
configuration file unique to the regional office to specify an URL
to the reference builds.
- Using a configuration file to specify the location of your reference build:
::
mkdir -p $MY_REPO/local-build-data
cat <<- EOF > $MY_REPO/local-build-data/build_avoidance_source
# Optional, these are already the default values.
BUILD_AVOIDANCE_DATE_FORMAT="%Y%m%d"
BUILD_AVOIDANCE_TIME_FORMAT="%H%M%S"
BUILD_AVOIDANCE_DATE_TIME_DELIM="T"
BUILD_AVOIDANCE_DATE_TIME_POSTFIX="Z"
BUILD_AVOIDANCE_DATE_UTC=1
BUILD_AVOIDANCE_FILE_TRANSFER="rsync"
# Required, unique values for each regional office
BUILD_AVOIDANCE_USR="jenkins"
BUILD_AVOIDANCE_HOST="stx-builder.mycompany.com"
BUILD_AVOIDANCE_DIR="/localdisk/loadbuild/jenkins/StarlingX_Reference_Build"
EOF
- Using command-line arguments to specify the location of your reference
build:
::
build-pkgs --build-avoidance --build-avoidance-dir /localdisk/loadbuild/jenkins/StarlingX_Reference_Build --build-avoidance-host stx-builder.mycompany.com --build-avoidance-user jenkins
- Prior to your build attempt, you need to accept the host key.
Doing so prevents "rsync" failures on a "yes/no" prompt.
You only have to do this once.
::
grep -q $BUILD_AVOIDANCE_HOST $HOME/.ssh/known_hosts
if [ $? != 0 ]; then
ssh-keyscan $BUILD_AVOIDANCE_HOST >> $HOME/.ssh/known_hosts
fi
- "build-pkgs" does the following:
- From newest to oldest, scans the CONTEXTs of the various
reference builds. Selects the first (i.e. most recent) context that
satisfies the following requirement: every Git the SHA
specifies in the CONTEXT is present.
- The selected context might be slightly out of date, but not by
more than a day. This assumes daily reference builds are run.
- If the context has not been previously downloaded, then
download it now. This means you need to download select portions of the
reference build workspace into the designer's workspace. This
includes all the SRPMS, RPMS, MD5SUMS, and miscellaneous supporting
files. Downloading these files usually takes about 10 minutes
over an office LAN.
- The designer could have additional commits or uncommitted changes
not present in the reference builds. Affected packages are
identified by the differing md5sum's. In these cases, the packages
are re-built. Re-builds usually take five or more minutes,
depending on the packages that have changed.
- What if no valid reference build is found? Then build-pkgs will fall
back to a regular build.
****************
Reference builds
****************
- The regional office implements an automated build that pulls the
latest StarlingX software and builds it on a regular basis (e.g.
daily builds). Jenkins, cron, or similar tools can trigger these builds.
- Each build is saved to a unique directory, and preserved for a time
that is reflective of how long a designer might be expected to work
on a private branch without syncronizing with the master branch.
This takes about two weeks.
- The *MY_WORKSPACE* directory for the build shall have a common root
directory, and a leaf directory that is a sortable time stamp. The
suggested format is *YYYYMMDDThhmmss*.
.. code:: sh
$ sudo apt-get update
BUILD_AVOIDANCE_DIR="/localdisk/loadbuild/jenkins/StarlingX_Reference_Build"
BUILD_TIMESTAMP=$(date -u '+%Y%m%dT%H%M%SZ')
MY_WORKSPACE=${BUILD_AVOIDANCE_DIR}/${BUILD_TIMESTAMP}
- Designers can access all build products over the internal network of
the regional office. The current prototype employs "rsync". Other
protocols that can efficiently share, copy, or transfer large directories
of content can be added as needed.
^^^^^^^^^^^^^^
Advanced usage
^^^^^^^^^^^^^^
Can the reference build itself use build avoidance? Yes it can.
Can it reference itself? Yes it can.
In both these cases, caution is advised. To protect against any possible
'divergence from reality', you should limit how many steps you remove
a build avoidance build from a full build.
Suppose we want to implement a self-referencing daily build in an
environment where a full build already occurs every Saturday.
To protect ourselves from a
build failure on Saturday we also want a limit of seven days since
the last full build. Your build script might look like this ...
::
...
BUILD_AVOIDANCE_DIR="/localdisk/loadbuild/jenkins/StarlingX_Reference_Build"
BUILD_AVOIDANCE_HOST="stx-builder.mycompany.com"
FULL_BUILD_DAY="Saturday"
MAX_AGE_DAYS=7
LAST_FULL_BUILD_LINK="$BUILD_AVOIDANCE_DIR/latest_full_build"
LAST_FULL_BUILD_DAY=""
NOW_DAY=$(date -u "+%A")
BUILD_TIMESTAMP=$(date -u '+%Y%m%dT%H%M%SZ')
MY_WORKSPACE=${BUILD_AVOIDANCE_DIR}/${BUILD_TIMESTAMP}
# update software
repo init -u ${BUILD_REPO_URL} -b ${BUILD_BRANCH}
repo sync --force-sync
$MY_REPO_ROOT_DIR/stx-tools/toCOPY/generate-cgcs-centos-repo.sh
$MY_REPO_ROOT_DIR/stx-tools/toCOPY/populate_downloads.sh
# User can optionally define BUILD_METHOD equal to one of 'FULL', 'AVOIDANCE', or 'AUTO'
# Sanitize BUILD_METHOD
if [ "$BUILD_METHOD" != "FULL" ] && [ "$BUILD_METHOD" != "AVOIDANCE" ]; then
BUILD_METHOD="AUTO"
fi
# First build test
if [ "$BUILD_METHOD" != "FULL" ] && [ ! -L $LAST_FULL_BUILD_LINK ]; then
echo "latest_full_build symlink missing, forcing full build"
BUILD_METHOD="FULL"
fi
# Build day test
if [ "$BUILD_METHOD" == "AUTO" ] && [ "$NOW_DAY" == "$FULL_BUILD_DAY" ]; then
echo "Today is $FULL_BUILD_DAY, forcing full build"
BUILD_METHOD="FULL"
fi
# Build age test
if [ "$BUILD_METHOD" != "FULL" ]; then
LAST_FULL_BUILD_DATE=$(basename $(readlink $LAST_FULL_BUILD_LINK) | cut -d '_' -f 1)
LAST_FULL_BUILD_DAY=$(date -d $LAST_FULL_BUILD_DATE "+%A")
AGE_SECS=$(( $(date "+%s") - $(date -d $LAST_FULL_BUILD_DATE "+%s") ))
AGE_DAYS=$(( $AGE_SECS/60/60/24 ))
if [ $AGE_DAYS -ge $MAX_AGE_DAYS ]; then
echo "Haven't had a full build in $AGE_DAYS days, forcing full build"
BUILD_METHOD="FULL"
fi
BUILD_METHOD="AVOIDANCE"
fi
#Build it
if [ "$BUILD_METHOD" == "FULL" ]; then
build-pkgs --no-build-avoidance
else
build-pkgs --build-avoidance --build-avoidance-dir $BUILD_AVOIDANCE_DIR --build-avoidance-host $BUILD_AVOIDANCE_HOST --build-avoidance-user $USER
fi
if [ $? -ne 0 ]; then
echo "Build failed in build-pkgs"
exit 1
fi
build-iso
if [ $? -ne 0 ]; then
echo "Build failed in build-iso"
exit 1
fi
if [ "$BUILD_METHOD" == "FULL" ]; then
# A successful full build. Set last full build symlink.
if [ -L $LAST_FULL_BUILD_LINK ]; then
rm -rf $LAST_FULL_BUILD_LINK
fi
ln -sf $MY_WORKSPACE $LAST_FULL_BUILD_LINK
fi
...
A final note....
To use the full build day as your avoidance build reference point,
modify the "build-pkgs" commands above to use "--build-avoidance-day ",
as shown in the following two examples:
::
build-pkgs --build-avoidance --build-avoidance-dir $BUILD_AVOIDANCE_DIR --build-avoidance-host $BUILD_AVOIDANCE_HOST --build-avoidance-user $USER --build-avoidance-day $FULL_BUILD_DAY
# Here is another example with a bit more shuffling of the above script.
build-pkgs --build-avoidance --build-avoidance-dir $BUILD_AVOIDANCE_DIR --build-avoidance-host $BUILD_AVOIDANCE_HOST --build-avoidance-user $USER --build-avoidance-day $LAST_FULL_BUILD_DAY
The advantage is that our build is never more than one step removed
from a full build. This assumes the full build was successful.
The disadvantage is that by the end of the week, the reference build is getting
rather old. During active weeks, build times could approach build times for
full builds.

7
doc/source/contributor/index.rst
View File

@@ -33,14 +33,13 @@ For information on the StarlingX development process, refer to the following gui
Build StarlingX Build StarlingX
--------------- ---------------
For instructions on how to build StarlingX, refer to the following guides (build Refer to the StarlingX Build Guide for instructions on how to build a StarlingX
guides for StarlingX are release-specific). ISO image.
.. toctree:: .. toctree::
:maxdepth: 1 :maxdepth: 1
build_guides/r2_release/index build_guide
build_guides/r1_release/index
-------------------- --------------------
Additional resources Additional resources

2
doc/source/deploy_install_guides/r1_release/index.rst
View File

@@ -242,7 +242,7 @@ Unload firewall and disable firewall on boot:
Getting the StarlingX ISO image Getting the StarlingX ISO image
------------------------------- -------------------------------
Follow the instructions from the :doc:`/contributor/build_guides/r1_release/index` to build a Follow the instructions from the :doc:`/contributor/build_guide` to build a
StarlingX ISO image. StarlingX ISO image.
********** **********