Writing Your First BRICK Script

Creating a Project

Let's start by creating your first BRICK project. We'll build a simple "Hello World" C program to demonstrate the basics.

First, run the init command. This generates scaffolding for your project:

brick init example

Every BRICK project needs a Brickfile (note the capital B and no extension). This is the main configuration file that defines your build targets.

Brickfile Basics

The above command created a Brickfile with the following content:

# Define a target called "example" @target example

This tells BRICK that there's a target named "hello" which will have its build instructions in a file called hello.brick.

Simple Example

Now fill out the example.brick file that contains the actual build instructions:

# Download source code from GitHub @source gh:example/hello-world:v1.0.0 # This program depends on "mylib", which will need its own "mylib.brick" file. @dep mylib # Build instructions start here # At this point, source code is already downloaded and extracted # Compile the program gcc -o hello hello.c # Install to the designated directory cp hello ${HELLO_INSTALL_DIR}/

Let's break down what this script does:

  • @source directive: Downloads source code from GitHub repository "example/hello-world" at tag "v1.0.0"
  • @dep directive: Ensures our required library is built and available before compiling
  • Build commands: Standard shell commands to compile the C program
  • Install command: Copies the compiled binary to the install directory

Understanding Directives

BRICK directives are special commands that start with @ and must appear at the top of your .brick files. Here are the most common ones:

@source

Required

Specifies where to download source code from. Supports:

  • @source url:https://example.com/archive.tar.gz - Direct URL
  • @source git:https://github.com/user/repo.git:commit-hash - Git repository
  • @source gh:user/repo:tag-or-commit - GitHub shorthand

@dep

Optional

Declares dependencies that must be available, pointing to another brick file. For example:

  • @dep my-library points to my-library.brick

@target

Brickfile only

Used in the main Brickfile to define build targets:

  • @target hello - Points to hello.brick
  • @target my-lib - Points to my-lib.brick

Environment Variables

BRICK automatically provides environment variables for your build scripts. The naming pattern is ${<TARGET_NAME>_<TYPE>_DIR}:

${<TARGET>_BUILD_DIR}

The directory where source code is extracted and build commands are executed. This is your working directory during the build process.

${<TARGET>_INSTALL_DIR}

The directory where you should install your compiled artifacts.Always install your outputs here!

For a target named "hello", you would use:

  • ${HELLO_BUILD_DIR} - Source code location
  • ${HELLO_INSTALL_DIR} - Installation destination

Running Your Script

Once you have your Brickfile and target files set up, run your build:

# Run the "hello" target brick run hello # Or specify an output directory brick run hello -o ./build

BRICK will:

  1. Parse your Brickfile and locate the "hello" target
  2. Read hello.brick and process the directives
  3. Download source code from the specified location
  4. Ensure dependencies (like mylibrary) are available
  5. Execute your build commands in the source directory
  6. Collect the installed artifacts
ls ./build/hello/ # Your compiled program should be here

Pro Tip

Use brick gen hello to generate build scripts without running them!