Differences
This shows you the differences between two versions of the page.
| Next revision | Previous revision Next revisionBoth sides next revision | ||
| user:ahorner [2022/09/29 19:50] – Working on the build info page ahorner | user:ahorner [2022/10/01 13:52] – ahorner | ||
|---|---|---|---|
| Line 1: | Line 1: | ||
| - | ====== | + | ====== |
| - | <WRAP important> | + | My Drafts: |
| - | * Do everything as an unprivileged user, not root, without sudo. | + | * [[:user:ahorner:locating-images|Unordered |
| - | * Make sure there are no spaces in the full path to the build directory. | + | |
| - | </ | + | |
| - | + | ||
| - | <WRAP important> | + | |
| - | There is an issue affecting the current OpenWrt source tree (from at least 21.02 onwards): OpenWrt images built in certain setups will succeed, but they will hang on boot if installed on a device. To work around this issue, please follow the instructions posted [[https:// | + | |
| - | </ | + | |
| - | + | ||
| - | After [[docs: | + | |
| - | + | ||
| - | <code bash> | + | |
| - | # Download and update the sources | + | |
| - | git clone https:// | + | |
| - | cd openwrt | + | |
| - | git pull | + | |
| - | + | ||
| - | # Select a specific code revision | + | |
| - | git branch -a | + | |
| - | git tag | + | |
| - | git checkout v21.02.3 | + | |
| - | + | ||
| - | # Update the feeds | + | |
| - | ./ | + | |
| - | ./ | + | |
| - | + | ||
| - | # Configure the firmware image and the kernel | + | |
| - | make menuconfig | + | |
| - | make -j $(nproc) kernel_menuconfig | + | |
| - | + | ||
| - | # Build the firmware image | + | |
| - | make -j $(nproc) defconfig download clean world | + | |
| - | </ | + | |
| - | + | ||
| - | The build steps are explained in detail below. | + | |
| - | + | ||
| - | ===== Downloading sources ===== | + | |
| - | Clone the Git repository using the following command. | + | |
| - | + | ||
| - | <code bash> | + | |
| - | git clone https:// | + | |
| - | </ | + | |
| - | + | ||
| - | Possible issues: | + | |
| - | * '' | + | |
| - | * '' | + | |
| - | + | ||
| - | ===== Updating sources ===== | + | |
| - | :!: Sources in development branch change frequently. | + | |
| - | It is recommended that you work with the latest sources. | + | |
| - | + | ||
| - | <code bash> | + | |
| - | git pull | + | |
| - | </ | + | |
| - | + | ||
| - | Possible issues: | + | |
| - | * '' | + | |
| - | * '' | + | |
| - | + | ||
| - | ===== Updating feeds ===== | + | |
| - | Pull the latest updates for the feeds in case it became outdated. | + | |
| - | + | ||
| - | <code bash> | + | |
| - | ./ | + | |
| - | </ | + | |
| - | + | ||
| - | Make the downloaded package/ | + | |
| - | + | ||
| - | <code bash> | + | |
| - | ./ | + | |
| - | ./ | + | |
| - | </ | + | |
| - | + | ||
| - | Possible issues: | + | |
| - | * '' | + | |
| - | * < | + | |
| - | Can't exec " | + | |
| - | Unsupported version of make found: make | + | |
| - | Checking ' | + | |
| - | Checking ' | + | |
| - | Checking ' | + | |
| - | Checking ' | + | |
| - | Checking ' | + | |
| - | Checking ' | + | |
| - | Checking ' | + | |
| - | Checking ' | + | |
| - | Checking ' | + | |
| - | Checking ' | + | |
| - | Checking ' | + | |
| - | Checking ' | + | |
| - | </ | + | |
| - | + | ||
| - | ==== Creating a local feed ==== | + | |
| - | + | ||
| - | - Prepare your ''< | + | |
| - | - Create a dir: '' | + | |
| - | - Write a Makefile or download one '' | + | |
| - | - Append a line with your custom feed to '' | + | |
| - | - Now run: '' | + | |
| - | - Build your package.\\ Select it in the menu of '' | + | |
| - | + | ||
| - | ===== Selecting code revision ===== | + | |
| - | This step can be skipped you want to build bleeding edge images. | + | |
| - | + | ||
| - | ==== Selecting branch ==== | + | |
| - | Each branch contains the baseline code for the release version, e.g. '' | + | |
| - | Each branch is intended to contain **stable** code with carefully selected fixes and updates backported from the development branch. | + | |
| - | + | ||
| - | To use a branch, clone the Git repository using the '' | + | |
| - | + | ||
| - | <code bash> | + | |
| - | # List branches | + | |
| - | git branch -a | + | |
| - | + | ||
| - | # Use OpenWrt master branch | + | |
| - | git checkout master | + | |
| - | + | ||
| - | # Use OpenWrt 21.02 branch | + | |
| - | git checkout openwrt-21.02 | + | |
| - | </ | + | |
| - | + | ||
| - | :!: When changing branches, it is recommended to perform a thorough scrub of your source tree by using the '' | + | |
| - | This ensures that your source tree does not contain any build artifacts or configuration files from previous build runs. | + | |
| - | + | ||
| - | ==== Selecting tag ==== | + | |
| - | Select an individual release tag to install packages from the official release repositories for a long time. | + | |
| - | + | ||
| - | <code bash> | + | |
| - | # Fetch and list tags | + | |
| - | git fetch -t | + | |
| - | git tag | + | |
| - | + | ||
| - | # Use OpenWrt 21.02.1 release | + | |
| - | git checkout v21.02.1 | + | |
| - | </ | + | |
| - | + | ||
| - | ==== Selecting hash ==== | + | |
| - | Select a specific code revision hash and sync all feeds to the same date. | + | |
| - | + | ||
| - | <code bash> | + | |
| - | REV_HASH=" | + | |
| - | git checkout ${REV_HASH} | + | |
| - | REV_BRANCH=" | + | |
| - | + | ||
| - | # Replace all src-git with src-git-full: | + | |
| - | sed -e "/ | + | |
| - | + | ||
| - | ./ | + | |
| - | + | ||
| - | # Edit every line of feeds.conf in a loop to set the chosen revision hash | + | |
| - | sed -n -e "/ | + | |
| - | | while read -r FEED_ID | + | |
| - | do | + | |
| - | REV_DATE=" | + | |
| - | REV_HASH=" | + | |
| - | sed -i -e "/ | + | |
| - | done | + | |
| - | + | ||
| - | ./ | + | |
| - | ./ | + | |
| - | </ | + | |
| - | + | ||
| - | ==== Using official build config ==== | + | |
| - | Compile OpenWrt in a way that it gets [[https:// | + | |
| - | + | ||
| - | For example if you are flashing for the [[toh: | + | |
| - | + | ||
| - | ' | + | |
| - | + | ||
| - | Download the config by removing everything up to the subtarget ' | + | |
| - | <code bash> | + | |
| - | # OpenWrt 19.07 and later | + | |
| - | wget https:// | + | |
| - | + | ||
| - | # OpenWrt 18.06 and before | + | |
| - | wget https:// | + | |
| - | </ | + | |
| - | + | ||
| - | When using this configuration the correct defaults will be already selected for the Target and Subtarget but **not** for the Target profile so you will have to tailor it for the specific device if you want to build only that one. | + | |
| - | + | ||
| - | ===== Image configuration ===== | + | |
| - | ==== Menuconfig ==== | + | |
| - | The **build system configuration interface** handles the selection of the target platform, packages to be compiled, packages to be included in the firmware file, some kernel options, etc. | + | |
| - | + | ||
| - | Start the build system configuration interface by writing the following command: | + | |
| - | + | ||
| - | <code bash> | + | |
| - | make menuconfig | + | |
| - | </ | + | |
| - | + | ||
| - | This will update the dependencies of your existing configuration automatically, | + | |
| - | + | ||
| - | You will see a list of options. | + | |
| - | This list is really the top of a tree. | + | |
| - | You can select a list item, and descend into its tree. | + | |
| - | + | ||
| - | To search for the package or feature in the tree, you can type the "/" | + | |
| - | This will give you its locations within the tree. | + | |
| - | + | ||
| - | For most packages and features, you have three options: | + | |
| - | '' | + | |
| - | * pressing '' | + | |
| - | * pressing '' | + | |
| - | * pressing '' | + | |
| - | + | ||
| - | When you save your configuration, | + | |
| - | + | ||
| - | When you open '' | + | |
| - | - Target system (general category of similar devices) | + | |
| - | - Subtarget (subcategory of Target system, grouping similar devices) | + | |
| - | - Target profile (each specific device) | + | |
| - | - Package selection | + | |
| - | - Build system settings | + | |
| - | - Kernel modules | + | |
| - | + | ||
| - | Select your device' | + | |
| - | + | ||
| - | E.g. to select and save the target for [[toh: | + | |
| - | - Target System -> Select -> Atheros AR7xxx/ | + | |
| - | - Subtarget -> Select -> Devices with small flash -> Select | + | |
| - | - Target Profile -> Select -> TP-LINK TL-WR841N/ | + | |
| - | - Exit -> Yes | + | |
| - | + | ||
| - | ==== Configure using config diff file ==== | + | |
| - | Beside '' | + | |
| - | This file includes only the changes compared to the default configuration. | + | |
| - | A benefit is that this file can be version-controlled in your downstream project. | + | |
| - | It's also less affected by upstream updates, because it only contains the changes. | + | |
| - | + | ||
| - | === Creating diff file === | + | |
| - | Save the build config changes. | + | |
| - | + | ||
| - | <code bash> | + | |
| - | # Write the changes to diffconfig | + | |
| - | ./ | + | |
| - | </ | + | |
| - | + | ||
| - | The firmware make process [[commit>? | + | |
| - | + | ||
| - | === Using diff file === | + | |
| - | These changes can form the basis of a config file ''< | + | |
| - | By running '' | + | |
| - | + | ||
| - | <code bash> | + | |
| - | # Write changes to .config | + | |
| - | cp diffconfig .config | + | |
| - | + | ||
| - | # Expand to full config | + | |
| - | make defconfig | + | |
| - | </ | + | |
| - | + | ||
| - | These changes can also be added to the bottom of the config file (''< | + | |
| - | + | ||
| - | <code bash> | + | |
| - | # Append changes to bottom of .config | + | |
| - | cat diffconfig >> .config | + | |
| - | + | ||
| - | # Apply changes | + | |
| - | make defconfig | + | |
| - | </ | + | |
| - | + | ||
| - | ==== Custom files ==== | + | |
| - | In case you want to include some custom configuration files, the correct place to put them is: | + | |
| - | * **''< | + | |
| - | + | ||
| - | For example, let's say that you want an image with a custom **''/ | + | |
| - | * '' | + | |
| - | * '' | + | |
| - | + | ||
| - | E.g. if your ''< | + | |
| - | + | ||
| - | It is strongly recommended to use [[docs: | + | |
| - | This helps minimize conflicts with auto-generated settings which can change between versions. | + | |
| - | + | ||
| - | ==== Defconfig ==== | + | |
| - | <code bash> | + | |
| - | make defconfig | + | |
| - | </ | + | |
| - | + | ||
| - | will produce a default configuration of the target device and build system, including a check of dependencies and prerequisites for the build environment. | + | |
| - | + | ||
| - | Defconfig will also remove outdated items from '' | + | |
| - | + | ||
| - | It also checks the dependencies and will add possibly missing necessary dependencies. | + | |
| - | This can be used to " | + | |
| - | + | ||
| - | ==== Kernel configuration (optional) ==== | + | |
| - | Note that '' | + | |
| - | :!: Also you won't be able to install kernel packages from the official repositories when you make changes here. | + | |
| - | + | ||
| - | While you won't typically need to do this, you can do it: | + | |
| - | + | ||
| - | <code bash> | + | |
| - | make kernel_menuconfig CONFIG_TARGET=subtarget | + | |
| - | </ | + | |
| - | + | ||
| - | CONFIG_TARGET allows you to select which config you want to edit, possible options: target, subtarget, env. | + | |
| - | + | ||
| - | The changes can be reviewed and reverted with: | + | |
| - | + | ||
| - | <code bash> | + | |
| - | git diff target/ | + | |
| - | git checkout target/ | + | |
| - | </ | + | |
| - | + | ||
| - | ==== Source mirrors ==== | + | |
| - | The 'Build system settings' | + | |
| - | - Local mirror for source packages | + | |
| - | - Download folder | + | |
| - | + | ||
| - | In the case of the first option, you simply enter a full URL to the HTTP or FTP server on which the package sources are hosted. | + | |
| - | Download folder would in the same way be the path to a local folder on the build system (or network). | + | |
| - | If you have a web/ | + | |
| - | Similar if a local ' | + | |
| - | + | ||
| - | The ' | + | |
| - | + | ||
| - | ==== Download sources and multi core compile ==== | + | |
| - | Before running final make it is best to issue make download command first, this step will pre-fetch all source code for all dependencies, | + | |
| - | + | ||
| - | If you try compiling OpenWrt on multiple cores and don't download all source files for all dependency packages it is very likely that your build will fail. | + | |
| - | + | ||
| - | <code bash> | + | |
| - | make download | + | |
| - | </ | + | |
| - | + | ||
| - | ===== Building images ===== | + | |
| - | Everything is now ready for building the image(s), which is done with one single command: | + | |
| - | + | ||
| - | <code bash> | + | |
| - | make | + | |
| - | </ | + | |
| - | + | ||
| - | This should compile toolchain, cross-compile sources, package packages, and generate an image ready to be flashed. | + | |
| - | + | ||
| - | ==== Make tips ==== | + | |
| - | See also: [[https:// | + | |
| - | + | ||
| - | '' | + | |
| - | '' | + | |
| - | + | ||
| - | Example of pre-downloading and building the images on a 4 core CPU: | + | |
| - | + | ||
| - | <code bash> | + | |
| - | make -j5 download world | + | |
| - | </ | + | |
| - | + | ||
| - | You can use [[https:// | + | |
| - | + | ||
| - | <code bash> | + | |
| - | make -j $(nproc) download world | + | |
| - | </ | + | |
| - | + | ||
| - | or a better macro with '' | + | |
| - | + | ||
| - | <code bash> | + | |
| - | make -j $(($(nproc)+1)) | + | |
| - | </ | + | |
| - | + | ||
| - | === Building in the background === | + | |
| - | If you intend to use your system while building, you can have the build process use only idle I/O and CPU capacity like this (4 core, 8 thread CPU): | + | |
| - | + | ||
| - | <code bash> | + | |
| - | make download | + | |
| - | ionice -c 3 chrt --idle 0 nice -n19 make -j9 | + | |
| - | </ | + | |
| - | + | ||
| - | === Building single packages === | + | |
| - | When developing or packaging software, it is convenient to be able to build only the package in question, e.g. with package '' | + | |
| - | + | ||
| - | <code bash> | + | |
| - | make package/ | + | |
| - | </ | + | |
| - | + | ||
| - | For a rebuild: | + | |
| - | <code bash> | + | |
| - | make package/ | + | |
| - | </ | + | |
| - | + | ||
| - | It doesn' | + | |
| - | + | ||
| - | === Spotting build errors === | + | |
| - | If for some reason the build fails, the easiest way to spot the error is to do: | + | |
| - | + | ||
| - | <code bash> | + | |
| - | make V=s 2>&1 | tee build.log | grep -i -E " | + | |
| - | + | ||
| - | make V=s 2>&1 | tee build.log | grep -i ' | + | |
| - | (may not work) | + | |
| - | </ | + | |
| - | + | ||
| - | :!: If **grep** throws an error, use **fgrep** instead. | + | |
| - | + | ||
| - | The above saves a full verbose copy of the build output (with stdout piped to stderr) in '' | + | |
| - | + | ||
| - | Another example: | + | |
| - | + | ||
| - | <code bash> | + | |
| - | ionice -c 3 nice -n 20 make -j 2 V=s CONFIG_DEBUG_SECTION_MISMATCH=y 2>&1 | tee build.log | + | |
| - | </ | + | |
| - | + | ||
| - | The above saves a full verbose copy of the build output (with stdout piped to stderr) in build.log while building using only background resources on a dual core CPU. | + | |
| - | + | ||
| - | Yet another way to focus on the problem without having to wade through tons of output from Make as described above is to check the corresponding log in '' | + | |
| - | i.e. if the build fails at '' | + | |
| - | + | ||
| - | === Getting beep notification === | + | |
| - | Depending on your CPU, the process will take a while, or while longer. | + | |
| - | If you want an acoustic notification, | + | |
| - | + | ||
| - | <code bash> | + | |
| - | make ...; echo -e ' | + | |
| - | </ | + | |
| - | + | ||
| - | === Ignore build errors === | + | |
| - | If you are building everything (not just the packages to make a flashable image), you will probably want to keep building all packages even if some have compile errors and won't be built. | + | |
| - | + | ||
| - | <code bash> | + | |
| - | # Ignore compilation errors | + | |
| - | IGNORE_ERRORS=1 make ... | + | |
| - | + | ||
| - | # Ignore all errors including firmware assembly stage | + | |
| - | make -i ... | + | |
| - | </ | + | |
| - | + | ||
| - | ===== Locating images ===== | + | |
| - | After a successful build, the freshly built image(s) can be found below the newly created ''< | + | |
| - | The compiled files are additionally classified by the target platform and subtarget, so e.g. a '' | + | |
| - | + | ||
| - | E.g. if your ''< | + | |
| - | + | ||
| - | See also: [[docs: | + | |
| - | + | ||
| - | ===== Cleaning up ===== | + | |
| - | You might need to clean your //build environment// | + | |
| - | + | ||
| - | The build artefacts, toolchain, build tools and downloaded feeds & sources files can be cleaned selectively.\\ | + | |
| - | The following '' | + | |
| - | + | ||
| - | ^ > Cleaned components > \\ v make argument v^ Compiled binaries:\\ firmware, kernel, packages ^ Toolchain\\ (target-specific) | + | |
| - | | clean | x | | | | | | | + | |
| - | | targetclean | + | |
| - | | dirclean | + | |
| - | | config-clean | | | | x | | | | + | |
| - | | distclean | + | |
| - | ==== Clean ==== | + | |
| - | <code bash> | + | |
| - | make clean | + | |
| - | </ | + | |
| - | + | ||
| - | Deletes contents of the directories ''/ | + | |
| - | This doesn' | + | |
| - | It is a good practice to do '' | + | |
| - | That may not be necessary always, but as a general rule it helps to ensure quality builds. | + | |
| - | + | ||
| - | ==== Targetclean ==== | + | |
| - | <code bash> | + | |
| - | make targetclean | + | |
| - | </ | + | |
| - | + | ||
| - | This cleans also the target-specific toolchain in addition of doing '' | + | |
| - | Does a '' | + | |
| - | Note: '' | + | |
| - | + | ||
| - | ==== Dirclean ==== | + | |
| - | <code bash> | + | |
| - | make dirclean | + | |
| - | </ | + | |
| - | + | ||
| - | This is your basic "full clean" operation. Cleans all compiled binaries, tools, toolchain, tmp/ etc.\\ | + | |
| - | Deletes contents of the directories ''/ | + | |
| - | + | ||
| - | + | ||
| - | ==== Distclean ==== | + | |
| - | <code bash> | + | |
| - | make distclean | + | |
| - | </ | + | |
| - | + | ||
| - | Nukes everything you have compiled or configured and also deletes all downloaded feeds contents and package sources. | + | |
| - | :!: In addition to all else, this will **erase your build configuration ''< | + | |
| - | Use only if you need a " | + | |
| - | + | ||
| - | ==== Selective cleanup ==== | + | |
| - | In more time, you may not want to clean so many objects, then you can use some of the commands below to do it. | + | |
| - | + | ||
| - | <code bash> | + | |
| - | # Clean linux objects | + | |
| - | make target/ | + | |
| - | + | ||
| - | # Clean package base-files objects | + | |
| - | make package/ | + | |
| - | + | ||
| - | # Clean luci objects | + | |
| - | make package/ | + | |
| - | </ | + | |
| - | + | ||
| - | ===== Examples ===== | + | |
| - | * https:// | + | |
| - | * https:// | + | |
| - | * https:// | + | |
| - | + | ||
| - | ===== Troubleshooting ===== | + | |
| - | * Beware of [[docs: | + | |
| - | * First get more information on the problem using the make option '' | + | |
| - | * Read more about make options: [[docs: | + | |
| - | + | ||
| - | ==== Missing source code file, due to download problems ==== | + | |
| - | First check if the URL path in the make file contains a trailing slash, then if it does, try with it removed (helped several times). | + | |
| - | Otherwise try to download the source code manually and put it into '' | + | |
| - | + | ||
| - | ==== Compilation errors ==== | + | |
| - | Try to update the main source and all the feeds, however beware of other potential problems. | + | |
| - | Check for related issues in the [[: | + | |
| - | + | ||
| - | Some packages may not be updated properly and built after they got stuck with old dependencies, | + | |
| - | < | + | |
| - | WARNING: Makefile ' | + | |
| - | </ | + | |
| - | The build environment can be recovered by uninstalling and reinstalling the failing package | + | |
| - | < | + | |
| - | $ ./ | + | |
| - | Uninstalling package ' | + | |
| - | $ ./ | + | |
| - | Installing package ' | + | |
| - | Installing package ' | + | |
| - | Installing package ' | + | |
| - | </ | + | |
| - | + | ||
| - | ==== WARNING: skipping < | + | |
| - | Run '' | + | |
| - | It should be labeled with ''< | + | |
| - | + | ||
| - | ==== Flashable images for my device are not generated ==== | + | |
| - | When you execute '' | + | |
| - | + | ||
| - | If running '' | + | |