Skip to content

Build Process Overview

Jump to bottom
Sammy Jelin edited this page Dec 30, 2013 · 14 revisions

Table of Contents:

For more exact details of how the builder works, please read the README.md.

Goals

The goals of the builder are as follows:

  • Build the web.xml file for the server
  • Run some basic templating over all files in the webprojects folder.
  • Compile .scss files into .css files
  • Compress js files, unless the --debug flag is specified
  • Compile run-time templates
  • Merge js and css files to reduce the number of requests to the server
  • Push files for all websites to the server
  • Push files for the webapp to any smartphone apps

The web.xml file

Java web applications use a web.xml file to organize things like what URLs correspond to what pages. Google does a thorough job of explaining them here. Our builder generates a web.xml file based off of the patterns described in our servlet-list.csv file.

The webprojects folder

The webprojects folder contains all the web-related code (e.g. .js and .html files). It is also what undergoes the most work during compilation.

Some subfolders of the webprojects folder have special meanings. Generally, any folder beginning with an _ has some sort of special meaning. These special folders come in two varieties: type folders and platform folders.

Type folders specify what type of content they contain:

  • _img These folders contain images
  • _js These folders contain JavaScript files. Files in this folder which are not .js files will not be pushed to the output code
  • _style These folders contain .css, .scss, and .sass files. Any files with some other extension will not be push to the output code
  • _templates These folders contain .tmplt and tspec files. Any files with some other extension will not be push to the output code
  • _raw These folders contain content which should be pushed to the output code without any sort of modification.
  • _ignore These folders contain content which should not be pushed to the output code
  • _skip The same as _ignore
  • _css This is a temporary folder used to hold the contents of the _style folder after SASS compilation is complete

Platform folders contain files that should only be pushed to the output code on certain platforms:

  • _debug Contents only used if the debug flag is set
  • _web Contents only used when pushing to server
  • _iOS Contents only used when pushing to iOS app

Additionally, there is one special file:

  • _order When merging JavaScript or CSS, this file (if present) specifies what order those files should be merged in. If the file does not contain a complete list of all files in the folder, the remaining files will be merged in after the files specified by the file.

All folders which are direct children of the webprojects folder but do not begin with an _ are assumed to represent distinct projects

Build-Time Templating

How our macros actually work is explained elsewhere. Here, we describe where they are defined and which files they are run on.

Currently, macros are defined in the macros file, though they might be allowed to be defined in more places in the future. Those macros are then run in all the files in the webprojects folder, unless those files are inside a _raw or _img folder.

SASS Compilation

SASS is a tool for simplifying writing CSS. All the .scss or .sass files in a _style folder undergo SASS compilation

SASS library files should be placed in an _ignore folder so that they will not be pushed to production. The main SASS library file is at webprojects/_ignore/main.scss

JS Compression

We use uglifyjs to compress our javascript. However, we only do this compression if we are not in debug mode.

We frequently use lines like:

    if({{DEBUG}}) {
        ...debug code...
    }

UglifyJS will automatically remove those lines if {{DEBUG}} is false. However, it will spit out a warning message. For this reason, we ignore all warning messages about "side-effect-free statements" or a condition always being true/false.

Incidentally, this method of writing debug-only code is drastically preferred over

    IF_DEBUG
        ...debug code...
    END_IF

because it fits better into the flow of JavaScript

Run-Time Template Compilation

How our run-time templates actually work is explained elsewhere. Here, we describe where they are defined/compiled.

The builder lookes for template files within the server/templates folder and any _templates folder within the webprojects directory. Within such folders, any .tmplt file will be expected to have a corresponding .tspec file, and vise versa. The templates within the server/templates folder are compiled into java and made accessible to the server. The templates in a _templates folder within the webprojects directory are compiled into both java and javascript, and made accessible both to the server and to the javascript files in the same project.

Merging & Pushing

Suppose we have a type folder with the name _type at the path webprojects/f1/f2/.../fn/_type, and the code is currently being outputted to a folder at the path root. Then one of the following happens:

  • Case 1: type is js or css
    The contents of webprojects/f1/f2/.../fn/_type (and all subfolders) are merged and placed into the file root/f1/f2/.../fn.type
  • Case 2: type is style, skip, or ignore
    These files are not copied to the output code
  • Case 3: type is raw
    The contents of webprojects/f1/f2/.../fn/_type are copied to root/f1/f2/.../fn/
  • Case 4: Else
    The contents of webprojects/f1/f2/.../fn/_type are copied to root/f1/f2/.../fn/type/

Projects listed in app-web-projects.csv are pushed to the www folder of all native apps, as well as the war folder of the server. All other projects get pushed to the war folder only.

Clone this wiki locally