# Lantern Build Engine > A simple bash-based build engine for automating complex, fiddly, and boring development tasks. Wow, this ran away from me! This was initially a simple bash script for a private project of mine, but it seems to have turned into a general-purpose engine all by itself. I guess that stealing it for a bunch of University projects had something to do with that.... :P ## Installing The lantern build engine is meant to be included in your project as a git submodule. 1. Add this repository as a git submodule: `git submodule add {{clone-url}} {{path/to/destination-directory}}` 2. `source` the file `lantern.sh` into your build script. An example build script can be found in this repository - it's called `build-example`. ## Usage The lantern build engine basically exposes a set of utility function that make writing a flexible build script _much_ easier. Start by copying the example build script, and customising it to suit your own needs. Each task is a function that's prefixed with `task_`, so you can wire up task dependencies as complex or as simple as you like! At the end of your build script, execute the provided `tasks_run` function like this to execute all the requested tasks: `tasks_run $@` ### `set-title "{{title name}}"` Sets the title of the terminal the build script is running in. Has no effect if the build script isn't being run in a terminal as far as I'm aware. ```bash set-title "Current item: ${item_name}"; ``` ### `cursor_position {{x}} {{y}}` Sets the cursor's position on the screen. ```bash cursor_position 10 20; # Sets the cursor's position to (10, 20) ``` ### `cursor_up {{rows}}` Moves the cursor up by a specified number of rows. ```bash cursor_up 5; ``` ### `cursor_down {{rows}}` Moves the cursor down by a specified number of rows. ```bash cursor_down 5; ``` ### `cursor_left {{cols}}` Moves the cursor left by a specified number of columns. ```bash cursor_left 5; ``` ### `cursor_right {{cols}}` Moves the cursor right by a specified number of columns. ```bash cursor_right 5; ``` ### `cursor_save` Saves the cursor's current position. Takes no arguments. ```bash cursor_save; ``` ### `cursor_restore` Restores the cursor's position to the last saved position. Takes no arguments. ```bash cursor_restore; ``` ### `right_aligned_text {{width}} "{{text}}"` Right-aligns the specified text such that it's on the the right-hand-side of the terminal when `echo`ed. The `{{width}}` parameter here is the width of the provided text, as ANSI colour escape codes throw the width calculations off (a pull request fixing this would be most welcome!). ```bash right_aligned_text 12 "Hello, World!"; # Example output: " Hello, World!" (without quotes, of course) ``` ### `task_status {{2-char-code}}` Used internally. Generates a 2-character status code like OpenRC and others do in the terminal on startup. See the example for more details. ```bash set_status "!!"; # Output: "[ !! ]" (With the square brackets in bright blue) ``` ### `stage_begin "{{stage_name}}"` Begins a build stage. The output will fill the terminal's width. ```bash stage_begin "Building"; # Output for a 20 column wide terminal: # ----[ Building ]---- ``` ### `stage_end {{exit_code}}` Ends a stage, displaying either `ok` or `!!`, depending on whether the exit code provided is 0 or not (an exit code of 0 means success). The output will be coloured, of course - this isn't displayed below due to limitations in markdown. ```bash echo "Testing"; stage_end $?; # Output for a 20 column wide terminal: # -------[ ok ]------- ``` ### `task_begin "{{task_name}}"` Begins a task. Works similarly to `stage_begin` - the visuals are just different. ```bash task_begin "Checking environment"; # Output for: # * Checking environment ``` ### `task_end {{exit_code}}` The same as `stage_end`, but the visuals are a bit different. The 2-character status code (` [ xy ] `) is displayed at the right-hand side on the line above the line that the cursor is currently on. ```bash task_begin "Checking environment"; task_end 0; # Output: # " * Checking environment [ ok ] " (without quotes) ``` ```bash task_begin "Combobulating discombobulators"; # ...... task_end $?; ``` ...might output something like this: ``` * Combobulating discombobulators Output More output Even moar output Yay for output [ ok ] (cursor position is here) ``` ### `subtask_begin "{{task_name}}"` For splitting up your tasks even further! Generally, if you find yourself using a lot of these, try upgrading to stages and tasks instead of tasks and subtasks - particularly because these don't play so well with output, due to changing the colour of the asterisk (this may be fixed in the future, if the appropriate magic can be conjured :P). ```bash subtask_begin "Checking git"; # Output: " * \tChecking git" (without quotes, and replacing "\t" with a tab character) ``` ### `subtask_end {{exit_code}}` The counterpart to `subtask_begin`, this changes the asterisk colour and outputs a 2-character status code to complete a subtask. ```bash subtask_begin "Checking git"; which git 1>/dev/null 2>&1; subtask_end $?; # Output: # * \tChecking git [ ok ] # (replacing "\t" with a tab character) ``` ### `check_command "{{binary_name}} {{subtask}}"` Automagically checks for the presence of a command. Kills the process with an exit code of `2` if it can't be found. Setting `{{subtask}}` to a non-empty string causes `subtask_begin` / `subtask_end` to be called appropriately - otherwise it's invisible. ```bash task_begin "Checking environment"; check_command "git" true; check_command "msbuild" true; task_end 0; ``` ### `tasks_run {{task_name}} {{task_name}} .....` Runs the specified tasks in the specified order. Call this at the bottom of your build script. ```bash tasks_run setup; # Runs the task_setup function tasks_run build package; # Runs the build and package tasks as above tasks_run $@; # Passes all arguments (except the script name / path itself) to the task runner ``` ## Contributing Contributions are welcome! Simply fork this repository, make your changes, and submit a Pull Request (aka Merge Request). All contributions must be declared to have the `Mozilla Public License 2.0` (the same license that this repository is under). ## License The lantern build engine is licensed under the _Mozilla Public License 2.0_ (MPL-2.0). This license can be found in the _LICENSE_ file in this repository, along with a link to an easy-to-read summary.