# shellbuild

shellbuild is an experimental build system meant to be tiny and easy to use. It has only a couple of functions and it's written in shell.

# using

Information here is subject to be changed. Please make sure to report inconsistencies.

## create a project

creating a project goes as follows:
 - create a new folder
 - optionally set up Git
 - if you decided to set up git, make sure to add `.sbcache` to the .gitignore (along with object files and other artifacts of course)
 - create a file called `sbrc` and mark it as executable

## configuration

**tip**: an example config file is available in the `example` subdirectory of this repository.

## sbrc structure

A `sbrc` is based on functions that can be called by itself or the user. These functions are always prefixed with an `_`.

The sbrc below would print `Hello!` when ran with `sb hello`.

```shell
_hello() {
    echo "Hello!"
}
```

When you run shellbuild, it simply loads the sbrc (and runs the function specified by the user.)

If no argument is passed to sb, it will try to run `__default` (yes, with **two** underscores):
```shell
__default() {
    echo "hello"
}
```
Running the example above with just `sb` would print `hello`.

## built-in functions

sb comes with a couple of built-in functions. Some of them are simply aliases to common commands to make your code more readable:
 - `match_files` runs `find` with the pattern provided as the first argument
 - `match_files_recurse` is like `match_files` but with no defined recursion limit
 - `ext` finds all files with the specified extension
 - `ext_all` finds all files with the specified extension but with no defined recursion limit.

## the `depends` built-in function

This function is so interesting that it deserves its own section. Every argument is either a file, or a function (prefixed by an underscore).

If any one of the files in the arguments has changed since the last time the program ran, it will echo `modified="FILES_CHANGED"`, where `FILES_CHANGED` is a space-separated list of all the files that changed since the last time the program ran.

If none of the files were modified, it will echo `return 3`.

You may notice that the output of this function looks like code. That's because it is! You're meant to eval its output, something like this: `eval $(depends mycfile.c _my_function)`.

This lets us make functions like this:
```shell
__default() {
    eval $(depends hello.c)
    echo "you will only see this message if hello.c was modified since the last time this program ran! cool, innit?"
}
```

## how the `depends` built-in function works

You don't really need to know this if you're making a simple program, but it can absolutely come in handy once you start working on more advanced sbrc's.

When ran, it will iterate through every argument passed to it and, if it comes across a file, it will create a corresponding file in the `.sbcache` directory. This file contains the last modified date of the source file. If the cache file exists, the time it was modified is comapred against the one in the cache. If they're different, it means it was changed.

If it comes across a function, it will call it. If that function's return status code is `3`, it is deemed as unchanged.

## notice

This project is just an experiment - I don't even know if it would work in a real-world project (I am yet to test that) or if it has some fundamental flaw.