node package manager
Don’t reinvent the wheel. Reuse code within your team. Create a free org »

cu-build-tools

cu-build-tools

Tools to build Camelot Unchained UI libraries and modules

Introduction

This library provides multiple sets of gulp tasks which aid in building UI modules and libraries

There are currently two different sets of tasks:

All configuration will be stored in files named cu-build.config.js which will determine how that module/library will be built.


Installation

You will need Git on your path. One way to do this is to install Github For Windows and use the "Git Shell" shortcut in your start menu.

npm install gulp -g
npm install cu-build-tools --save-dev

if you need to develop with your own fork or the mod squad fork, just update the url to point to the right repository


Setup

To utilise the build tools, you will need to create two files in the given directory:

cu-build.config.js Minimal Configuration

/**
 * This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at http://mozilla.org/MPL/2.0/.
 */
 
var name = 'name-here';
 
module.exports = {
  type: 'module', // (module|library|multi) 
  path: __dirname,
  name: name,
};
 

gulpfile.js Minimal Configuration

/**
 * This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at http://mozilla.org/MPL/2.0/.
 */
 
'use strict';
 
var gulp = require('gulp');
var buildConfig = require('./cu-build.config.js');
var buildTools = require('cu-build-tools');
 
// load build tool tasks and obtain processed build configuration 
var config = buildTools.auto(gulp, buildConfig);
 
// custom gulp tasks can be defined here 
 

Module/Library - Builder

If cu-build.config.js has a type set to library or module the following tasks will be created in gulp:

default

This will do the following:

  • install
  • build or publish
  • watch
watch

This will watch the src directory and build or publish when files change.

server

This will create a connect server, you can then access this server via at http://localhost:9000/

build

This will build everything (library and bundle) to the normal build directory (default dist)

publish

This will build everything (bundle) to the configured publish directory (default publish).

install

This will install/generate npm dependencies, tsd and VS project.

Command Line Arguments

--user-ui

This will make the publish command send files to the User UI directory at %LocalAppData%/CSE/CamelotUnchained/4/INTERFACE. You can provide a channel number which will change the destination channel. e.g. --user-ui 10 for Wyrmling.

--port ****

You can override the port used for the connect server e.g. gulp server --port 9001

--server

You can specify the server should be run as part of the default task

--no-server

You can specify the server should not be run as part of the default task

--publish

You can specify that the publish should be the default task instead of build

--no-publish

You can specify that build should be the default task instead of publish

--no-install

You can specify that the default task should not install anything.

--no-sourcemaps

You can specify that sourcemaps should not be created

--sourcemaps-inline

You can specify that sourcemaps should be inlined

--ui-nested

You can specify that ui files should not be nested


Multi Builder

If cu-build.config.js has a type set to multi the following tasks will be created in gulp:

install

This will run install on all subdirectories containing cu-build.config.js (including node_modules)

publish

This will publish all subdirectories to the configured publish directory

clean

This will clean the publish directory

gulp %DIRECTORY%

This will run the publish task on the specified subdirectory.

As an example: gulp character will run the publish task on the character directory.

gulp %DIRECTORY%::%TASK%

This is a proxy to the normal module and component build system. It allows you to run tasks on a target directory.

As an example: gulp character::publish will run the publish task on the character directory.


Build Configuration

Example Configuration

Example Module/Library Builder Configuration
 
var name = 'name-here';
 
module.exports = {
  type: 'module', // or library 
  path: __dirname,
  name: name,
};
Example Multi Builder Configuration
module.exports = {
  type: 'multi',
  path: __dirname,
  name: 'multi',
  publish: {
    dest: 'publish',
  },
};
Injecting Scripts Into Development Server

You might want to inject a mock api to help with development.

You will want a script to inject e.g. https://github.com/Mehuge/cu-fake-api

You could install the fake api above with the following command:

npm install git+https://github.com/Mehuge/cu-fake-api --save

You would then want to add the path to the script to your cu-build.config.js:

module.exports = {
  // ... 
  server: {
    inject: {
      scripts_before: [require.resolve('cu-fake-api')],
      scripts_after: []
    }
  }
  // ... 
}

Bundle Configuration Structure

set bundle to false to disable bundle building (Not Recommended)

bundle: {
  dest: 'dist', // the destination folder for bundle (will be overridden by publish.dest+publish.target during a publish 
  base: '', // the base for bundling (will determine where the output is placed) 
  main: true, // the tmp in path (AUTO generated when set to true) 
  browserify: true, // enable/disable browserify bundle 
  stylus: false, // if stylus should be copied 
  stylus_base: 'style', // the base directory within src for stylus 
  stylus_dest: '', // the target directory for stylus 
  sass: false, // if sass should be copied 
  sass_base: 'sass', // the base directory within src for sass 
  sass_dest: 'css', // the target directory for sass 
  copy: true, // array of file globs (or false if no copy) setting to true will auto populate the copy globs 
  copy_base: '', // the base (within src) directory for files to copy. 
  css_rename_main: true, // will rename the main css file to name of module/library 
}

Library Configuration Structure

set lib to false to disable library building

lib: {
  dest: 'lib', // the destination folder for lib 
  base: true, // the base (within src) directory within src 
  stylus: false, // if stylus should be copied 
  stylus_base: 'style', // the base directory within src for stylus 
  stylus_dest: '', // the target directory for stylus 
  sass: false, // if sass should be copied 
  sass_base: 'sass', // the base directory within src for sass 
  sass_dest: '', // the target directory for copied source sass 
  css_dest: '', // the target directory for compiled css 
  copy: false, // array of file globs (or false if no copy) 
  copy_base: '', // the base (within src) directory within src for copy 
  css_rename_main: false, // if main css files should be renamed to library name 
}

Main Configuration Structure

{
  type: '', // library, module, multi 
  path: '', // the project root path, should be set to __dirname 
  src: 'src', // the src directory 
  tmp: 'tmp', // the tmp directory 
  name: null, // the project name 
  main_name: 'main', // the main file name 
  proj_name: null, // the VS project name 
  lib: null, // @see above 
  bundle: null, // @see above 
  server: {
    root: null, // the server root path 
    port: 9000, // the server port 
    inject: {
      scripts_before: [], // array of paths to scripts to inject before 
      scripts_after: [], // array of paths to scripts to inject after 
    },
  },
  build: {
    install_npm: true, // if npm should be installed during install task 
    install_tsd: true, // if tsd should be installed during install task 
    publish: false, // if the default task is publish 
    server: false, // if the server should be started by default 
    sourcemaps: true, // if sourcemaps should be created for bundles 
    sourcemaps_inline: false, // if sourcemaps should be inline for bundles 
    is_multi: false, // if module/library is running under multi builder 
    ui_nested: true, // if ui files should be nested or not 
  },
  publish: {
    dest: 'publish', // the publish directory 
    target: true, // the publish target (AUTO generated when set to true) 
  },
  license: '...', // the license string attached to top of bundled file 
  glob: { // the glob patterns, should not need to change these 
    ts: ['**/*+(.ts|.tsx)'],
    js: ['**/*+(.js|.jsx)'],
    stylus: ['**/*.styl'],
    sass: ['**/*.scss'],
    bundle: ['**/*.bundle.js'],
  },
  compile: {
    ts: true, // enable typescript compile 
    js: false, // enable javascript compile 
    sass: true, // enable sass compile 
    stylus: false, // enable stylus compile 
  },
}

Task Hooks

There are a number of gulp task hooks that can be overridden to allow custom tasks to take place:

  • build:before
  • build:after
  • publish:before
  • publish:after
  • install:before
  • install:after
  • library:before
  • library:after
  • bundle:before
  • bundle:after
  • compile:before
  • compile:after

You can override any of these tasks, to add additional processing.