Manual - notro/rpi-build GitHub Wiki
rpi-build provides an easy to use language for building, installing and releasing Linux kernels for the Raspberry Pi.
This is done with the help of Rake (Ruby Make).
rpi-build [option tasks] <release> <target>
Targets:
* fetch - Download files
* unpack - Unpack archives into workdir
* patch - Patch Linux kernel source
* config - Configure Linux kernel
* menuconfig - make menuconfig
* diffconfig - Show kernel config diff from default config
* kbuild - Build Linux kernel
* kmodules - Copy modules and device firmware to a temporary directory
* external - Build and install out-of-tree modules
* build - Build all
* readme - Create README.md
* commit - Commit kernel and firmware
* push - Push commit(s)
* archive - Archive workdir out
* transfer - Copy archive to machine (needs SSHIP)
* install - Install
* diff[against] - Create source code diff files (diffprep has to be run)
Filename: <dir>-<against>.patch in workdir
'against' can be 'unpack' or 'patch'. Default is 'unpack'.
Option tasks:
* use[library] - Use library (Rakefile)
* clean - Clean workdir
* log - Redirect output to build.log
* diffprep[dirs] - Prepare source for the diff target
'dirs' is a comma separated list of source dirs,
e.g. diffprep[linux,u-boot]. Default is 'linux'
rpi-build is built on top of Rake, and has much of the same behaviour.
Targets, releases and option tasks are Rake tasks.
They are run in the order they are given on the command line,
except for option tasks which are run before any other tasks.
Some Rake options:
-h - Help
--trace - Be more verbose
Print full stack trace on exceptions
Environment variables:
RPI_BUILD_DIR - rpi-build root directory
Default: ~/rpi-build
WORKDIR - Working directory used when building
Default: ./workdir
DOWNLOAD_DIR - Directory for downloaded files
Default: $RPI_BUILD_DIR/downloads
Admin mode:
rpi-build admin <action>
Actions:
* addlib[gitrepo] - Add library with git
Short gitrepo assumes Github: addlib[notro/fbtft-build]
* update - Update git repos in RPI_BUILD_DIR
Caveat:
rpi-build won't push when logging to file, in case username and password is asked for.
A rpi-build run consist of two phases.
-
In the first phase, a release describes some meta info about the kernel release, like kernel version, commit message etc. This release depends on packages which describes the actions and prerequisites needed to build and install a certain component. During this phase, the build targets are filled with information about how to make that release.
-
In the second phase the chosen target is invoked. The targets are chained together and will only be invoked one time, except when a target is invoked directly (e.g. if config is invoked after install, a second install will run all steps from build)
Creates a release
Creates a package
Creates a target (default targets).
Gives the path to the workdir
Optional parameter:
- file - Return the path to this file in the working directory.
Gives the path to the download_dir
Optional parameter:
- file - Return the path to this file in the download directory.
Searches for file fn in:
- Current Rakefile directory
- workdir
- download_dir
- directories for required files beneath RPI_BUILD_DIR (i.e. libraries)
VAR is a special way to handle environment variables. ENV is the the standard way.
When an environment variable is accessed through VAR:
- If the variable is set (ENV), return it.
- If not, see if it is stored in the working directory and return it.
- If not see if there is a default block assigned to it and return it's value.
- If not return nil as ENV does when the variable is not set.
When an environment variable is set with VAR, ENV is set and written to a file in the working directory.
Set the variable and store it's value for later runs
VAR['hello'] = 'world'
If the variable is not set, set it to 'world' and store the value for later runs
VAR['hello'] ||= 'world'
Late variable expansion: Set a default value for 'hello' that will expand when the variable is accessed
VAR.default('hello') { 'world' }
Downloads a file using wget to the download directory
Parameters:
- src - url of file to download Optional:
- saveas - Save the file as
- desc - Used in the README.md file
Unpacks an archive to the working directory
Parameters:
- fn - Archive to unpack Optional:
- symlink - Create symlink to the top level directory in the archive
Clone git repository
Parameters:
- src - URL to repository
- saveas - Directory to clone into
Patches the kernel sourcecode
Parameters:
- file - Patch name
Search dirs: workdir, download_dir, $pwd/patches
If no match is found, workdir and $pwd/patches is searched for a directory matching the patch name.
This directory is then searched for a Linux version number file that is <= the version to be built.
If the file is empty, the patch is skipped. Optional: - opts - Optional arguments to the patch program.
- usegitapply - Use git apply instead of patch
Set kernel configuration option(s)
Parameters:
- option - Option or array of options to set
- command - :enable, :disable, :module, :str, :val, :undefine Optional:
- answer - The value fed to stdin when running make oldconfig
yes is used to do this.
answer is used to hold the value for :str and :val.
Rationale: Sometimes when enabling an option, other options becomes visible. This way rpi-build can give an answer when asked by make oldconfig.
Download a github repository as an archive
Parameters:
- repo - Repository to download: username/repo. The #{env_name}_SHA variable tells which ref.
- symlink - Create symlink to the top level directory in the archive Optional:
- env_name - Override the base of the environment variable name. Default is username/repo as USERNAME_REPO. Environment variables:
- #{env_name}_BRANCH will be 'master' if not set
- #{env_name}_SHA will be HEAD of the branch if not set
Download git repository from gitweb powered repository
Parameters:
- repo - Repository to download. The #{env_name}_SHA variable tells which ref.
- symlink - Create symlink to the top level directory in the archive
- env_name - Set the base of the environment variable name. Environment variables:
- #{env_name}_BRANCH will be 'master' if not set
- #{env_name}_SHA will be HEAD of the branch if not set
Add content to the rpi-update pre-install script
Parameter:
- str - Content to add
Add content to the rpi-update post-install script
Parameter:
- str - Content to add
Insert string before search string in file fn.
Insert string after search string in file fn.
Replace string search with string replace in file fn.
The Readme module provides a way to set the contents of the README.md file.
It is tested on the Raspberry Pi with Raspian and on i386 with Ubuntu 12.04 and 14.04.