UserDocs_Tutorial

User Documentation - Tutorial

Introduction

Welcome to BuildGen, in this tutorial we will cover how to both create the required files and use BuildGen to build your project. The two will be intertwined as we will be changing the building as we add new features to the configuration files.

This tutorial was intended to be read in order and we will be building upon we was discussed earlier.

To start off we are going to create a sample project. The project is going to use C and python because they are well known and cross-platform. It is also useful to have a compiled example.

Project layout

This is also available in an archive.

-> build           # Where we are going to build our project
    -> [Empty Directory]
-> printer         # a library for printing things.
    -> printer.h
    -> printer.c
-> Hello World.py  # The main program.

---

--- Hello World.py ---
#! /usr/bin/env python

import os
os.system("./printer Hello World!")

---

--- printer/printer.c ---
#include <stdio.h>

int main ( int argc, char **argv )
{
    int i;
    for ( i = 1; i < argc; i++ )
        printf("%s ", argv[i]);

    putchar('\n');

    return 0;
}

The program is a two part program that prints "Hello World!" to standard output. Nothing too fancy.

BuildGen Files

BuildGen generates the project info by reading a select set of files. These files contain information that describe the project. In order to keep BuildGen simple for anyone to run these files have pre-determined names. There are two different files used to describe the project.

Buildroot

There is one Buildroot file in each project. It is located in the root directory of the project folder.

This Buildroot file is loaded before every other file. It describes project wide settings such as version numbers and compiler flags.

Buildinfo

The Buildinfo files are the files that do all of the work. They tell BuidGen what to compile and where to put it. It is good practice to have one Buildinfo file for each section of your project. This allows sections of the project to be build (along with all of their dependencies) with the same build configuration you would have if you built the whole project.

Writing the Files

Now that we have learned about the theory we will move into how it actually works. Since there is only one Buildroot per project and it is used by all files it seems like a pretty logical place to start.

Since or project is very simple there is not much we need to set up in the Buildroot. We could very likely get away with an empty one but, in the interest of learning we will put a little info in there now.

All we are going to put in our Buildroot (for now) is some project info so that whenever we need to use it from inside our Buildinfo's we will have the same thing. So create a Buildinfo file with these contents:

projectName = "Sample Project" -- These are not necessary but keep the project
version     = "1.0.0"          -- neat.

Pretty self-explanatory. Some keen observers have noticed the comment syntax and some might have thought of Lua. This is not a coincidence as all of BuildGen's configuration files are Lua scripts.

Please Note

While you can do a lot with Lua scripting, it is strongly advised not to create any files from BuildGen configuration files. This is because BuildGen is supposed to generate build scripts and the actual building of the project will be done afterwords. It is a much better practice to put your generation scripts and other programs inside another file and tell BuildGen about that.

The names "projectName" and "version" are almost completely arbitrary. The only thing to consider when choosing names is to ensure you names don't collide with BuildGen's commands. To make this easy for you BuildGen uses a simple naming scheme so that you can be sure that the next version of BuildGen will not use names that would collide with the ones you use in your project.

BuildGen's Naming Scheme

BuildGen organizes all of it's functions an variable names into namespaces. These namespaces (Lua tables) are all one capital letter. The current namespaces are; C the Co=ore namespace, D the Definitions namespace, S the Standard library namespace and L the user Libraries namespace. There is also a namespace called P for libraries to store data between Buildinfo files. You should not use this namespace as anything that you need to remember should be kept in your Buildroot.

Because of the naming scheme you know that anything that is not a one capital letter name will not interfere with BuildGen's framework and we will not interfere with your application in the future.

There is one more thing to remember. Once you import BuildGen's base standard library Penlight is also loaded into the global namespace. So it would be wise to try to avoid their names too.

Writing the Files (continued)

Now that we have our Buildroot set up we are going to start on our Buildinfo's. We will use one for our main program (Hello World.py) and one for our helper application (printer). We will start with our main program because we can fully install it without error. (except for the runtime error)

We will go step by step through the procedure. First, we will import the standard library. It contains an install function that makes installing files nice, easy and tidy. (It also allows us to install new programs without rebooting on UNIX)

S.import("stdlib")
   -- or --
S.import "stdlib"

Now we have the standard library loaded into S. Wait! you might say. We just called something from S, and you are absolutely right. Some basic functionality is loaded into S and L when the core (C) namespace is initialized so that they can load themselves.

The second way of writing it is just syntactic sugar via Lua's constructor call syntax.

Next we will tell BuildGen what to install where.

S.install("Hello World.py", "bin/")

Notice that there is not a full path to bin. The install prefix is added to the path. If you want to specify a full path just make sure it starts with a '/'. In BuildGen all path seperators will be represented as '/' and the correction will be preformed for other operating systems.

That is it for installing your main program. Your Buildinfo should now look like this:

S.import "stdlib"

S.install("Hello World.py", "bin/")

and your entire setup should look like this.