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.
Install itBldz
npm install -g itbldz --save-devand create your config with
init-itbldzif something is missing edit the config files that are created (config.json, build.json, deploy.json).
build it
build-itdeploy it
deploy-itor ship it (build & deploy)
ship-itNote: 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.jsAll your arguments will be passed to grunt. To trigger tasks, simply add them.
Examples:
Get all tasks with description
build-it --helpVerbose output:
build-it --verboseGiven this config:
{
"compile": {
"typescript : { /* compile your sources */ }
},
"build": {
"unit" : { /* unit tests */ },
"acceptance" : { /* acceptance tests */ }
}
}
Compile your source:
build-it compile/typescriptCompile and trigger your unit tests:
build-it compile/typescript test/unitBuild it using another config "uglify.json"
build-it --with=uglifyDeploy using another config "heroku.json"
deploy-it --to=herokuChange the configuration to point to the production.json file
deploy-it --to=heroku --as=productionShip it with "uglify.json" and "heroku.json"
ship-it --with=uglify --to=herokuTo include this project, all you have to do is to configure the build.json and the config.json.
The build.json is the task-template. It orchestrates the build, and is separated into build-steps, task-groups and tasks.
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 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" : {}
}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. The reference a specific version, add "@1.0.0" to the package name (replace 1.0.0 with the version you want...)
- "dependencies" (optional): The dependencies the Task Runner may need
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.
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.
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.
However, now that you know that you shouldn't do it, here's the way on how to do it. In the template syntax you can execute functions as well:
{
"example-timestamp": "<%= Date.now() %>'"
}This can be extended - you can create simple Modules that look like the following (TypeScript):
export class HelloWorld {
public greet(name) {
return "Hello " + name;
}
}Then in your configuration (i.e. build.json) you can include the module like this:
{
"test-module": {
"hello world" : {
"task": "exec",
"package": "grunt-exec",
"echo-module" : {
"cmd" : "echo '<%= modules.HelloWorld.greet('me') %>'"
}
}
}
}To control the modules that should be loaded, a module.js file is added that is automatically included if available or can be included with --modules=path/to/modules.js which looks like the following:
[
"modules/HelloWorld.js"
]The name of the module is the name of the class in the file that should be loaded for this keyword, so that when you have multiple classes like so:
export class HelloWorld {
public greet(name) {
return "Hello " + name;
}
}
export class GoodbyeWorld {
public greet(name) {
return "Goodbye " + name;
}
}you will have both available in the configuration.
Git clone this repository, run a
npm install -g itbldz
npm install
and then
build-it
to have it set up
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