Summary

ybuild is a community contributed build system for creating YUI3.x components.

It builds javascript and css components to fit the YUI3 Loader, which is part of the YUI Framework (http://yuilibrary.com/).

It depends on mosen/buildy to execute all of the build tasks.

Documentation under heavy construction

Usage

ybuild gallery-module-name to build a gallery module OR ybuild * to build all modules in the current directory.

See ybuild -h for detailed command line options.

Setup

In order to build your component for yui3, your files should be organised as following:

Directory structure

The directory structure is the same as YUI Builder (https://github.com/yui/builder) with the exception of the build.xml and build.properties files. ybuild uses a build.json file instead to describe all the same parameters.

/moduleroot
    /src
        /yui-module-name
            build.json
            /js
                module.js
            /assets
                yui-module-name-core.css
                /skins
                    /sam
                        yui-module-name-skin.css
    /build

Assets can be omitted if your component won't be skinnable. (i.e there's no stylesheets OR images).

build.json format

The build.json file format describes a YUI3.x component in JSON format. It replaces the build.xml and build.properties files used with YUI Builder.

Example

All parts of the json spec are optional except where noted as required. The following is an example where most of the possible options are set...

{
    "name"    : "yui-module-name",
    "description" : "An example module",
    "type"    : "js",
    "version" : "1.0.0",
    "skip"    : ["template", "jslint"],
    "sourceDir"   : "js",
    "sourceFiles" : [
        "module.js"
    ],
    "buildDir"  : "../../build/yui-module-name",
    "assetsDir" : "assets",
    "tasks" : {
        "jslint" : {
            "jslint_option" : "jslint_value"
        },
        "template" : {
            "template_option" : "template_value"
        }
    },
    "details" : {
        // These options are all copied from the current Loader's addModule() implementation.
        // Some may not be yet supported by ybuild.
        "requires"   : ["base"],
        "optional"   : [],
        "supersedes" : [],
        "after"      : [],
        "after_map"  : {},
        "rollup"     : undefined,
        "skinnable"  : true,
        "submodules" : {},
        "group"      : "",
        "lang"       : ["en-US"],
        "condition"  : {
            "trigger" : "testmodule",
            "test" : function(),
            "when" : "before|after|instead"
        },
        "use"        : null // Not documented, gets munged into supersedes anyway.
    }
}

build.json properties reference

name

required

Name of the YUI module. Will be used in YUI().add() so this is what the loader will refer to when you include the name in YUI().use('name').
type

required

One of js or css. The type of component we are building. css implies that sourceFiles will only contain stylesheets. You should also set sourceDir to css.
version

default : @VERSION@

Normally filled with the string @VERSION@, might be used in building yui itself? Needs clarification
skip

Array of tasks to skip, identified by their name in buildy.
sourceDir

Relative directory to the source files. If omitted, defaults to a subdirectory named after the type option.
sourceFiles

required

Array of filenames to include when building the module (with extensions).
buildDir

default : ../../build/modulename

Directory where the built files will reside (relative to the module directory).
assetsDir

default : ./assets

Relative directory to the module assets.
tasks

Hash containing options passed to specific tasks. Eg. lint options, minify options.
details

Details which the loader will use to determine the loading order and requirements. See the example for possible options, also see yui3 loader docs (specifically addModule()).

ybuild vs. yui builder tool

Why switch build tools?

No java dependencies, no ant, no jars.
All node.js! several other yui tools already run on node.
Just plain faster. Eg:

Building one of my own modules - gallery-datatable-ml

ant: 3.258s
ybuild: 0.200s

TODO

Separate logging from every object.
Language pack support.
YUI Builder Tests target.
Handle error where one part of the skin exists, and the other doesn't (core without skin etc).

Options not yet handled by ybuild

in yui3

srcdir different than implied source directory
component.prependfiles / component.appendfiles mostly for license additions?
component.logger.regex set log removal regex per example
tests.requires / tests.* in async-queue tests target in general, builds a test module
global.build.component or global.* in widget-modality top level directories for build/assets
component.rollup and rollup related functionality. check loader still uses rollups?
yui.core / yui.rls / loader.tnt / loader.yui2 custom build tasks inside yui seed.
component._lang in datatype used to populate each datatype module with a list of languages.

in yui-gallery

yui.variable A in AlloyUI stuff
component.assets.flatten take nested assets and flatten into one target directory
component.details.auipath and auitype in AlloyUI looks like the details are simply amended to YUI().add details line.
component.assets.base in aui-skin-classic alter the base assets directory, normally ./assets
component.assets.files = images//*,css//* at aui-skin-classic files to match in assets, normally */
component.optionals in gallery-slider-window (optional?) can't find documentation with this property.

justinrainbow/ybuild