toke/README.md

Toke - TOML-based Command runner

Toke (TOML Make) is a simple command runner inspired by Make but uses TOML (Tom's Obvious, Minimal Language) instead of Makefiles. This project was created for fun as an alternative to Make, because I was looking for a simple command runner/build system but didn't like the Makefile syntax.

How to use toke

Toke works by reading a TOML file named tokefile.toml (or any variation of it like Tokefile.toml, tokefile, etc.) in your project directory. This file contains definitions of variables, targets, and their respective commands.

You can also pass in a file to be used instead of the default one.

toke -f my_custom_named_toke_file

To run a toke target, just run toke target_name_here

For example:

toke build

Toke then reads the TOML file, resolves variables, and then executes the specified commands for the target you provide.

It also checks for dependency cycles in your targets to prevent infinite loops.

Example Tokefile

[vars]
cc = "gcc"

[targets.build]
vars.cc = "clang"
cmd = "${cc} main.c -o main"

[targets.run]
cmd = "./main arg1 arg2"
deps = ["build"]

Because TOML has several ways of defining the same structure, here is a JSON representation of the above TOML file to make it easier to understand.

You can write your TOML file in any way you wish as long as it's structure is in the same style as the following JSON.

{
  "vars": {
    "cc": "gcc"
  },
  "targets": {
    "build": {
      "vars": {
        "cc": "clang"
      },
      "cmd": "${cc} main.c -o main"
    },
    "run": {
      "cmd": "./main arg1 arg2",
      "deps": ["build"]
    }
  }
}

In this example:

We define a variable cc which is set to "gcc".

We have two targets: build and run.

The build target compiles the code with clang.

The run target runs the code with some arguments. It also depends on the build target.

Variables

Global variables

You can define global variables in the vars table, as seen in the above example.

Local variables

You can specify local variables for each target. These local variables are defined under the vars key within each target section. If the local variable name matches a global variable, it will overwrite the global variable value for that specific target.

Here is an example:

[vars]
cc = "g++"

[target.target1]
vars.cc = "gcc"
cmd="${cc} ${cflags} main.c -o main"

[target.target2]
vars.cc = "clang"
vars.cflags = "-Wall"
cmd="${cc} ${cflags} main.c -o main"

[target.target3]
vars.cflags = "-O3"
cmd="${cc} ${cflags} main.c -o main"

In this example:

target1 uses gcc for the cc variable, overriding the global value.

target2 specifies clang for the cc variable and adds -Wall to cflags.

target3 only sets cflags to -O3.

Command line overrides

Additionally, you can override both global and local variables via command line arguments when invoking toke. Command line arguments follow the format VARIABLE=value. When provided, these values will overwrite any corresponding global or local variables.

Here's an example of using command line arguments:

toke build CC=gcc CFLAGS=-O2

In this example:

CC=gcc overrides the value of the cc variable.

CFLAGS=-O2 overrides the value of the cflags variable.

These overrides allow for flexible customization.

Contributing

Contributions are welcome! Feel free to submit issues or pull requests to help improve Toke.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Toke is a fun experiment aiming to simplify build systems using the TOML format. Give it a try and see if it suits your project needs better than traditional build systems like Make!