-
Notifications
You must be signed in to change notification settings - Fork 0
build.py, or how to generate a compressed three.js file
This page describes how to compile your Three.js file.
- 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 commonYou should see output saying that Three.js was compiled in the three.js/build directory. For more build options, type this:
python build.py -hinstall 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/
--
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.
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
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
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.
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
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.