Merge pull request #182 from OnionIoT/content/build-pkg-fw-updates

greenbreakfast · web-flow · commit 3b2eb9471d41 · 2024-11-19T13:21:52.000-05:00
Update docker image used in compile package and build firmware articles
diff --git a/docs/firmware/_build-env-notes.mdx b/docs/firmware/_build-env-notes.mdx
@@ -12,4 +12,12 @@ import WslNote from './_wsl-note.mdx';
 <WslNote/>
 
 
-**The method recommended by Onion is to use Ubuntu 22.04 Linux in a Docker container.** Using Docker provides isolation, which helps prevent dependency conflicts with existing software on the host system and ensures a clean, reproducible development environment.
+**The method recommended by Onion is to use Linux in a Docker container.** Using Docker provides isolation, which helps prevent dependency conflicts with existing software on the host system and ensures a clean, reproducible development environment.
+
+**Onion recommends using the `onion/openwrt-builder` Docker image.** This Docker image is based on Ubuntu 22.04 and has all of the [software packages required to use the OpenWRT build tools](https://openwrt.org/docs/guide-developer/toolchain/install-buildsystem#debianubuntumint) already installed. 
+
+:::tip
+
+For those new to Docker, see [Docker's installation guide](https://docs.docker.com/desktop/) and the manual on [running a Docker container](https://docs.docker.com/engine/reference/run).
+
+:::
diff --git a/docs/firmware/_docker-pull-instructions.mdx b/docs/firmware/_docker-pull-instructions.mdx
@@ -0,0 +1,11 @@
+To download the `onion/openwrt-builder` Docker image, make sure Docker is installed and running, and run the following command:
+
+```
+docker pull onion/openwrt-builder
+```
+
+:::note Only needs to be done once
+
+It might take a few minutes to download the Docker image depending on your internet connection. After the image downloads, you won't need to download it again and this step can be skipped next time.
+
+:::
diff --git a/docs/firmware/_docker-start-instructions.mdx b/docs/firmware/_docker-start-instructions.mdx
@@ -1,13 +1,7 @@
-:::tip
-
-For those new to Docker, see [Docker's installation guide](https://docs.docker.com/desktop/) and the manual on [running a Docker container](https://docs.docker.com/engine/reference/run).
-
-:::
-
-To start a Docker container running Ubuntu 22.04, make sure Docker is installed and running, and then run the following command:
+To start a Docker container based on the `onion/openwrt-builder` image run the following command:
 
 ```
-docker run -it ubuntu:22.04 /bin/bash
+docker run -it onion/openwrt-builder /bin/bash
 ```
 
 :::info Macs with Apple Silicon
@@ -16,4 +10,13 @@ The OpenWRT build system, SDK, and Image Builder expect an x86_64 processor arch
 
 Some users have reported successful compilation if Rosetta for x86/amd64 emulation on Apple Silicon is enabled in Docker. 
 
-:::
+:::
+
+You should see something similar to:
+
+```shell
+~ docker run -it onion/openwrt-builder /bin/bash
+root@385d649fdab7:~#
+```
+
+You are now inside the Docker container.
diff --git a/docs/firmware/_install-deps.mdx b/docs/firmware/_install-deps.mdx
@@ -1,3 +1,5 @@
+<!-- NO LONGER USED! -->
+
 When using Ubuntu 22.04 Linux or newer, you need to install the software packages required to use the OpenWRT build tools. These can be installed using the packager manager.
 
 :::tip
diff --git a/docs/firmware/how-to-build-firmware.md b/docs/firmware/how-to-build-firmware.md
@@ -84,28 +84,34 @@ import BuildEnvNotes from './_build-env-notes.mdx';
 
 <BuildEnvNotes tool="Image Builder" />
 
-#### 1. Start your Docker container
+#### Step 1: Pull the Docker Image
 
-import DockerInstructions from './_docker-instructions.mdx';
+import DockerPullInstructions from './_docker-pull-instructions.mdx'; 
 
-<DockerInstructions/>
+<DockerPullInstructions/>
 
-#### 2. Install software dependencies
+#### Step 2: Start your Docker Container
 
-import InstallDeps from './_install-deps.mdx';
+import DockerStartInstructions from './_docker-start-instructions.mdx'; 
 
-<InstallDeps/>
+<DockerStartInstructions/>
 
-#### 3. Clone the OnionIoT/openwrt-imagebuilder-wrapper repo
+#### Step 3: Clone the OnionIoT/openwrt-imagebuilder-wrapper repo
 
 This repository is set up to build OpenWRT firmware for the Onion Omega2 and Omega2+. 
 
-To clone the openwrt-imagebuilder-wrapper repo, issue the following command:
+To clone the **openwrt-imagebuilder-wrapper** repo in the Docker container, run the following command:
 
 ```Shell
 git clone https://github.com/OnionIoT/openwrt-imagebuilder-wrapper.git
 ``` 
 
+When the repo is cloned, enter the directory:
+
+```Shell
+cd openwrt-imagebuilder-wrapper
+``` 
+
 ### Customizing the firmware image
 
 The firmware image specifications are defined in the `profile` configuration file. 
@@ -174,25 +180,29 @@ After completing this step, the OpenWRT Image Builder will download and is set u
 
 The following steps show you how to build a firmware image.
 
-#### 1. Run the build script
+#### Step 1: Run the build script
 
 To build the firmware image(s), run the following command:
 
 ```Shell
 bash onion_buildenv build_all_firmware
 ```
 
-The build should take less than 5 minutes.
+The build should take **about 2 minutes.** It might be more or less depending on the CPU performance of your development computer.
 
-#### 2. Locate the compiled firmware image
+#### Step 2: Locate the compiled firmware image
 
 Compiled firmware images are in the `output` directory. 
 
 The firmware images are named based on the device model name, the OpenWRT version number specified in the `profile` file, and the date of the build: `<BUILD_MODEL>-<OPENWRT_VERSION>-<BUILD_DATE>.bin` .
 
-For example:
+##### For example
+
+For an Omega2+ device, with:
+- `OPENWRT_VERSION="23.05.3"` set in the `profile` config file
+- built on May 31, 2024
 
-For an Omega2+ device, with OPENWRT_VERSION="23.05.3" set in the `profile` config file and built on May 31, 2024. The firmware image name will be `onion_omega2p-23.05.3-20240531.bin`. 
+The firmware image name will be `onion_omega2p-23.05.3-20240531.bin`. 
 
 <!-- NOTE: Ok to keep OpenWRT release numbers hard-coded in this section -->
 
diff --git a/docs/packages/compile-package.md b/docs/packages/compile-package.md
@@ -37,51 +37,59 @@ Onion's OpenWRT SDK wrapper is the recommended method to build packages for Omeg
 
 The system set up instructions are the same for compiling packages in **development** and in **production**. The configuration and compilation steps differ between the two environments.
 
-**Step 1: Set up local environment**
+#### A Note on the Build Environment
 
 import BuildEnvNotes from '../firmware/_build-env-notes.mdx';
 
 <BuildEnvNotes tool="OpenWRT SDK" />
 
-**Step 2: Start your Docker Container**
+#### Step 1: Pull the Docker Image
 
-import DockerInstructions from '../firmware/_docker-instructions.mdx';
+import DockerPullInstructions from '../firmware/_docker-pull-instructions.mdx'; 
 
-<DockerInstructions/>
+<DockerPullInstructions/>
 
-**Step 3: Install software dependancies**
+#### Step 2: Start your Docker Container
 
-import InstallDeps from '../firmware/_install-deps.mdx';
+import DockerStartInstructions from '../firmware/_docker-start-instructions.mdx';
 
-<InstallDeps/>
+<DockerStartInstructions/>
 
-**Step 4: Clone the repository**
+#### Step 3: Clone the OnionIoT/penwrt-sdk-wrapper repository
 
-To clone the **openwrt-sdk-wrapper** repository in the development environment, open the terminal and run the following command:
+To clone the **openwrt-sdk-wrapper** repository in the Docker container, run the following command:
 
 ```shell
 git clone https://github.com/OnionIoT/openwrt-sdk-wrapper.git
 ```
 
+When the repo is cloned, enter the directory:
+
+```shell
+cd openwrt-sdk-wrapper
+```
+
 ## Compiling packages for development
 
 The following sections cover configuration changes and compiling packages for a development environment.
 
+To compile packages for production, see the [relevant section below](#compiling-packages-for-production).
+
 ### Config changes
 
 After setting up the `openwrt-sdk-wrapper`, it is necessary to configure the required changes for system updates, package installations, or environment customization.
 
 #### Step 1: Update package feed variable
 
-Locate the `PACKAGE_FEEDS` variable in the profile file and modify it to reference the local source. This is necessary during development if there is a need to retrieve package makefiles from a local repository.
+Locate the `PACKAGE_FEEDS` variable in the `profile` file and modify it to reference the local source. This is necessary during development if there is a need to retrieve package makefiles from a local repository.
 
-**Example:** Assuming the custom package source is in the `/home/ubuntu/OpenWRT-Packages` directory, the updated `PACKAGE_FEEDS` variable should be:
-
-```shell
-PACKAGE_FEEDS="
-src-link custom /home/ubuntu/OpenWRT-Packages
-"
-```
+> **For example:** Assuming the custom package source is in the `/home/ubuntu/OpenWRT-Packages` directory, the updated `PACKAGE_FEEDS` variable should be:
+>
+>```shell
+>PACKAGE_FEEDS="
+>src-link custom /home/ubuntu/OpenWRT-Packages
+>"
+>```
 
 #### Step 2: Run build environment setup script
 
@@ -97,14 +105,16 @@ After completing this step, the OpenWRT SDK will be downloaded and set up for us
 
 #### Step 1: Run the build script
 
-To compile and build the desired packages, run the following commands in the development environment:
+To compile and build the desired packages, run the following command:
 
 ```bash
 bash onion_buildenv build_packages <PACKAGE_NAME>
 ```
 
 Replace `<PACKAGE_NAME>` with the actual package name.
 
+This will compile the selected pacakge and its dependencies.
+
 #### Step 2: Compiled package location
 
 All compiled packages can be found in the following directory:
@@ -115,6 +125,8 @@ openwrt-sdk/bin/packages/mipsel_24kc/custom/
 
 These packages have the extension `.ipk` and are compiled specifically for the `mipsel_24kc` architecture. The compiled packages can be used for testing on a device to confirm proper operation.
 
+---
+
 ## Compiling packages for production
 
 The following sections cover configuration changes and compiling package feeds for a production environment.
@@ -123,21 +135,24 @@ The following sections cover configuration changes and compiling package feeds f
 
 #### Step 1: Point to the package feed
 
-Navigate to the cloned **openwrt-sdk-wrapper** repo to update the `PACKAGE_FEEDS` variable.
+In you local copy of the **openwrt-sdk-wrapper**, update the `PACKAGE_FEEDS` variable in the `profile` configuration file.
 
-Follow these steps:
+Use the following syntax:
 
-1. Modify the profile configuration file.
-2. Update the `PACKAGE_FEEDS` variable using the following syntax: `src-git <feed-name> <package-feed-url>[;<package-feed-branch>]`
-   - `<feed-name>`: Choose an arbitrary name for SDK usage.
-   - `<package-feed-url>`: Provide the Git repository URL.
-   - `<package-feed-branch>`: Optionally, specify a branch of the package feed repository.
+```
+src-git <feed-name> <package-feed-url>[;<package-feed-branch>]
+```
 
-For example, say the `openwrt-23.05` branch of the `https://github.com/OnionIoT/OpenWRT-Packages` repo is the package feed, the addition to the `PACKAGE_FEEDS` variable should be:  <!-- TODO: update this 23.05 with OPENWRT_VERSION variable -->
+Replace the placeholder parameters with:
+- `<feed-name>` - choose a name for the package feed
+- `<package-feed-url>` - provide the Git repository URL
+- `<package-feed-branch>` - optionally, specify a branch of the package feed repository
 
-```shell
-src-git myfeed https://github.com/OnionIoT/OpenWRT-Packages.git;openwrt-23.05
-```
+> **For example:** say the `openwrt-23.05` branch of the `https://github.com/OnionIoT/OpenWRT-Packages` repo is the package feed, the addition to the `PACKAGE_FEEDS` variable should be:  <!-- TODO: update this 23.05 with OPENWRT_VERSION variable -->
+> 
+> ```shell
+> src-git myfeed https://github.com/OnionIoT/OpenWRT-Packages.git;openwrt-23.05
+>```
 <!-- TODO: update this 23.05 with OPENWRT_VERSION variable -->
 
 #### Step 2: Select packages from the package feed
@@ -148,17 +163,17 @@ To select specific packages from the package feed to compile, follow these steps
 2. Locate the `SDK_PACKAGES` variable.
 3. Modify the `SDK_PACKAGES` variable to include the packages from the package feed that you want to compile. Ensure that the list is new-line delimited.
 
-For example:
-
-```shell
-SDK_PACKAGES="
-  custom-lib
-  custom-package1
-  new-software
- "
- ```
-
-In this example, `custom-lib`, `custom-package1`, and `new-software` packages, along with any dependencies they require, will be compiled and built.
+>For example:
+>
+>```shell
+>SDK_PACKAGES="
+>  custom-lib
+>  custom-package1
+>  new-software
+> "
+> ```
+>
+>In this example, `custom-lib`, `custom-package1`, and `new-software` packages, along with any dependencies they require, will be compiled and built.
 
 #### Step 3: Set up the SDK and environment
 
@@ -172,28 +187,35 @@ First, download and setup the OpenWRT SDK with the following command:
 
 #### Step 1: Build packages
 
-Build and compile all desired packages listed in the `SDK_PACKAGES` variable in the profile, and run the following command:
+Build and compile all the packages listed in the `SDK_PACKAGES` variable in the profile, along with their dependencies, by running the following command:
 
 ```bash
 bash onion_buildenv build_all_packages
 ```
 
-#### Step 2: Compiled packages location
+Compilation time depends on the packages that are being compiled. Packages that are complex and/or have many dependencies take longer to compile. For reference, it takes about 30 minutes to compile the packages from the [OnionIoT/OpenWRT-Packages repo](https://github.com/OnionIoT/openwrt-packages/tree/openwrt-23.05).
+
+#### Step 2: Compiled package location
 
 All compiled packages can be found in the following directory:
 
 ```shell
 openwrt-sdk/bin/packages/mipsel_24kc/<feed-name>/
 ```
 
-Where `<feed-name>` is the name of the feed that was added to the `profile` configuration file in Step 1 above.
+Where `<feed-name>` is the name of the feed that was added to the `profile` configuration file in [Step 1 in the Config Changes section above](#config-changes-1).
+
+The packages have the extension `.ipk` and are compiled specifically for the Omega2 `mipsel_24kc` architecture. Also included are **package index files** that are required by OPKG on the device to recognize and install the packages from the repository.
 
-The packages have the extension `.ipk` and are compiled specifically for the `mipsel_24kc` architecture. Also included are package index files that will be used by the package manager on the device to install the packages.
 
-:::note Important note
+:::info Package Indexing and Signing
 
-The last step of compiling a package feed is creating an index of the packages and signing the packages. This step is required so the compiled packages can be used as an opkg package repository by the device.
+The last step of compiling a package feed is creating an index of the packages and signing the packages. This step is required so the compiled packages can be used as a package repository by the device. 
+
+When the `bash onion_buildenv build_all_packages` command is run, the Onion OpenWRT SDK Wrapper will automatically perform indexing and signing as the last step.
 
 :::
 
+The compiled packages can now be deployed as a package repo. See the [Deploy a Package Repo article](./deploy-package-repo) for more details.
+
 <GiscusDocComment />

Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,5 @@`
	`1`	`+<!-- NO LONGER USED! -->`
	`2`	`+`
`1`	`3`	`When using Ubuntu 22.04 Linux or newer, you need to install the software packages required to use the OpenWRT build tools. These can be installed using the packager manager.`
`2`	`4`
`3`	`5`	`:::tip`