itBldz Build-Tools

The only build-tool you'll ever need

The goal is to provide an easy to setup framework which allow every development team a "closed for modification, open for extension"-plattform for their own needs.

Usage

Setup

Install itBldz

npm install -g itbldz --save-dev

and create your config with

init-itbldz

if something is missing edit the config files that are created (config.json, build.json, deploy.json).

build it

build-it

deploy it

deploy-it

or ship it (build & deploy)

ship-it

Note: If you don't install it globally, you can use

[node] ./node_modules/itbldz/bin/build-it.js|deploy-it.js|ship-it.js|init-itbldz.js

Options

All your arguments will be passed to grunt. To trigger tasks, simply add them.

Examples:

Get all tasks with description

build-it --help

Verbose output:

build-it --verbose

Given this config:

{
    "compile": { 
        "typescript : { /* compile your sources */ }
    },
    "build": {
        "unit" : { /* unit tests */ },
        "acceptance" : { /* acceptance tests */ }
    }
}

Compile your source:

build-it compile/typescript

Compile and trigger your unit tests:

build-it compile/typescript test/unit

Build it using another config "uglify.json"

build-it --with=uglify

Deploy using another config "heroku.json"

deploy-it --to=heroku

Ship it with "uglify.json" and "heroku.json"

ship-it --with=uglify --to=heroku

Configure for your use case

To include this project, all you have to do is to configure the build.json and the config.json.

build.json

The build.json is the task-template. It orchestrates the build, and is separated into build-steps, task-groups and tasks.

build-steps

The build-step is the first layer. It defines the main tasks of the build. You should use a natural language that fits your build-pipeline best.

An example:

    {
        "prepare build environment" : {},
        "compile" : {},
        "tests" : {}
    }

Task Groups

Task-groups are containers for other task-groups and tasks. They do not run by itself, but rather orchestrate the task-groups and tasks they contain. They are used to organize build-steps, and should use a natural language that describe their use best.

An example:

    {
        "compile" : {
            "code" : { 
                "java using maven" : {},
                "typescript to javascript" : {}
            },
            "assets" : {
                "less to css" : {}
            }
        },
        "tests" : {}
    }

Tasks Runners

Task Runners are the heart and soul, and are executors for grunt-tasks. They can have arbitrary names and should describe best what they do, not what grunt task they are using. Which grunt-task they run is specified by the properties task and package. The task field specifies the name of the grunt-task that should be run, while the package field specifies which npm package is required to run the task. Note: itBldz will try to install all required packages automatically. However, at the current moment for global installation of itblz that's only true for references you do not require('') in your application. These you will have to add to your package.json.

The build.json is to be the same on every environment you run the build.

An example:

{
    "tests": {
        "unit": {
            "task": "mochaTest",
            "package": "grunt-mocha-test",
            "dependencies": [ "chai", "sinon" ],
            "test": {
                "src": [ "<%= config.files.unit %>" ],
                "quiet": "true"
            }
        }
    }
}

This runs mocha unit tests

• "task": the task name that should be executed
• "package": the npm package that contains the task
• "dependencies" (optional): The dependencies the Task Runner may need

config.json

Where to do it

The config.json is describing the environment the build is running in. It is used to control the directories, file-patterns, or environmental specifics. You can use all variables in the config.json in your build.json by typing

<%= config.YOURKEY %>

An example would be:

    {
      "directories" : {
        "sources" : "sources",
        "output" : "target"
      },
      "filesets" : {
        "php" : ["**/*.php", "!**/framework/**"]
      }
    }

Make sure the configuration natively reflects the language on how you are talking about your environment.

For different environments you might have different configurations. Split them and reference the correct config when starting the build.

Environment

In your configuration and build you can access the environment variables of your host system as well.

Add the Statement

<%= env.ENV_VARIABLE %>

and it will automatically be replaced.

I need a function in my configuration!

Sorry, but that sounds like an oxymoron. itbldz is to configure build scenarios in an easy way, and adding logic to your configuration does not seem to help reducing complexity.

If you want a grunt task to do more then what is configured, then create an npm package, test it and use this.

If you need a task-runner where you can add functions to your configuration, then directly use grunt.

Contributing

Getting started

Git clone this repository, run a

npm install -g itbldz
npm install

and then

build-it

to have it set up

Guidelines

You are free to extend the project as you wish. Every new code has to include unit tests and result in a green build when building the build-tools executing

build-it