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).

Usage

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.

Phases

A rpi-build run consist of two phases.

  1. 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.

  2. 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)

Language

Special rpi-build tasks

release

Creates a release

package

Creates a package

target

Creates a target (default targets).

Helper functions

workdir

Gives the path to the workdir
Optional parameter:

  • file - Return the path to this file in the working directory.
download_dir

Gives the path to the download_dir
Optional parameter:

  • file - Return the path to this file in the download directory.
findfile(fn)

Searches for file fn in:

  • Current Rakefile directory
  • workdir
  • download_dir
  • directories for required files beneath RPI_BUILD_DIR (i.e. libraries)

VAR

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.

Examples

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' }

Main functions

download

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
unpack

Unpacks an archive to the working directory
Parameters:

  • fn - Archive to unpack Optional:
  • symlink - Create symlink to the top level directory in the archive
git

Clone git repository
Parameters:

  • src - URL to repository
  • saveas - Directory to clone into
patch

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
config

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.
github_tarball

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
gitweb_tarball

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
pre_install

Add content to the rpi-update pre-install script
Parameter:

  • str - Content to add
post_install

Add content to the rpi-update post-install script
Parameter:

  • str - Content to add
insert_before(fn, search, insert)

Insert string before search string in file fn.

insert_after(fn, search, insert)

Insert string after search string in file fn.

replace(fn, search, replac)

Replace string search with string replace in file fn.

Readme

The Readme module provides a way to set the contents of the README.md file.

Testing

It is tested on the Raspberry Pi with Raspian and on i386 with Ubuntu 12.04 and 14.04.

⚠️ **GitHub.com Fallback** ⚠️