Project Build File Tips Tricks

Sample Build File

We'll use this sample build file to explain some of the things you can do within your projects

{
  "name": "MyApp",
  "version": "0.0.1",
  "directories": {
    "lib": "app"
  },
  "bpm:build": {
    "bpm_libs.js": {
      "files": []
    },
    "bpm_styles.css": {
      "files": ["css"]
    },
    "App/bpm_libs.js": {
      "files": ["lib"],
      "modes": ["debug"],
      "spade:format": "function"
    },
    "App/bpm_libs.js": {
      "files": ["lib"],
      "modes": ["production"],
      "minifier": "uglify-js"
    }
  },
  "dependencies": {
    ...
  }
}

Directories hash

The directories hash manages the mappings for your project's lib, css, and test keys. Their values are relative path to the [PROJECT_ROOT] directory and lib may be an array. In the above example, we are mapping the lib key to the [PROJECT_ROOT]/app/ folder, so instead of the [PROJECT_ROOT]/lib/ folder holding all of your JavaScript files the [PROJECT_ROOT]/app/ folder will. If your JavaScript files for your project are spread across multiple folders you can provide 'lib' with an array ("lib": ["app","lib","some_other_folder"]).

The default values for the keys is the name of the key.

Explaining the "bpm:build" hash

In this hash, the keys are file names with its value another hash. The keys are relative to the top-level output directory assets. The value hash, at minimum, must contain a files array listing all files that will be compiled to create the file. So in the example,

"App/bpm_styles.css": {
  "files": ["css"],
  "modes": ["production"]
}

would create a file in the [PROJECT_ROOT]/assets/App directory called bpm_styles.css that will hold files from the directories mapping defined for the css key (if none is defined the default value and folder of "css" is used).

modes and spade:format explained

You can define three different build modes for each file defined in the bpm:build hash: "debug", "production", and "*" with the latter telling BPM to build the file for both modes (which is the default if not defined). When using bpm preview the default mode is "debug" and when using bpm rebuild the default is "production". However, you can specify the build mode by using the --mode flag.

Spade comes with a BPM plugin called "spade:format" which will allow you to specify if your code is outputted as a string or a function (string is the default). What this allows for is the ability to debug code within your console. Lets take a look at this part of the sample build file:

"App/bpm_libs.js": {
  "files": ["lib"],
  "modes": ["debug"],
  "spade:format": "function"
},

In plain English we are telling BPM that when we are in debug mode compile the files defined by in our directories hash for the lib key into the [PROJECT_ROOT]/App/bpm_libs.js file and my JavaScript will be outputted as unminimized functions instead of strings (unminimized since we do not define a minifier).

And now it should be obvious that the second "App/bem_libs.js" key definition only will compile under production mode.

One more thing...

Separating external and application JS

You can quickly have a large list of dependencies in your build file (removed in this example) and it would be nice if you could separate external library code from your own application code. Trust me your debugger will thank you for this! We accomplish this in the example here:

"bpm_libs.js": {
  "files": []
},

By specifying an empty "files" key array we tell BPM that we want all of our non-application code to be put into the file "[PROJECT_ROOT]/bpm_libs.js". The code within that file will be formatted dependent upon the rules defined in the library's build file.

Help make this doc better!

If you have any other tips you'd like to see here, or see an error, please let me know and I'll be happy to include them in.