Skip to content
Newer
Older
100644 270 lines (177 sloc) 7.7 KB
cc4b53f @davglass Readme Updates
davglass authored Apr 3, 2012
1 Welcome to YUI Builder
2 ======================
b39dca7 @reid Welcome to YUI Builder.
reid authored Jul 1, 2010
3
cc4b53f @davglass Readme Updates
davglass authored Apr 3, 2012
4 Introduction
3b587c6 @sdesai README update. Added build file templates to use as starting point fo…
sdesai authored Feb 25, 2009
5 ------------
6
7 YUI uses ANT to create component build files from individual source files.
8
9 Each component has its own ANT build file residing in the component's
1f29cb2 @sdesai English as a second (or third) language cleanup
sdesai authored Mar 2, 2009
10 source folder with an associated properties file used to define build
3b587c6 @sdesai README update. Added build file templates to use as starting point fo…
sdesai authored Feb 26, 2009
11 parameters specific to the component e.g:
12
13 yui2/src/autocomplete/build.xml
14 yui2/src/autocomplete/build.properties
15
16 The component build will automate the conversion from component source
17 to <component>.js, <component>-min.js, <component>-debug.js by:
18
d3d5d3e @sdesai Cleaned up lists
sdesai authored Mar 2, 2009
19 a) Concatenating individual source files
20 b) Stripping logger statements
21 c) Compressing files, using yuicompressor
22 d) Running jslint on all 3 built files
23 e) Adding boiler plate module/version registration code
24 f) Building skin files from <component>-core.css, <component>-skin.css
25 g) Deploying built JS, CSS and assets to <project>/build
3b587c6 @sdesai README update. Added build file templates to use as starting point fo…
sdesai authored Feb 26, 2009
26
27 The same component build system is also used for CSS components such as
28 reset, base, fonts and grids.
29
30 The component build does not currently:
31
d3d5d3e @sdesai Cleaned up lists
sdesai authored Mar 2, 2009
32 a) Check in any code
3b587c6 @sdesai README update. Added build file templates to use as starting point fo…
sdesai authored Feb 26, 2009
33
34 The developer is responsible for checking modified source code
35 into the <project>/src directory, and built code into the
36 <project>/build directory, allowing them to review diffs,
37 before committing changes.
38
d3d5d3e @sdesai Cleaned up lists
sdesai authored Mar 2, 2009
39 b) Generate API documentation
3b587c6 @sdesai README update. Added build file templates to use as starting point fo…
sdesai authored Feb 26, 2009
40
cc4b53f @davglass Readme Updates
davglass authored Apr 3, 2012
41 Installation
3b587c6 @sdesai README update. Added build file templates to use as starting point fo…
sdesai authored Feb 26, 2009
42 ------------
43
44 Below is a brief summary as well as a detailed step-by-step guide
45 for installing the build system, allowing you to build the "src"
46 component code.
47
cc4b53f @davglass Readme Updates
davglass authored Apr 3, 2012
48 Summary
49 -------
3b587c6 @sdesai README update. Added build file templates to use as starting point fo…
sdesai authored Feb 26, 2009
50
d3d5d3e @sdesai Cleaned up lists
sdesai authored Mar 2, 2009
51 1) Install ANT 1.7 or above, and add ant to your path
3b587c6 @sdesai README update. Added build file templates to use as starting point fo…
sdesai authored Feb 26, 2009
52
d3d5d3e @sdesai Cleaned up lists
sdesai authored Mar 2, 2009
53 2) Clone the YUI "builder" project from http://github.com/yui/builder/
3b587c6 @sdesai README update. Added build file templates to use as starting point fo…
sdesai authored Feb 26, 2009
54
d3d5d3e @sdesai Cleaned up lists
sdesai authored Mar 2, 2009
55 3) At the command line, cd to the source directory of the component
56 you wish to build, and execute "ant all" to build, e.g.:
3b587c6 @sdesai README update. Added build file templates to use as starting point fo…
sdesai authored Feb 26, 2009
57
0e54d65 @sdesai Added download link to README. yuilibrary.com download page update pe…
sdesai authored Mar 10, 2009
58 prompt> cd yui2/src/autocomplete
59 prompt> ant all
3b587c6 @sdesai README update. Added build file templates to use as starting point fo…
sdesai authored Feb 26, 2009
60
cc4b53f @davglass Readme Updates
davglass authored Apr 3, 2012
61 Detailed Instructions
62 ---------------------
3b587c6 @sdesai README update. Added build file templates to use as starting point fo…
sdesai authored Feb 26, 2009
63
64 To use the build system, you'll need to install ANT and obtain
65 the YUI build infrastructure from github.
66
67 These are both one-time install tasks.
68
cc4b53f @davglass Readme Updates
davglass authored Apr 3, 2012
69 Installing Ant
70 --------------
3b587c6 @sdesai README update. Added build file templates to use as starting point fo…
sdesai authored Feb 26, 2009
71
d3d5d3e @sdesai Cleaned up lists
sdesai authored Mar 2, 2009
72 1) Download and install ANT 1.7 (or above)
3b587c6 @sdesai README update. Added build file templates to use as starting point fo…
sdesai authored Feb 26, 2009
73
d3d5d3e @sdesai Cleaned up lists
sdesai authored Mar 2, 2009
74 http://ant.apache.org/bindownload.cgi
3b587c6 @sdesai README update. Added build file templates to use as starting point fo…
sdesai authored Feb 26, 2009
75
d3d5d3e @sdesai Cleaned up lists
sdesai authored Mar 2, 2009
76 2) Be sure to define an ANT_HOME environment variable to point to
77 your ANT install root, and add the ANT executable to your
78 environment's PATH variable.
3b587c6 @sdesai README update. Added build file templates to use as starting point fo…
sdesai authored Feb 26, 2009
79
cc4b53f @davglass Readme Updates
davglass authored Apr 3, 2012
80 Installing YUI Build Infrastructure
81 -----------------------------------
3b587c6 @sdesai README update. Added build file templates to use as starting point fo…
sdesai authored Feb 26, 2009
82
d3d5d3e @sdesai Cleaned up lists
sdesai authored Mar 2, 2009
83 1) Clone the YUI "builder" project from github:
3b587c6 @sdesai README update. Added build file templates to use as starting point fo…
sdesai authored Feb 26, 2009
84
d3d5d3e @sdesai Cleaned up lists
sdesai authored Mar 2, 2009
85 http://github.com/yui/builder/
3b587c6 @sdesai README update. Added build file templates to use as starting point fo…
sdesai authored Feb 26, 2009
86
d3d5d3e @sdesai Cleaned up lists
sdesai authored Mar 2, 2009
87 This project contains the files used by the
88 YUI ant build process.
3b587c6 @sdesai README update. Added build file templates to use as starting point fo…
sdesai authored Feb 26, 2009
89
d3d5d3e @sdesai Cleaned up lists
sdesai authored Mar 2, 2009
90 2) Out of the box, the build system is designed to work
91 when cloned to the default "builder" directory, parallel
92 to the project source directories:
3b587c6 @sdesai README update. Added build file templates to use as starting point fo…
sdesai authored Feb 26, 2009
93
cc4b53f @davglass Readme Updates
davglass authored Apr 3, 2012
94 <gitroot>/yui2 ( cloned yui2 project )
95 <gitroot>/yui3 ( cloned yui2 project )
96 <gitroot>/builder ( cloned builder project )
3b587c6 @sdesai README update. Added build file templates to use as starting point fo…
sdesai authored Feb 26, 2009
97
d3d5d3e @sdesai Cleaned up lists
sdesai authored Mar 2, 2009
98 Cloning it to the default location will allow you to
99 build any of the components without having to modify any
100 component build scripts.
3b587c6 @sdesai README update. Added build file templates to use as starting point fo…
sdesai authored Feb 26, 2009
101
0e54d65 @sdesai Added download link to README. yuilibrary.com download page update pe…
sdesai authored Mar 10, 2009
102 NOTE: YUI Builder is also available for download as a zip from
103 http://yuilibrary.com/downloads. If downloading from this location
104 to build yui2 or yui3 source, make sure to unzip the contents into
105 the directory structure mentioned above, to have the build work out
106 of the box.
107
cc4b53f @davglass Readme Updates
davglass authored Apr 3, 2012
108 Building An Existing Component
3b587c6 @sdesai README update. Added build file templates to use as starting point fo…
sdesai authored Feb 26, 2009
109 ------------------------------
110
111 With ANT and the YUI build infrastructure installed, you can now build any
112 of the components from source, using the build.xml file in the component's
113 source directory.
114
115 The build system allows you to build locally, within the component's
116 source directory, and also run a full build to update the top level build
117 directory for a component.
118
cc4b53f @davglass Readme Updates
davglass authored Apr 3, 2012
119 Full Build
120 ----------
3b587c6 @sdesai README update. Added build file templates to use as starting point fo…
sdesai authored Feb 26, 2009
121
122 To perform a full build for a component, run ant with the "all" target:
123
124 e.g:
125
126 prompt> cd yui2/src/autocomplete
127 prompt> ant all
128
1f29cb2 @sdesai English as a second (or third) language cleanup
sdesai authored Mar 3, 2009
129 The "all" build target will build the component from its source files AND
3b587c6 @sdesai README update. Added build file templates to use as starting point fo…
sdesai authored Feb 26, 2009
130 deploy the built files, as well as any assets, to the top level build
131 folder:
132
133 <project>/build/<component>
134
135 So, for autocomplete, the built files would be copied to:
136
137 yui2/build/autocomplete
138
139 NOTE: When invoking ant without a file argument, as we do above, it will
140 use build.xml, if present in the current directory - which is what we want.
141
142 LOCAL BUILD
143
144 To perform a local build for a component, run ant without a target:
145
146 e.g:
147
148 prompt> cd yui2/src/autocomplete
149 prompt> ant
150
151 This will run the default target, which is "local".
152
153 The "local" build target will build the autocomplete component from its
154 source files, but will NOT deploy the built files to the top level build
155 folder.
156
157 The locally built files are stored in the temporary directory:
158
159 <project>/src/<component>/build_tmp
160
1f29cb2 @sdesai English as a second (or third) language cleanup
sdesai authored Mar 3, 2009
161 So, for autocomplete, the built files can be found in the directory below:
3b587c6 @sdesai README update. Added build file templates to use as starting point fo…
sdesai authored Feb 26, 2009
162
163 yui2/src/autocomplete/build_tmp
164
cc4b53f @davglass Readme Updates
davglass authored Apr 3, 2012
165 Build Output
166 ------------
3b587c6 @sdesai README update. Added build file templates to use as starting point fo…
sdesai authored Feb 26, 2009
167
168 ANT will output build information to the screen, as it runs through the
169 build, which can be redirected to a file if required:
170
171 prompt> ant all
172
173 Buildfile: build.xml
174 [echo] Starting Build For autocomplete
175 ...
176 [echo] builddir : ../../../builder/componentbuild
177 ...
178 ...
179 BUILD SUCCESSFUL
180 Total time: 7 seconds
181
182 prompt>
183
184 NOTE: Most components will have warnings which are output during the
185 "minify" and "lint" steps, which the component developer has evaluated
186 and determined to have no impact on functionality.
187
cc4b53f @davglass Readme Updates
davglass authored Apr 3, 2012
188 Creating Build Files For A New Component
3b587c6 @sdesai README update. Added build file templates to use as starting point fo…
sdesai authored Feb 26, 2009
189 ----------------------------------------
190
191 The builder/componentbuild/templates directory has basic build.xml and
1f29cb2 @sdesai English as a second (or third) language cleanup
sdesai authored Mar 3, 2009
192 build.properties templates for the various component types supported.
3b587c6 @sdesai README update. Added build file templates to use as starting point fo…
sdesai authored Feb 26, 2009
193
194 For most new components, you should be able to start with the
195 appropriate template files and simply change the values of the basic
196 properties defined to suit your component.
197
198 If you're creating:
199
200 * A YUI 2 Component (either a JS or CSS component), use:
201
202 builder/componentbuild/templates/yui2
0e54d65 @sdesai Added download link to README. yuilibrary.com download page update pe…
sdesai authored Mar 10, 2009
203
3b587c6 @sdesai README update. Added build file templates to use as starting point fo…
sdesai authored Feb 26, 2009
204 build.xml
205 build.properties
206
207 * A YUI 3 Component (either a JS or CSS component), use:
208
209 builder/componentbuild/templates/yui3
0e54d65 @sdesai Added download link to README. yuilibrary.com download page update pe…
sdesai authored Mar 10, 2009
210
3b587c6 @sdesai README update. Added build file templates to use as starting point fo…
sdesai authored Feb 26, 2009
211 build.xml
212 build.properties
213
214 * A YUI 3 Rollup Component, use:
215
216 builder/componentbuild/templates/yui3/rollup
217
218 For the rollup component:
219 build.xml
220 build.properties
221
222 For the sub components:
223 subcomponentone.xml
224 subcomponentone.properties
225 subcomponenttwo.xml
226 subcomponenttwo.properties
227
cc4b53f @davglass Readme Updates
davglass authored Apr 3, 2012
228 Further Customization
229 ---------------------
3b587c6 @sdesai README update. Added build file templates to use as starting point fo…
sdesai authored Feb 26, 2009
230
231 If required, you can define custom values for any of the properties
3df81a9 @sdesai Added targets documentation
sdesai authored Feb 26, 2009
232 defined in builder/componentbuild/docs/properties.html to customize the
233 build for your new component, however as mentioned above, for most
1f29cb2 @sdesai English as a second (or third) language cleanup
sdesai authored Mar 3, 2009
234 components the properties defined in the template files should be
3df81a9 @sdesai Added targets documentation
sdesai authored Feb 27, 2009
235 sufficient.
3b587c6 @sdesai README update. Added build file templates to use as starting point fo…
sdesai authored Feb 26, 2009
236
1f29cb2 @sdesai English as a second (or third) language cleanup
sdesai authored Mar 3, 2009
237 You can also override or extend existing targets, to customize the actual
3b587c6 @sdesai README update. Added build file templates to use as starting point fo…
sdesai authored Feb 26, 2009
238 build process for a component if required. The list of targets and their
3df81a9 @sdesai Added targets documentation
sdesai authored Feb 27, 2009
239 role is defined in builder/componentbuild/docs/targets.html.
da3e8d4 @sdesai Adding whitespace to verify CC CI builds are disabled
sdesai authored Dec 8, 2009
240
cc4b53f @davglass Readme Updates
davglass authored Apr 3, 2012
241
242 Log Verbosity
243 -------------
244
245 * `ant all` will give you the default log output, may be a little noisy
246 * `ant all -v` will give you full log output (really noisy)
247 * `ant all -q` will give you only the jslint output from your build
248
249 JSLint/Hint
250 -----------
251
252 By default, we look for the `node` executable. If found we use a Node.js based
253 JSLint server to lint the JS files. If it's not installed, we fall back to
254 Rhino (which can be very slow)
255
256 If you install the `jshint` (`npm -g i jshint`), we will use that by default.
257
258 To skip using this you can pass `-Djshint.skip=true`:
259
260 `ant all -q -Djshint.skip=true`
261
262 The default is also to only run jslint/hint on RAW files, skipping min and debug versions.
263
264 You can change this by adding `-Dlint.all=true` to your command:
265
266 `ant all -q -Dlint.all=true`
267
268
269
Something went wrong with that request. Please try again.