Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 125 lines (68 sloc) 7.014 kb
00e83bb @timwindsor First commit of the Ant Build Script for WebWorks applications
timwindsor authored
1 WebWorks Build Script
2 =====================
3
4 This is an Ant build script for building BlackBerry WebWorks applications for BlackBerry Java smartphones, BlackBerry PlayBook tablets, and BlackBerry 10 devices. With some basic set up, the script can sign and create both test and production builds, deploy to the file system for Ripple, and support optimization with JSLint, JSHint, CSSLint, as well as JS and CSS concatenation and minification.
5
dbeddc9 @timwindsor Added link to setup video on Youtube
timwindsor authored
6 Watch a [video](http://www.youtube.com/watch?v=89bOz3w_z5E) showing how to setup the script.
7
00e83bb @timwindsor First commit of the Ant Build Script for WebWorks applications
timwindsor authored
8 ## Script Setup
9
10 The project is designed to work in two parts:
11
12 1. a build script with project specific properties that goes in the project directory.
13
14 2. a set of common build tasks and associated tools (including ant) that go in a central location.
15
16 ## Project specific build.xml
17
18 The build.xml file is meant to be placed in the project's main directory and modified with settings specific to the project. These settings should only change based on the project's needs.
19
20 When setting up a project to use this build script, add the build.xml file to the project and change these properties in the script:
21
22 * Project name: change this from the default to the name you wish to use for the project build files (zip, bar, jad/cod files and ripple directory).
23
24 * jsconcat, cssconcat: update these if you want a specific name for your combined and minified files.
25
26 * lintfail: defaults to false, but can be set to true if you want to fail the build on errors with JSLint, JSHint, and CSSLint.
27
28 * build target: Set to a list of targets you want to build
29
30 * For _Windows_ you are then set, but the default path for including the buildTasks.xml file will not work on _MacOS_ or _Linux_ which contain Ant already and put it in a different directory. Change this path to wherever you placed buildTasks.xml.
31
32 ## Common Build Tasks and Tools
33
34 In the /tools directory of the repository is a buildTasks.xml file plus some tools and script files. This folder is meant to be placed in one location and be accessed by the project build scripts. These are common settings and tasks that should change when your build environment changes, not individual projects.
35
36 1. To use these tools, create a directory with all the contents somewhere on your system, like __c:\BuildTools__.
37
38 2. If you've got Ant installed already, then that simplifies things. If not, create an __%ANT_HOME%__ environment variable and point it at the __apache-ant-1.8.2__ directory. Then add __%ANT_HOME%/bin__ to your system __PATH__ variable.
39
40 3. Open __buildTasks.xml__ and edit the following properties:
41
42 > sign.pw: Code signing password.
43
44 > file.excludes: add any additional files that shouldn't be zipped, like project files from your editor.
45
46 > bbwp.xxx.dir: update the locations of the the SDKs that should be used.
47
48 > ripple.dir: update the location of your local webserver (or Ripple localhost) so that projects can be pushed out to the webserver.
49
50 > tools.dir: update if you put the tools in a different location than the directory above _%ANT_HOME%_.
51
ec00695 @timwindsor Now supports a params file property and conditionally uses it.
timwindsor authored
52 > paramsfile: Set this value to a params.json file if you need to send parameters to downstream tools in the build process, such as the blackberry-signer (ie: proxy setup), or blackberry-nativepackager tools. Leave the value empty to not use a params file.
53
00e83bb @timwindsor First commit of the Ant Build Script for WebWorks applications
timwindsor authored
54 > review the other properties, but they shouldn't need changing.
55
56 ## Build Targets
57
58 __build.test__ (build in all SDKs+Ripple with WebInspector, source output, and debug token for Tablet and BB10)
59
60 __build.prod__ (build in all SDKs+Ripple with signing and no debugging, and a build id number for Tablet and BB10)
61
62 __build.beta__ (build in all SDKs+Ripple with signing _and_ debugging, and a build id number for Tablet and BB10)
63
64 __build.ripple__ (deploy to your file system for serving up in Ripple)
65
66 Specific builds follow the pattern:
96e85bf @timwindsor Updated documentation on target name changes
timwindsor authored
67 __build.[bbos, tablet, bb10].[test, prod, beta]__
00e83bb @timwindsor First commit of the Ant Build Script for WebWorks applications
timwindsor authored
68
96e85bf @timwindsor Updated documentation on target name changes
timwindsor authored
69 - use __bbos__ for BlackBerry 5 through 7.x smartphones
70 - __tablet__ for PlayBook 1.x through 2.x
71 - __bb10__ for BlackBerry 10
00e83bb @timwindsor First commit of the Ant Build Script for WebWorks applications
timwindsor authored
72 - use __test__ for WebInspector, source output, and debug tokens. Will still sign the app for Java Smartphones.
73 - use __prod__ for regular signing with a build id and no debugging
74 - use __beta__ for regular signing with a build id and WebInspector turned on.
75
76 Lint/Hint and Minify targets can be included before the build:
77
78 __build.optimize__ runs both lint and minify tasks
79
80 __build.lint__ runs jslint, jshint and csslint
81
82 __build.minify__ concatenates and minifies the JS and CSS files
83
84 ## Deploy Targets
85
86 Besides building and linting projects, you can also use this script to deploy to your device, or simulator.
87
88 Deployment commands follow the pattern:
89
96e85bf @timwindsor Updated documentation on target name changes
timwindsor authored
90 __build.deploy.[bb10.[device, sim], tablet, bbos].[test, prod, beta]__
91 - __bb10__, __tablet__, __bbos__ for each platform as defined above
92 - only for __bb10__ builds, use __device__ for real devices and __sim__ for VMWare based simulators
e23e4a9 @timwindsor Tweak to the readme instructions
timwindsor authored
93 - __test__, __prod__, __beta__ to load the matching build created above
00e83bb @timwindsor First commit of the Ant Build Script for WebWorks applications
timwindsor authored
94
95 ## Build a Project
96
97 Try it out by copying build.xml into a project, editing the script as above and then running __ant build__ in the directory.
98
99 This script should work well with IDE's like Eclipse and Sublime Text and others too.
100
101 ## Dependencies
102
103 The script is dependent on several tools:
104
105 - [Apache Ant 1.8.2](http://ant.apache.org/) released under the [Apache 2.0 License](http://www.apache.org/licenses/LICENSE-2.0.html)
106
107 - [Rhino JS](http://www.mozilla.org/rhino/) released under the [MPL/GPL License](https://developer.mozilla.org/en/Rhino_License)
108
109 - [YUICompressor](http://developer.yahoo.com/yui/compressor/) released under the [BSD License](http://yuilibrary.com/license/)
110
111 - JSLint and JSHint are released under a modified [MIT License](http://www.opensource.org/licenses/MIT) with the addition: "The Software shall be used for Good, not Evil."
112
113 - CSSLint is released under the [MIT License](http://www.opensource.org/licenses/MIT)
114
115 ## Credits
116
117 This project was inspired by and based on the work of [Addy Osmani](http://addyosmani.com/blog/client-side-build-process/) and the [HTML5 Boilerplate Ant Script](https://github.com/h5bp/ant-build-script) project. It's really just a tweaking of their work with the addition of BlackBerry WebWorks targets.
118
119 ## License
120
121 The build script aside from the 3rd party tools is covered under the [Apache 2.0 License](http://www.apache.org/licenses/LICENSE-2.0.html)
122
123 ## Disclaimer
124
125 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Something went wrong with that request. Please try again.