build.py, or how to generate a compressed three.js file

d3x0r edited this page Sep 12, 2016 · 136 revisions

This page describes how to compile your Three.js file.

Quickstart (Node.js)

  • Clone (or download and unzip) the project to your file system:
git clone https://github.com/mrdoob/three.js.git
  • Do your building in the ./three.js/utils/build/ subdirectory.
cd ./three.js/utils/build
  • Install build dependencies
npm install
  • Run the build.js script.
#node build.js --include common --include extras
# current readme in utils/build says
npm run build-closure

You should see output saying that Three.js was compiled in the three.js/build directory. For more build options, type this:

#node build.js -h
# new way?  No build.js script...

Quickstart (Mac/Linux):

  • Clone (or download and unzip) the project to your file system:
$ git clone https://github.com/mrdoob/three.js.git
  • Do your building in the ./three.js/utils/build/ subdirectory.
$ cd ./three.js/utils/build
  • Run the build.py script.
$ python build.py --include common --include extras

You should see output saying that Three.js was compiled in the three.js/build directory. For more build options, type this:

python build.py -h

This page is currently invalid and needs to be rewritten.

Except "Recommended for Windows"


See node.js at top for node build on Windows

Recommended for Windows (August 19 2012)

Download three.js SDK select master or dev branch,decompress to where you would like.

install three.js https://github.com/mrdoob/three.js/ master/dev Click ZIP button.

install python http://www.python.org/download/

install java http://www.java.com/en/download/manual.jsp

install notepad++ http://notepad-plus-plus.org/

1. Run notepad++

2. If there is not a new file ready for you,select in menu, "File" then select "New".

3. At the top(line 1), type in "location" of build.py file, plus the command "build.py", then select the "optional arguments" (mentioned below) that you would like to use for this build.

location of build.py file\build.py optional arguments

usage: build.py [-h] [--includes] [--common] [--extras] [--canvas] [--webgl]
                [--svg] [--dom] [--debug] [--minified] [--all]

Build and compress Three.js

optional arguments:
  -h, --help  show this help message and exit
  --includes  Build includes.js
  --common    Build Three.js
  --extras    Build ThreeExtras.js
  --canvas    Build ThreeCanvas.js
  --webgl     Build ThreeWebGL.js
  --svg       Build ThreeSVG.js
  --dom       Build ThreeDOM.js
  --debug     Generate debug versions
  --minified  Generate minified versions
  --all       Build all Three.js versions

example:

D:\PROGRAMMING\threejs\mrdoob-three.js-13c6951\utils\build.py --common

4. In menu select "File" then "Save As".

5. At bottom of Save As pop up window, change Save as type to "Batch file".

6. Browse to three.js utils folder, name batch file according to option arguments.(be sure to keep .bat at end of filename)

example:

A) build_threejs_common.bat (just helps to remind you what was selected in the batch file)

B) build_threejs_common_debug.bat

7. Click on Save.

8. All you have to do now is goto the three.js utils folder, and double click on the file you just created.

Anything created will go into the build folder, so you may want to delete files in that folder that you are going to recreate.



Why compression?

The source code of Three.js is deliberately easy to read for a human being. This means that it's split into several files and classes. While that's great for developing and hacking on Three.js, it's not that great when deploying code to the production server.

In production, you want to

use the least amount of files possible (to minimise the number of connections to your server)

transmit as few bytes as possible (to save on bandwidth and on wait-time on both sides)

So how do we put all files into just one and make it smaller than the sum of the parts? Well, the answer is the awesome combination of our build script plus Javascript compressors!

h2. build.py

The build script is located in @utils/build.py@. As you might already have guessed, it's written in Python, so you'll need a working Python 2.6 (or higher) installation in order to execute it.

To create your first compressed Three.js file, simply chdir to the utils directory, and launch the script:

bc. python build.py --common --minified

This will create a compressed version of the current Three.js source code, and place it in the @build@ folder (i.e. a level above @utils@)

If you just want to create a version of Three.js in one file, without compressing anything, just ignore the @--minified@ switch:

bc. python build.py --common

This is way faster to produce, but the resulting file is also understandably larger than the compressed version!

h2. Customising your build

Another advantage of using this script is that you can prepare a packed version with exactly the parts of Three.js that you use. So let's say you only use the Canvas renderer in your project--then you don't need to include the other renderers. Well, there are options for that in the build system:

bc. python build.py --canvas --minified

This will generate the ThreeCanvas.js file in @build/custom@

Or if you just want to use WebGL:

bc. python build.py --webgl --minified

will generate ThreeWebGL.js in @build/custom@

For a complete list of the available options, simply run @build.py@ without arguments:

usage: build.py [-h] [--includes] [--common] [--extras] [--canvas] [--webgl]
                [--svg] [--dom] [--debug] [--minified] [--all]

Build and compress Three.js

optional arguments:
  -h, --help  show this help message and exit
  --includes  Build includes.js
  --common    Build Three.js
  --extras    Build ThreeExtras.js
  --canvas    Build ThreeCanvas.js
  --webgl     Build ThreeWebGL.js
  --svg       Build ThreeSVG.js
  --dom       Build ThreeDOM.js
  --debug     Generate debug versions
  --minified  Generate minified versions
  --all       Build all Three.js versions

h2. Do you really need to use build.py?

Generally speaking, most people don't need it, since we already create the builds with compressed files and upload them to the repository pretty much right after committing changes to the code (the builds are in the @build@ folder).

But if you're working in the very THREE.js source code and want to generate a compressed version for your own use, this is the tool you'll need. Also, if you add a new class to the project, it will need to be added to the build.py script so that it's included when on the builds. Read on for more information on how is it done.

h2. How does build.py work?

The script has a list of files that are to be included in each 'version' of the build. For example, when you specify the @--canvas@ option, it will read all the files defined in the @CANVAS_FILES@ list, append them all together in just one big file, and then send the result through the compressor, which in turn, will create a significantly smaller version of the file, while still being equivalent code-wise. It does so by removing comments, extra spaces and tabs, and by using other advanced techniques such as renaming vars that can be safely renamed without breaking anything else, etc.

If you wanted to include a file only when building the Canvas version, you'll add the relative path to the file to the @CANVAS_FILE@ variable.

Three.js currently uses Google's "Closure":http://code.google.com/closure/compiler/ compiler for producing its packed version. The compiler is included too in the download of Three.js, following the batteries included house style.

In the past we used Yahoo's "YUI":http://developer.yahoo.com/yui/compressor/ compressor, but changed to Closure because it generated smaller files.