In these examples, we will present the basic Lua Tupfile API and show how it relates to several small projects, then give an introduction to some of the helper API methods. A reference for all Lua API methods can be found here - not all API methods are demonstrated in the examples below.

### Compiling a Single Program

In this example, we will write a Lua Tupfile that compiles a small C program. The two key requirements for using Tup are 1. running tup init at the top of the project, and 2. Tupfile.lua.

In a new directory, run:

    $ tup init

and create the following files in the same directory:

hello.c

    #include <stdio.h>

    int main(void)
    {
    	printf("Hello, world!\n");
    	return 0;
    }

Tupfile.lua

    tup.definerule{ inputs = {'hello.c'}, command = 'gcc %f -o %o', outputs = {'hello'} }

Now, everything is prepared to compile. The current directory structure looks like this:

    $ ls -a
    .  ..  hello.c  .tup  Tupfile.lua

Compile the project by running:

    $ tup
    [ tup ] [0.134s] Scanning filesystem...
    [ tup ] [0.252s] Reading in new environment variables...
    [ tup ] [0.369s] Parsing Tupfiles...
     1) [0.008s] .
     [ ] 100%
    [ tup ] [0.388s] No files to delete.
    [ tup ] [0.388s] Generating .gitignore files...
    [ tup ] [0.530s] Executing Commands...
     1) [0.095s] gcc hello.c -o hello
     [ ] 100%
    [ tup ] [0.740s] Updated.
    $ ls -a
    .  ..  hello  hello.c  .tup  Tupfile.lua
    $ ./hello
    Hello, world!

### Compiling Multiple Programs

In this example, we will build off the previous project to build the similar program goodbye in addition to hello, using Lua functions to generalize build rule definition.

Create the following file in the same directory as the previous example:

goodbye.c

    #include <stdio.h>

    int main(void)
    {
    	printf("Goodbye, world!\n");
    	return 0;
    }

Replace the rules file with this new one:

Tupfile.lua

    function compile(source, output)
    	tup.definerule{ inputs = {source}, command = 'gcc %f -o %o', outputs = {output} }
    end

    compile('hello.c', 'hello')
    compile('goodbye.c', 'goodbye')

The current directory structure looks like this:

    $ ls -a
    .  ..  goodbye.c  hello  hello.c  .tup  Tupfile.lua

Build and test the programs:

    $ tup
    [ tup ] [0.000s] Scanning filesystem...
    [ tup ] [0.252s] Reading in new environment variables...
    [ tup ] [0.253s] Parsing Tupfiles...
     1) [0.006s] .
     [ ] 100%
    [ tup ] [0.264s] No files to delete.
    [ tup ] [0.264s] Generating .gitignore files...
    [ tup ] [0.509s] Executing Commands...
     1) [0.071s] gcc goodbye.c -o goodbye
     [ ] 100%
    [ tup ] [0.788s] Updated.
    $ ls -a
    .  ..  goodbye  goodbye.c  hello  hello.c  .tup  Tupfile.lua
    $ ./hello
    Hello, world!
    $ ./goodbye
    Goodbye, world!

Note that (if you copied everything verbatim) the command to build hello didn't change, nor did any of its dependencies, so Tup didn't rebuild it.

### Working With Multiple Directories

In this example, we place and build the program source files in their own directories for organizational purposes. We will use Tuprules.lua to store our common compile method to avoid duplicating it in each build directory.

Create directories and move the source files to get the following project structure:

    $ rm hello goodbye # They are in the way of the next steps
    $ rm Tupfile.lua
    $ mkdir hello
    $ mkdir goodbye
    $ mv hello.c hello/
    $ mv goodbye.c goodbye/

Tuprules.lua

    function compile(source, output)
    	tup.definerule{ inputs = {source}, command = 'gcc %f -o %o', outputs = {output} }
    end

hello/Tupfile.lua

    compile('hello.c', 'hello')

goodbye/Tupfile.lua

    compile('goodbye.c', 'goodbye')

The final directory structure should look like this:

    $ ls -a
    .  ..  goodbye  hello  .tup  Tuprules.lua
    $ ls -a hello
    .  ..  hello.c  Tupfile.lua
    $ ls -a goodbye
    .  ..  goodbye.c  Tupfile.lua

Tupfile.lua automatically includes Tuprules.lua in its current directory and parent directories, so we can access compile in hello/Tupfile.lua and goodbye/Tupfile.lua.

Build and test the programs. You can run tup from any location under the root of your project (where the Tupfile.ini lives, or where you ran tup init), but for the following listing we run everything in the top directory.

    $ tup
    [ tup ] [0.000s] Scanning filesystem...
    [ tup ] [0.286s] Reading in new environment variables...
    [ tup ] [0.287s] Parsing Tupfiles...
     1) [0.001s] .
     2) [0.001s] goodbye
     3) [0.001s] hello
     [   ] 100%
    [ tup ] [0.296s] No files to delete.
    [ tup ] [0.296s] Deleting 2 commands...
     [  ] 100%
    [ tup ] [0.297s] Generating .gitignore files...
    [ tup ] [0.532s] Executing Commands...
     1) [0.107s] goodbye: gcc goodbye.c -o goodbye
     2) [0.111s] hello: gcc hello.c -o hello
     [  ] 100%
    [ tup ] [0.877s] Updated.
    $ ls -a
    .  ..  goodbye  hello  .tup  Tuprules.lua
    $ ls -a hello/
    .  ..  hello  hello.c  Tupfile.lua
    $ ls -a goodbye/
    .  ..  goodbye  goodbye.c  Tupfile.lua
    $ ./hello/hello
    Hello, world!
    $ ./goodbye/goodbye
    Goodbye, world!

### Configuration And Selectively Sharing Code

You can split Lua Tupfiles as you see fit and selectively combine them using tup.include. In this example, we read the tup.config file to determine which modules to build, and only include the module's build definitions if enabled.

In a new directory, run:

    $ tup init

and create the following files in the same directory:

module1.c

    #include <stdio.h>

    int main(void)
    {
    	printf("Module 1 run.\n");
    	return 0;
    }

module2.c

    #include <stdio.h>

    int main(void)
    {
    	printf("Module 2 run.\n");
    	return 0;
    }

module1.lua

    compile('module1.c', 'module1')

module2.lua

    compile('module2.c', 'module2')

Tupfile.lua

    function compile(source, output)
    	tup.definerule{ inputs = {source}, command = 'gcc %f -o %o', outputs = {output} }
    end

    if tup.getconfig('MODULE1') == 'y' then
    	tup.include('module1.lua')
    end

    if tup.getconfig('MODULE2') == 'y' then
    	tup.include('module2.lua')
    end

tup.config

    CONFIG_MODULE1=n
    CONFIG_MODULE2=y

This will cause the module 2 build rule to be included and built, but not module 1. Note that tup.getconfig returns an empty string if the specified config value is missing. The way Tupfile.lua is set up, all modules are disabled by default.

The directory structure should look like this:

    $ ls -a
    .  ..  module1.c  module1.lua  module2.c  module2.lua  .tup  tup.config  Tupfile.lua

As usual, build and test with the following:

    $ tup
    [ tup ] [0.298s] Scanning filesystem...
    [ tup ] [0.917s] Reading in new configuration/environment variables...
     1) new variant: tup.config
     [ ] 100%
    [ tup ] [2.435s] Parsing Tupfiles...
     1) [0.007s] .
     [ ] 100%
    [ tup ] [2.442s] No files to delete.
    [ tup ] [2.443s] Generating .gitignore files...
    [ tup ] [3.755s] Executing Commands...
     1) [0.071s] gcc module2.c -o module2
     [ ] 100%
    [ tup ] [4.283s] Updated.
    $ ./module1
    bash: ./module1: No such file or directory
    $ ./module2
    Module 2 run.

### Helper API Methods

The following are not complete examples, but snippets and descriptions of their results when run.

    out = tup.frule{inputs = {'hello.c'}, command = 'gcc %f -o %o', outputs = {'%B'}}
    out = tup.frule{input = 'hello.c', command = 'gcc %f -o %o', output = '%B'}
    out = tup.rule('hello.c', 'gcc %f -o %o', '%B')

All of these are equivalent to tup.definerule{inputs = {'hello.c'}, command = 'gcc hello.c -o hello', outputs = {'hello'}}. out is {'hello'}. Note that using %f/%o is preferred if you intend to use variants.

    tup.frule{inputs = {'file1.c', 'file2.c'}, command = 'gcc %f -o %o', output = 'app'}

This is equivalent to tup.definerule{inputs = {'file1.c', 'file2.c'}, command = 'gcc file1.c file2.c -o app', outputs = {'app'}}.

    header = tup.rule('./generateheader.sh', {'generatedheader.h'})
    objects = tup.foreach_rule(
    	{
    		'file1.c',
    		'file2.c',
    		extra_inputs = header
    	},
    	'gcc %f -c -o %o',
    	{'%B.o'}
    )
    tup.rule(objects, 'gcc %f -o %o', {'app'})

This is equivalent to:

    tup.definerule{
    	inputs = {'file1.c', 'generatedheader.h'},
    	command = 'gcc file1.c -c -o file1.o',
    	outputs = {'file1.o'}
    }
    tup.definerule{
    	inputs = {'file2.c', 'generatedheader.h'},
    	command = 'gcc file2.c -c -o file2.o',
    	outputs = {'file2.o'}
    }
    tup.definerule{
    	inputs = {'file1.o', 'file2.o'},
    	command = 'gcc file1.o file2.o -c -o app',
    	outputs = {'app'}
    }

### Environment Variables And Globbing

Like the previous section, the following are not complete examples, but snippets and descriptions of their results when run.

    tup.export('SDK_PREFIX')
    tup.rule(tup.glob('*.c'), 'gcc %f -o %o -L$SDK_PREFIX/lib -lsdklib', {'app'})

In a directory with the files file1.c and file2.c, this is equivalent to:

    tup.definerule{inputs = {'file1.c', 'file2.c'}, command = 'gcc %f -o %o -L$SDK_PREFIX -lsdklib', outputs = {'app'}}

Note that $SDK_PREFIX is expanded by the shell and is treated the same as any other command substring by Tup. tup.export simply passes the value in the shell that invokes Tup to the shell that Tup invokes.