zeus by dreadl0ck

ZEUS is a modern build system featuring support for writing build targets in multiple scripting languages, an interactive shell with tab completion and customizable ANSI color profiles as well as support for keybindings.

It parses the zeus directory in your project, to find commands either via a single file zeus/commands.yml or via scripts in the zeus/scripts directory.

A command can have typed parameters and commands can be chained. Each command can have dependencies which will be resolved prior to execution, similar to GNU Make targets.

For each dependency target outputs can be defined, the target will be skipped if all named outputs exist. You can export global variables and functions visible to all scripts.

The Event Engine allows the user to register file system events, and run custom shell or ZEUS commands when an event occurs.

ZEUS also features an auto formatter for shell scripts, a bootstrapping functionality and a rich set of customizations available by using a config file.

ZEUS can save and restore project specific data such as events, keybindings, aliases, milestones, author, build number and a project deadline.

YAML is used for serialization of the zeus/config.yml, zeus/data.yml and zeus/commands.yml files.

ZEUS was designed to happily coexist with GNU Make, and offers a builtin Makefile command overview and migration assistance.

The 1.0 Release will feature an optional webinterface, markdown / HTML report generation and an encrypted storage for sensitive information.

The name ZEUS refers to the ancient greek god of the sky and thunder.

When starting the interactive shell there is a good chance you will be struck by a lighting and bitten by a cobra, which could lead to enormous super coding powers!

Project Page

Changelog

Wiki

NOTE: ZEUS is still under active development There will be regular updates so make sure to update your build from time to time. Please read the BUGS section to see whats causing trouble as well as the COMING SOON section to get an impression of whats coming up for version 1.0

See ZEUS in action:

The Dark Mode does not work in terminals with a black background, because it contains black text colors. I recommend using the solarized dark terminal theme, if you want to use the dark mode.

Index

Preface
Installation
- Homebrew
- Github
- Tools
- Development
Try it out
Configuration
Interactive Shell
Builtins
Commandsfile
Globals
Command Data
- Description
- Help
- Outputs
- Dependencies
- Async
- Exec
- Path
- Arguments
- Language
- Build Number
Internals
License
Contact

Preface

Why not GNU Make?

GNU Make has its disadvantages: For large projects you will end up with few hundred lines long Makefile, that is hard to read, overloaded and annoying to maintain.

Also writing pure shell is not possible, instead the make shell dialect is used. If you ever tried writing an if condition in a Makefile you will know what I’m talking about ;)

My goal was to offer extended functionality and usability, with better structuring options for large projects and the programmers choice of his favourite scripting language.

ZEUS keeps things structured and reusable, the scripts can also be executed manually without ZEUS if needed (you can generate a standalone version of them with the generate builtin).

Also, generic scripts can be reused in multiple projects.

Similar to GNU Make, ZEUS offers stopping shellscript execution, if a line returned an error code != 0.

This Behaviour can be disabled in the config by using the StopOnError option. Other languages such as python or ruby have this behaviour by default.

Signals to the ZEUS shell will be passed to the scripts, that means handling signals inside the scripts is possible.

Terminology

Command Prompts:

# shell commands
$ ls

# ZEUS interactive shell prompt
zeus »

Usage Descriptions:

# no parentheses: built in commands
# [] parentheses: optional parameters
# <> parentheses: values that need to be supplied by the user
milestones [remove <name>] [set <name> <0-100>] [add <name> <date> [description]]

Installation

Homebrew

$ brew tap dreadl0ck/formulas
$ brew install zeus

Github

$ go get -v -u github.com/dreadl0ck/zeus

NOTE: This might take a while, because some assets are embedded into the binary to make it position independent. Time to get a coffee

ZEUS uses ZEUS as its build system! After the initial install simply run zeus inside the project directory, to get the command overview.

Tools

I also recommend installing the amazing micro text editor, as this is the default editor for the edit command. Don’t worry you can also use vim if desired.

Also nice to have is the cloc tool, which means count lines of code and is used for the info builtin.

OSX Users can grab both with:

$ brew install cloc micro
...

Development

When developing compile with: (this compiles without assets and is much faster)

$ zeus/scripts/dev.sh
...

Try it out

After installation, cd into the project repository and run zeus.

This will show you the way ZEUS is used to compile itself. Run edit commands to look at the projects commands.yml

For more complex examples, move into the tests directory and run zeus there. You will find examples for arguments, async commands, dependencies and multi language setups there. Run edit commands to look at the projects commands.yml to see how things work there.

Configuration

The config file zeus/config.yml allows various customizations.

When a ZEUS instance is running in interactive mode, this file is being watched and parsed when a WRITE event occurs.

ZEUS will warn you about unknown config fields.

However, the builtin config command is recommended for editing the config, it features tab completion for all config fields, actions and values.

Usage:
config [get <field>]
config [set <field> <value>]

Config Options:

Option	Type	Description
makefileOverview	bool	print the makefile target overview when starting zeus
autoFormat	bool	enable / disable the auto formatter
colors	bool	enable / disable ANSI colors
passCommandsToShell	bool	enable / disable passing unknown commands to the shell
webInterface	bool	enable / disable running the webinterface on startup
interactive	bool	enable / disable interactive mode
debug	bool	enable / disable debug mode
recursionDepth	int	set the amount of repetitive commands allowed
projectNamePrompt	bool	print the projects name as prompt for the interactive shell
allowUntypedArgs	bool	allow untyped command arguments
colorProfile	string	current color profile
historyFile	bool	save command history in a file
historyLimit	int	history entry limit
exitOnInterrupt	bool	exit the interactive shell with an SIGINT (Ctrl-C)
disableTimestamps	bool	disable timestamps when logging
stopOnError	bool	stop script execution when there’s an error inside a script
dumpScriptOnError	bool	dump the currently processed script into a file if an error occurs
dateFormat	string	set the format string for dates, used by deadline and milestones
todoFilePath	string	set the path for your TODO file, default is: “TODO.md”
editor	string	configure editor for the edit builtin
colorProfiles	map[string]*ColorProfile	add custom color profiles
languages	[]*Language	add custom language definitions

NOTE: when modifying the Debug or Colors field, you need to restart zeus in order for the changes to take effect. That’s because the Log instance is a global variable, and manipulating it on the fly produces data races.

Interactive Shell

ZEUS has a built in interactive shell with tab completion for all its commands! All scripts inside the zeus/scripts/ directory will be treated and parsed as commands.

To start the interactive shell inside your project, simply run:

$ cd project_folder
$ zeus
...

This will print all available commands, their description, arguments, dependencies, outputs etc To get a quick overview whats available for the current project.

Default Readline Keybindings

The Interactive Shell uses the readline library, here are the default Keybindings:

Meta+B means press Esc and n separately. Users can change that in terminal simulator(i.e. iTerm2) to Alt+B Notice: Meta+B is equals with Alt+B in windows.

Shortcut in normal mode

Shortcut	Comment
`Ctrl`+`A`	Beginning of line
`Ctrl`+`B` / `←`	Backward one character
`Meta`+`B`	Backward one word
`Ctrl`+`C`	Send io.EOF
`Ctrl`+`D`	Delete one character
`Meta`+`D`	Delete one word
`Ctrl`+`E`	End of line
`Ctrl`+`F` / `→`	Forward one character
`Meta`+`F`	Forward one word
`Ctrl`+`G`	Cancel
`Ctrl`+`H`	Delete previous character
`Ctrl`+`I` / `Tab`	Command line completion
`Ctrl`+`J`	Line feed
`Ctrl`+`K`	Cut text to the end of line
`Ctrl`+`L`	Clear screen
`Ctrl`+`M`	Same as Enter key
`Ctrl`+`N` / `↓`	Next line (in history)
`Ctrl`+`P` / `↑`	Prev line (in history)
`Ctrl`+`R`	Search backwards in history
`Ctrl`+`S`	Search forwards in history
`Ctrl`+`T`	Transpose characters
`Meta`+`T`	Transpose words (TODO)
`Ctrl`+`U`	Cut text to the beginning of line
`Ctrl`+`W`	Cut previous word
`Backspace`	Delete previous character
`Meta`+`Backspace`	Cut previous word
`Enter`	Line feed

Shortcut in Search Mode (Ctrl+S or Ctrl+r to enter this mode)

Shortcut	Comment
`Ctrl`+`S`	Search forwards in history
`Ctrl`+`R`	Search backwards in history
`Ctrl`+`C` / `Ctrl`+`G`	Exit Search Mode and revert the history
`Backspace`	Delete previous character
Other	Exit Search Mode

Shortcut in Complete Select Mode (double Tab to enter this mode)

Shortcut	Comment
`Ctrl`+`F`	Move Forward
`Ctrl`+`B`	Move Backward
`Ctrl`+`N`	Move to next line
`Ctrl`+`P`	Move to previous line
`Ctrl`+`A`	Move to the first candidate in current line
`Ctrl`+`E`	Move to the last candidate in current line
`Tab` / `Enter`	Use the word on cursor to complete
`Ctrl`+`C` / `Ctrl`+`G`	Exit Complete Select Mode
Other	Exit Complete Select Mode

Shell Integration

When ZEUS does not know the command you typed it will be passed down to the underlying shell. That means you can use git and all other shell tools without having to leave the interactive shell!

This behaviour can be disabled by using the PassCommandsToShell option. There is path and command completion for basic shell commands (cat, ls, ssh, git, tree etc)

Remember: Events, Aliases and Keybindings can contain shell commands!

NOTE: Multilevel path completion is broken, I’m working on a fix.

Bash Completions

If you also want tab completion when not using the interactive shell, install the bash-completion package which is available for most linux distros and macOS.

on macOS you can install it with brew:

brew install bash-completion

on linux use the package manager of your distro.

Then add the completion file files/zeus to:

macOS: /usr/local/etc/bash_completion.d/
Linux: /etc/bash_completion.d/

and source it with:

macOS: . /usr/local/etc/bash_completion.d/zeus
Linux: . /etc/bash_completion.d/zeus

Direct Command Execution

You don’t need the interactive shell to run commands, just use the following syntax:

$ zeus [commandName] [args]
...

This is useful for scripting or using ZEUS from another programming language. Note that you can use the bash-completions package and the completion script files/zeus to get tab completion on the shell.

Builtins

ZEUS includes a lot of useful builtins, the following builtin commands are available:

Command	Description
format	run the formatter for all scripts
config	print or change the current config
deadline	print or change the deadline
version	print zeus version
data	print the current project data
makefile	show or migrate GNU Makefile contents
milestones	print, add or remove the milestones
events	print, add or remove events
exit	leave the interactive shell
help	print the command overview or the manualtext for a specific command
info	print project info (lines of code + latest git commits)
author	print or change project author name
clear	clear the terminal screen
globals	print the current globals
alias	print, add or remove aliases
color	change the current ANSI color profile
keys	manage keybindings
web	start webinterface
wiki	start web wiki
create	bootstrap a single command
git-filter	filter git log output
todo	manage todos
update	update zeus version
procs	manage spawned processes
edit	edit scripts
generate	generate standalone version of a script or commandChain

you can list them by using the builtins command.

The default Editor for the edit command is micro Fallback is vim, but you can configure your desired editor in the config.

Some will be explained in more detail below, the rest of the builtins is explained in different sections.

Edit Builtin

usage: edit [ <commandName> | config | globals | commands ] [ line <number> ]

The edit builtin allows you to modify scripts without leaving the interactive shell using your favourite editor! Default is micro, fallback is vim, but can also use the Editor config field to set a custom editor.

When the project uses a Commandsfile, the edit builtin will load the Commandsfile at the correct position of the requested command. Use the line subcommand to jump to the desired line.

Also editing config, data and globals is possible.

It does also play nice with the builtin shellscript formatter.

NOTE: Hit tab to see available commands to edit

Default Micro Keybindings

The micro editor comes with syntax highlighting for over 90 languages by default, and offers the following keybindings:

{
    "ShiftUp":        "SelectUp",
    "ShiftDown":      "SelectDown",
    "ShiftLeft":      "SelectLeft",
    "ShiftRight":     "SelectRight",
    "AltLeft":        "WordLeft",
    "AltRight":       "WordRight",
    "AltShiftRight":  "SelectWordRight",
    "AltShiftLeft":   "SelectWordLeft",
    "AltUp":          "MoveLinesUp",
    "AltDown":        "MoveLinesDown",
    "CtrlLeft":       "StartOfLine",
    "CtrlRight":      "EndOfLine",
    "CtrlShiftLeft":  "SelectToStartOfLine",
    "ShiftHome":      "SelectToStartOfLine",
    "CtrlShiftRight": "SelectToEndOfLine",
    "ShiftEnd":       "SelectToEndOfLine",
    "CtrlUp":         "CursorStart",
    "CtrlDown":       "CursorEnd",
    "CtrlShiftUp":    "SelectToStart",
    "CtrlShiftDown":  "SelectToEnd",
    "CtrlH":          "Backspace",
    "Alt-CtrlH":      "DeleteWordLeft",
    "Alt-Backspace":  "DeleteWordLeft",
    "CtrlO":          "OpenFile",
    "CtrlS":          "Save",
    "CtrlF":          "Find",
    "CtrlN":          "FindNext",
    "CtrlP":          "FindPrevious",
    "CtrlZ":          "Undo",
    "CtrlY":          "Redo",
    "CtrlC":          "Copy",
    "CtrlX":          "Cut",
    "CtrlK":          "CutLine",
    "CtrlD":          "DuplicateLine",
    "CtrlV":          "Paste",
    "CtrlA":          "SelectAll",
    "CtrlT":          "AddTab",
    "Alt,":           "PreviousTab",
    "Alt.":           "NextTab",
    "Home":           "StartOfLine",
    "End":            "EndOfLine",
    "CtrlHome":       "CursorStart",
    "CtrlEnd":        "CursorEnd",
    "PageUp":         "CursorPageUp",
    "PageDown":       "CursorPageDown",
    "CtrlG":          "ToggleHelp",
    "CtrlR":          "ToggleRuler",
    "CtrlL":          "JumpLine",
    "Delete":         "Delete",
    "CtrlB":          "ShellMode",
    "CtrlQ":          "Quit",

    // Emacs-style keybindings
    "Alt-f": "WordRight",
    "Alt-b": "WordLeft",
    "Alt-a": "StartOfLine",
    "Alt-e": "EndOfLine",
    "Alt-p": "CursorUp",
    "Alt-n": "CursorDown",
}

Generate Builtin

usage: generate <outputName> <commandChain>

The generate builtin generates a standalone version of a single command or commandChain.

If all commands are of the same language, a single script is generated. If there are multiple scripting languages involved, a directory is generated with all required scripts and a run.sh script, that executes the first element of the commandChain.

examples:

# generate a standalone version of the build command, with all globals and dependencies
zeus » generate build.sh build

# generate a standalone version of the commandChain, with all globals and dependencies
# scenario1: only shell scripts
zeus » generate deploy_server.sh clean -> configure -> build -> deploy ip=167.149.1.2

# scenario2: mixed languages
# this will create a deploy_server directory with all required scripts and generated code to execute them in the order of the commandChain
zeus » generate deploy_server clean -> configure -> build -> deploy ip=167.149.1.2

Create Builtin

 usage: create [<language> <commandName>] [script <all> | <commandName>]

The create builtin can be used for 2 purposes:

1) bootstrap a new command and start the editor

zeus » create python newPythonCommand

A new python command will be appended to the commandsFile and the editor will be launched.

2) write the exec section of a command to a file

zeus » create script build

Assuming build is shellscript, the exec section will be written to zeus/scripts/build.sh and stripped from the commandsFile

Todo Builtin

usage: todo [add <task>] [remove <index>]

The todo builtin is a simple tool for working with TODO.md files, it allows you to list, add and remove tasks in the interactive shell.

A task is considered a note with prefix: -

Default path for todo file is TODO.md in the root of the project.

You can specify a custom path in the config, using the TodoFilePath field.

Procs Builtin

usage: procs [detach <command>] [attach <pid>] [kill <pid>]

The procs builtin allows you to detach commands (execute them async), list or kill spawned processes and attach Stdin + Stdout + Stderr to a running process.

NOTE: there are tab completions for PIDs

Git Filter Builtin

usage: git-filter [keyword]

A very simple filter for git commits, outputs one commit per line and can be filtered for keywords like using the UNIX grep command.

NOTE: This is still work in progress

Aliases

You can specify aliases for ZEUS or shell commands. This is handy when using commands with lots of arguments, or for common git or ssh operations.

Aliases will be added to the tab completer, saved in the project data and restored every time you run ZEUS.

zeus » alias set gs git status
zeus » gs
On branch master
Your branch is up-to-date with 'origin/master'.
Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git checkout -- <file>..." to discard changes in working directory)
...

Running alias without params will print the current aliases:

zeus » alias
gs = git status

Events

Events for the following filesystem operations can be created: WRITE

REMOVE

RENAME

CHMOD

When an operation of the specified type occurs on the watched file (or on any file inside a directory), a custom command is executed. This can be a ZEUS or any shell command.

Events can be bound to a specific file type, by supplying the filetype before the command:

zeus » events add WRITE docs/ .md say hello

Filetypes feature completion, just specify the directory and hit tab to see a list of filetypes inside the directory.

Example for a simple WRITE event on a single file:

zeus » events add WRITE TODO.md say updated TODO

Running events without params will print the current events:

zeus » events
custom event        a63d8659d6243630    WRITE               say wiki updated    .md               wiki/
config event        58c41a66bf6efde4    WRITE               internal            .yml               zeus/config.yml

Note that you can also see the internal ZEUS events used for watching the config file, and for watching the shellscripts inside the zeus directory to run the formatter on change.

For removing an event specify its path:

zeus » events remove TODO.md
  INFO removed event with name TODO.md

Milestones

For a structured workflow milestones can be created.

A Milestone tracks the progress of a particular programming task inside the project, and contains an expected date and an optional description.

Usage: milestones [remove ] milestones [set <0-100>] milestones [add [description]]

Add a milestone to the project:

zeus » milestones add Testing 12-12-2018 Finish testing
  INFO added milestone Testing

list the current milestones with:

zeus » milestones
Milestones:
# 0 [                    ] 0% name: Testing date: 12-12-2018 description: Finish testing

set a milestones progress with:

zeus » milestones set Testing 50
zeus » milestones
Milestones:
# 0 [==========          ] 50% name: Testing date: 12-12-2018 description: Finish testing

Project Deadline

Usage:
deadline [remove]
deadline [set <date>]

A global project Deadline can also be set:

zeus » deadline set 24-12-2018
  INFO added deadline for 24-12-2018

get the current deadline with:

zeus » deadline
Deadline: 24-12-2018

Keybindings

Keybindings allow mapping ZEUS or shell commands to Ctrl-[A-Z] Key Combinations.

Usage:
keys [set <KeyComb> <commandChain>]
keys [remove <KeyComb>]

To see a list of current keybindings, run keys in the interactive shell:

zeus » keys
Ctrl-B = build
Ctrl-S = git status
Ctrl-P = git push

To set a Keybinding:

zeus » keys set Ctrl-H help

NOTE: use [TAB] for completion of available keybindings

To remove a Keybinding:

zeus » keys remove Ctrl-H

NOTE: some key combination such as Ctrl-C (SIGINT) are not available because they are handled by the shell

Auto Formatter

The Auto Formatter watches the scripts inside the zeus directory and formats them when a WRITE Event occurs.

Currently this is only available for Shellscripts, but I plan to add formatters for more languages & add an option to add custom ones.

However changing the file contents while your IDE holds a buffer of it in memory, does not play well with all IDEs and Editors and should ideally be implemented as IDE Plugin.

My IDE (VSCode) complains sometimes that the content on disk is newer, but most of the time its works ok. Please note that for VSCode you have to CMD-S twice before the buffer from the IDE gets written to disk.

NOTE: Since this causes trouble with most IDEs and editors, its disabled by default You can enable this feature in the config if you want to try it with your editor When setting the AutoFormat Option to true, the DumpScriptOnError option will also be enabled

Formatting seems to work well with the micro editor, so when editing your scripts with the edit builtin, try it out!

ANSI Color Profiles

Colors are used for good readability and can be configured by using the config file.

You can add multiple color profiles and configure them to your taste.

there are 5 default profiles: dark, light, default, off, black

To change the color profile to dark:

zeus » colors dark

NOTE: dark mode is strongly recommended :) use the solarized dark theme for optimal terminal background.

For configuring color profiles in the config, use the style format from the ansi go package:

ANSI Style Format

"foregroundColor+attributes:backgroundColor+attributes"

Colors

black
red
green
yellow
blue
magenta
cyan
white
0…255 (256 colors)

Foreground Attributes

B = Blink
b = bold
h = high intensity (bright)
i = inverse
s = strikethrough
u = underline

Background Attributes

h = high intensity (bright)

Makefile Integration

By using the makefile command you can get an overview of targets available in a Makefile:

zeus » makefile
available GNUMake Commands:
~> clean
~> configure
~> status
~> backup
~> bench: build
~> test: clean
~> debug: build
~> build: clean
~> deploy

This might be helpful when switching to ZEUS or when using both for whatever reason.

Currently the following actions are performed:

globals will be extracted and put into the zeus/globals.sh file
variable conversion from ‘$(VAR)’ to the bash dialect: ‘$VAR’
shell commands will be converted from ‘@command’ to ‘command’
calls to ‘make target’ will be replaced with ‘zeus target’
if statements will be converted to bash dialect

NOTE: Makefile migration is not yet perfect! Always look at the generated files, and check if the output makes sense. Especially automatic migration of make target arguments has not been implemented yet. Also switch statement conversion is currently missing.

Makefile Migration Assistance

ZEUS helps you migrate from Makefiles, by parsing them and transforming the build targets into a ZEUS structure. Your Makefile will remain unchanged, Makefiles and ZEUS can happily coexist!

simply run this from the interactive shell:

zeus » makefile migrate

or from the commandline:

$ zeus makefile migrate
~> clean
~> configure
~> status
~> backup
...
[INFO] migration complete.

Your makefile will remain unchanged. This command creates the zeus directory with your make commands as ZEUS scripts. If there are any global variables declared in your Makefile, they will be extracted and put into the zeus/globals.sh file.

Bootstrapping

When starting from scratch, you can use the bootstrapping functionality:

$ zeus bootstrap
...

This will create the zeus folder, and bootstrap the basic commands (build, clean, run, install, test, bench), including a commands.yml file. Happy Coding!

Webinterface

The Webinterface will allow to track the build status and display project information, execute build commands and much more!

Communication happens live over a websocket.

When WebInterface is enabled in the config the server will be started when launching ZEUS. Otherwise use the web builtin to start the server from the shell.

NOTE: This is still work in progress

Markdown Wiki

A Markdown Wiki will be served from the projects wiki directory.

All Markdown Documents in the wiki/docs folder can be viewed in the browser, which makes creating good project docs very easy.

The wiki/INDEX.md file will be converted to HTML and inserted in main wiki page.

Command Chains

Targets (aka commands) can be chained, using the -> operator

By using the dependencies field you can specify a command chain (or a single command), that will be run before execution of the target script.

Individual commands from this chain will be skipped if they have outputs that do already exist!

This command chain will be executed from left to right, each of the commands can also contain dependencies and so on.

You can also assemble & run command chains in the interactive shell. This is useful for testing chains and see the result instantly.

A simple example:

# clean the project, build for amd64 and deploy the binary on the server
zeus » clean -> build-amd64 -> deploy

Commandsfile

Similar to GNU Make, ZEUS allows adding all targets to a single file named commands.yml inside the zeus directory. This is useful for small projects and you can still use the interactive shell if desired.

The File follows the YAML specification.

ZEUS will warn you about about unknown fields, duplicate command names and global variables. Cyclic commandchains produce an error at runtime.

There is an example commands.yml in the tests directory. A watcher event is automatically created for parsing the file again on WRITE events.

Use the globals section to export global variables and function to all commands.

If you want to move to a zeus directory structure after a while, use the create builtin:

zeus » create script all
migrated  10  commands from Commandsfile in:  4.575956ms

This will write the exec section of each command into a separate script in zeus/scripts and strip the section from your commandsFile.

If an error occurs, ZEUS will print a snippet of the generated script and highlight the corresponding line.

Globals

Globals allow you to declare variables and functions in global scope and share them among all ZEUS scripts.

You have two options:

globals section in your commands.yml for global variables visible to all scripts
zeus/globals/globals.[scriptExtension] for language specific code such as functions

NOTE: Your current shells environment will be passed to each executed command. That means global variables from ~/.bashrc or ~/.bash_profile are accessible by default

Globals will be accessible in your scripts as normal variables!

Command Data

Scripts supply information in the zeus/commands.yml file.

A simple ZEUS command could look like this:

exampleCommand:
    dependencies: clean
    outputs:
        - bin/zeus
    description: build project
    buildNumber: true
    exec: go build -o bin/zeus
    help: |
        zeus build script
        this script produces the zeus binary
        it will be be placed in bin/zeus

Fields:

Field	Type	Description
dependencies	[]string	dependencies for the current command
description	string	short description text for command overview
help	string	help text for help builtin
outputs	[]string	output files of the command
buildNumber	bool	increase build number when this field is present
async	bool	detach script into background
arguments	[]string	list of typed arguments, allows optionals and default values
path	string	custom path for script file
exec	string	supply script directly

All data fields are optional. Just throw your scripts into zeus/scripts/ fire up the interactive shell and start hacking!

The help text can be accessed by using the help builtin:

zeus » help build

zeus build script
this script produces the zeus binary
it will be be placed in bin/zeus

Description

ZEUS uses the description field for a short description text, which will be displayed on startup by default or when using the help builtin without params.

Help

A multiline help text can be set for each script by using the help field.

zeus » help <command>

You can get the projects command overview at any time just type help in the interactive shell:

zeus » help

Outputs

For each target you can define multiple outputs files with the outputs field. When all of them exist, the command will not be executed again.

example:

outputs:
    - bin/file1
    - bin/file2

Dependencies

The dependencies field allows you to specify multiple commands, that will be executed in the declared order, prior to the execution of the current command.

A Dependency will be skipped if all its outputs files or directories exist.

Since Dependencies are ZEUS commands, they can have arguments.

example:

dependencies:
    - command1 <arg1> <arg2>
    - command2 <arg1>
    - command3

Async

The async field allows to run a command in the background. It will be detached with the UNIX screen command and you can attach to its output at any time using the procs builtin.

This can be used to speed up builds with lots of targets that don’t have dependencies between them, or to start multiple services in the background.

The procs builtin can be used to list all running commands, to attach to them or to detach non-async commands in the background.

Exec

The exec field allows to specify the code to run directly in the commandsfile.

If this field is empty or missing, ZEUS assumes your script resides in the zeus/scripts/ directory, and has the name commandName.[fileExtension]

Path

The path field allows to specify a custom path for the script.

If a command has a custom path set and an exec action specified an error is thrown upon command initialization.

Arguments

ZEUS supports typed command arguments.

To declare them, supply a comma separated list to the zeus-args field, following this scheme: label:Type

Available types are: Int, String, Float, Bool

Arguments are being passed in the label=val format:

zeus » build name=testbuild

The order in which they appear does NOT matter (because of the labels)

It is also possible to create optional arguments: label:Type?

They won’t be required for executing the command, and if no value was supplied they will be initialized with the zero value for their data type

You can set a default value for optional arguments: label:Type? = value

Lets look at an example for declaration:

argumentTest:
    description: test optional args
    arguments:
        - name:String? = "defaultName"
        - author:String
        - ok:Bool?
        - count:Int?

Here’s an example of how this looks like in the interactive shell:

commands
├─── build (binName: String)
|    ├─── dependencies  clean -> configure
|    ├─── buildNumber
|    └─── description   build project for current OS
|
├─── argTest (author:String, ok:Bool?, count:Int?, name:String? = "defaultName")
|    ├─── dependencies  clean -> configure
|    └─── description   demonstrate arguments

The build command has one argument with the label ‘binName’, its a string and its required.

NOTE: there will be a parse error if an argument label shadows a global, because both share the same name.

The argTest command has 4 arguments, 3 of them are optional. The only one required is the ‘author’ argument.

NOTE: required args will always appear first in the list of arguments. If dismissed ‘name’ will be initialized with ‘defaultName’, the rest will be set to the zero values of their data types. (false, 0)

Accessing the arguments inside your scripts is easy: Since they will be inserted prior to any code of the command, you can just treat the like global variables in your chosen scripting language.

So for Shellscripts, use $label to access them.

NOTE: use tab to get completion for available labels in the interactive shell

Scripting Languages

ZEUS now supports bash, ruby, python, lua and javascript for writing your commands!

You can also run commandChains that contain commands of different languages!

The default language is bash. If you wish to change a single commands language, simply add the language field directly on the command!

Adding custom languages in the config:

If you wish to add a custom language, have a look at the Language struct in language.go and supply all required fields in the configs Languages section in the config.

You can also override the default languages, for example if you want to use nodejs as js interpreter, instead of the default OSX osascript interpreter.

For macOS javascript is particularly interesting, because it can be used to interact with the system, display GUI elements like progress bars, import ObjC libs and more!

Build Number

Set the buildNUmber field to true to increase the projects buildNumber for every execution of the command!

Internals

ANSI Escape Sequences are from the ansi package.

The interactive shell uses the readline library, although some modifications were made to make the path completion work.

For shell script formatting the syntax package is used.

Here’s a simple overview of the architecture:

alt text

Error Dumps

When a script fails and the dumpScriptOnError config field is set to true, ZEUS will create a dump of the generated script in zeus/dumps.

The dump contains a timestamp, the ZEUS version, the stdErr output of the command and the error message from the process. The file will be named error_dump.[fileExtension] according to the scripting language of the command.

For every language only the last failed script dump will be preserved.

Tests

ZEUS has automated tests for its core functionality.

run the tests with:

zeus » test

Without failed assertions, on macOS the coverage report will be opened in your Browser.

On Linux you will need to open it manually, using the generated html file.

Race Detection Tests

To run the test with race detection enabled:

zeus » test-race

The Go Test functions in zeus_test.go can also be executed in isolation, either on the commandline or via the VSCode golang plugin inside the IDE.

NOTE: The tests are still work in progress. Code coverage is currently at ~ 50%

OS Support

ZEUS was developed on OSX, and thus supports OSX and Linux.

Windows is currently not supported! This might change in the future.

Assets

ZEUS uses asset embedding to provide a path independent executable. For this rice is used.

If you want to work on ZEUS source, you need to install the tool with:

$ go get github.com/GeertJohan/go.rice
$ go get github.com/GeertJohan/go.rice/rice
...

The assets currently contains the shell asciiArt as well the bare scripts for the bootstrap command. You can find all assets in the assets directory.

Vendoring

ZEUS is vendored with go modules. That means it is independent of any API changes in the used libraries and will work seamlessly in the future!

Notes

Background Processes

Spawning jobs inside a script with & is a good idea if you want to interact with them in the context of the current command (for example to use sudo to start your server on a privileged port)

But keep in mind that ZEUS will not wait for these background processes and they will not be tracked in the processMap.

Coming Soon

The listed features will be implemented over the next weeks. After that the 1.0 Release is expected.

Markdown / HTML Report Generation

A generated Markdown build report that can be converted to HTML, which allows adding nice fonts and syntax highlighting for dumped output. I think this is especially interesting for archiving unit test results.
Encrypted Storage

Projects can contain sensitive information like encryption keys or passwords.

Lets search for github commits that include ‘remove password’: search

283,905 results. Oops.

Oh wait, there’s more: click

ZEUS 1.0 will feature encrypted storage inside the project data, that can be accessed and modified using the interactive shell.

Bugs

Multilevel Path tab completion is still broken, the reason for this seems to be an issue in the readline library. I forked readline and currently experiment with a solution.

NOTE: Please notify me about any issues you encounter during testing.

Project Stats

-------------------------------------------------------------------------------
Language                     files          blank        comment           code
-------------------------------------------------------------------------------
Go                              32           1597           1468           5995
Markdown                         6            822              0           2171
YAML                            10             34            108            380
JSON                             1              0              0            175
Sass                             1             21              1            143
Bourne Shell                    31             74            151            128
HTML                             2             10              2             72
JavaScript                       2             17             21             53
make                             1              6              6             10
Python                           2              4              7              8
Ruby                             1              1              0              2
Lua                              1              0              0              1
-------------------------------------------------------------------------------
SUM:                            90           2586           1764           9138
-------------------------------------------------------------------------------

License

ZEUS - An Electrifying Build System
Copyright (c) 2017 Philipp Mieden <dreadl0ck [at] protonmail [dot] ch>

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program.  If not, see <http://www.gnu.org/licenses/>.

Contact

You have ideas, feedback, bugs, security issues, pull requests, questions etc?

Contact me: dreadl0ck [at] protonmail [dot] ch