Skip to content

Getting Started

Jump to bottom
Adrian J. Collado edited this page Oct 28, 2016 · 4 revisions

Building YABS From Scratch

Chances are that you won't have YABS installed on your computer the first time you want to use it (If you do, congratulations), and will thus need to build it.

You can start by cloning the main repository using git clone https://github.com/SlickOS/YABS.

As YABS uses a third party library for YAML parsing (yaml-cpp), you first have to build that. Do do so, run the dependencies script.

On Linux, run Scripts/Linux/Dependencies.sh.

On macOS, run Scripts/macOS/Dependencies.sh.

Once the library is compiled, use an appropriate build script to build YABS for the first time.

On Linux, run Scripts/Linux/Build.sh.

On macOS, run Scripts/macOS/Build.sh.

Once you've built the program, you can either manually install it by putting it somewhere that your shell can find it, or by running the install script.

On Linux, run Scripts/Linux/Install.sh.

On macOS, run Scripts/macOS/Install.sh.

Congratulations! You now have YABS installed on your computer and can get to the fun stuff!

Your First Script

YABS is based on the idea of tools, projects, and configurations. By splitting each of these into separate sections, we can have very fine control over what is built and how.

Projects

One of the most important sections in your build script is the list of projects.

Projects:
  - Name: Build
    Variables:
      - SourceDir: Source/
      - ObjectDir: Build/Objects
      - Binary: Build/build

Each project has a name and any number of variables.

Variables can be referenced using $VariableName. This allows us to substitute in text in our commands. The project name is required, and can be referenced in any commands. It essentially acts like a variable in every respect except its syntax, which is +Project.

Configurations

Configurations allow you to build slightly different variations of your code. They're commonly used as ways to produce a release versus a debug version.

Configurations:
  - Name: Debug
    Variables:
      - C++Flags: -g -DDEBUG
  - Name: Release
    Variables:
      - C++Flags: -O2 -DRELEASE

Like projects, each configuration has a name and any number of variables. The only difference is that the name is referenced using +Config rather than +Project.

Targets

Targets are the lists of commands that YABS actually performs. You can define any number of targets. Common targets include Build, Clean, Rebuild, and Install.

Targets:
  - Name: Build
    Commands:
      - Tool: C++ Compile($Flags, +Find($SourceDir, *.cpp), $ObjectDir)
      - Tool: C++ Link($LinkFlags, +Find($ObjectDir, *.o), $Libraries, $Binary)

  - Name: Clean
    Commands:
      - Shell: rm -rf $ObjectDir $Binary

  - Name: Rebuild
    Dependencies:
      - Clean
      - Build

Each target has a name, any number of variables, any number of commands, and any number of dependencies.

The variables act the same as both configurations and projects, however they're not used as commonly since all of the variables from the other two sections will be usable in the commands.

The name is not referenceable like +Project and +Config, as it is designed solely as a designation for the build tool itself.

Commands are the instructions on how to execute each target. There are many different type of commands:

  • Tool - Tools described by Tool Definition Files.
  • Shell - Commands executed by the default shell (/bin/bash on Linux, and cmd.exe on Windows).
  • Path - Commands for manipulating directories and files.

Commands may use variables from any of the other sections using $VariableName. If multiple sections have variables with the same name, then the variables are chained together and separated using a space character.

Each command is executed in series with those before and after it. If a command fails, no further commands will be executed.

Dependencies are targets that must be executed before the current target. In the example above, the Rebuild target has dependencies of Clean and Build. This means that Clean will be executed first (as it is the first target in the list of dependencies), and then Build will be executed. If either dependency fails, the current target will not be executed.

Targets are, by default, executed for each configuration and architecture of each project. The same is done for submodules within projects.

Running YABS

Running just the YABS command will execute the first target for all projects and configurations.

yabs

Running the YABS command with one or more targets will execute the listed targets.

yabs Clean

Running YABS with a --project (-p), --platform (-a), or --config (-c) switch will pick the relevant project, architecture, or configuration, respectively.

yabs --project YABS -c Release

If you list multiple projects, platforms, or configurations, you must add the switch for each one listed.

yabs -c Debug -c Release

Running YABS with the --list or -l command will list the commands executed, rather than actually executing them. This is useful for debugging your scripts.

yabs -l

Running YABS with the --help or -h switches, or with the ? target will print out a help message.

yabs ?

Going Further

There are many more things that can be done with YABS.

The syntax for the YAML files can be found at the Syntax wiki page.

Clone this wiki locally