Hello!

Let's start with Hello World: famously, the simplest project that does anything interesting. We'll write this one in C, but don't worry if you're not a C programmer. The focus isn't the C code itself, just to compile it.

To play with the code on your own machine, get the redo source code and look in the docs/cookbook/hello/ directory.

Compiling the code

First, let's create a source file that we want to compile:

Now we need a .do file to tell redo how to compile it:

With those files in place, we can build and run the program:

$ redo hello
redo  hello

$ ./hello
Hello, world!

Use the redo command to forcibly re-run a specific rule (in this case, the compiler). Or, if you only want to recompile hello when its input files (dependencies) have changed, use redo-ifchange.

$ redo hello
redo  hello

# Rebuilds, whether we need it or not
$ redo hello
redo  hello

# Does not rebuild because hello.c is unchanged
$ redo-ifchange hello

$ touch hello.c

# Notices the change to hello.c
$ redo-ifchange hello
redo  hello

Usually we'll want to also provide an all.do file. all is the default redo target when you don't specify one.

With that, now we can rebuild our project by just typing redo:

$ rm hello

# 'redo' runs all.do, which calls into hello.do.
$ redo
redo  all
redo    hello

# Notice that this forcibly re-runs the 'all'
# rule, but all.do calls redo-ifchange, so
# hello itself is only recompiled if its
# dependencies change.
$ redo
redo  all

$ ./hello
Hello, world!

Debugging your .do scripts

If you want to see exactly which commands are being run for each step, you can use redo's -x and -v options, which work similarly to sh -x and sh -v.

$ rm hello

$ redo -x
redo  all
* sh -ex all.do all all all.redo2.tmp
+ redo-ifchange hello

redo    hello
* sh -ex hello.do hello hello hello.redo2.tmp
+ redo-ifchange hello.c
+ cc -o hello.redo2.tmp hello.c -Wall
redo    hello (done)

redo  all (done)

Running integration tests

What about tests? We can, of course, compile a C program that has some unit tests. But since our program isn't very complicated, let's write a shell "integration test" (also known as a "black box" test) to make sure it works as expected, without depending on implementation details:

Even if we rewrote our hello world program in python, javascript, or ruby, that integration test would still be useful.

Housekeeping

Traditionally, it's considered polite to include a clean rule that restores your project to pristine status, so people can rebuild from scratch:

Some people like to include a .gitignore file so that git won't pester you about files that would be cleaned up by clean.do anyway. Let's add one:

.gitignore
hello
~
.~

Congratulations! That's all it takes to make your first redo project.

Here's what it looks like when we're done:

$ ls
all.do  clean.do  hello.c  hello.do  test.do

Some people think this looks a little cluttered with .do files. But notice one very useful feature: you can see, at a glance, exactly which operations are possible in your project. You can redo all, clean, hello, or test. Since most people downloading your project will just want to build it, it's helpful to have the available actions so prominently displayed. And if they have a problem with one of the steps, it's very obvious which file contains the script that's causing the problem.