1 | ![Coffee Toaster](http://github.com/serpentem/coffee-toaster/blob/0.5.0/images/toaster.png?raw=true)
|
2 |
|
3 | Version 0.5.5
|
4 |
|
5 | CoffeeToaster is a dependency manager and build system for CoffeeScript.
|
6 |
|
7 | The main purpose is to provide a very comfortable environment to code large<BR>
|
8 | libraries using such things as class definitions and namespaces, in order to<BR>
|
9 | to help avoid naming collisions in your architecture.
|
10 |
|
11 | A smart 'require' powered by wild-cards is also provided, together with a<BR>
|
12 | powerful build system that concatenates everything and outputs a single<BR>
|
13 | javascript release file that can be even minified if you like.
|
14 |
|
15 | The build system was developed to offer vendors support, with specific<BR>
|
16 | ordering options. If you are adept of the extends directive in CoffeeScript,<BR>
|
17 | Toaster will even check if you have required base classes for the classes<BR>
|
18 | that extends another.
|
19 |
|
20 | The CLI program informs you about everything that is happening when a new<BR>
|
21 | file is created, deleted or modified. You can even drag'n'drop a folder with<BR>
|
22 | lots of CoffeeScript files inside your source folder and everything will be<BR>
|
23 | handled gracefully.
|
24 |
|
25 | If you are building for the browser you can use the debug option to compile<BR>
|
26 | everything individually -- plus, node targeted support is on the way. In <BR>
|
27 | debug mode you'll be gifted with a boot-loader that will load every file in<BR>
|
28 | the proper order according your needs.
|
29 |
|
30 | I should also mention that it's not some kind of AMD or CJS implementation,<BR>
|
31 | as you may be thinking. It's much more like a new point of view based on my<BR>
|
32 | specific needs and personal taste, which I didn't come up with a fancy name yet.
|
33 |
|
34 | Keep on reading this README, and please do not hesitate to open a feature<BR>
|
35 | request or a bug report.<BR>
|
36 | https://github.com/serpentem/coffee-toaster/issues
|
37 |
|
38 | In case of any doubts, drop an email at the email group and luckily you'll<BR>
|
39 | be answered sooner than later.<BR>
|
40 | https://groups.google.com/group/coffee-toaster
|
41 |
|
42 | # Features
|
43 |
|
44 | * Inheritance support across multiples files for the lazy
|
45 | * You can require any file whenever your want to
|
46 | * Vendors management
|
47 | * Packaging System & Namespaces
|
48 | * Automagic packaging system that uses folders as namespaces
|
49 | * Micro build routines to help you customize and release your peace of code
|
50 | * Exports aliases
|
51 | * Lets you set a top package to list all your modules
|
52 | * Broken and circular-loop dependencies validation
|
53 | * Helps you prevent some mistakes with circular dependencies loops and<BR>
|
54 | alerts you against dependencies not found
|
55 | * Live syntax-check
|
56 | * Precise live syntax-check with file path and line number information
|
57 | * Growl support
|
58 | * Warning/Error messages are shown even in growl
|
59 | * Debug Mode
|
60 | * In order to provide an easy debugging routine once inside the browser,<BR>
|
61 | all files will be compiled individually into its respectives '.js' versions<BR>
|
62 | and a smart boot-loader (your-debug-file.js) is provided to load every file<BR>
|
63 | orderly. Just include this boot-loader in your html file and voilà
|
64 | * Minify support
|
65 | * Aiming to be practical, the output can be even minified (using uglify-js)
|
66 | * Scaffolding routines
|
67 | * Interactive creation of a very simple skeleton for new projects and<BR>
|
68 | config file for existent projects
|
69 |
|
70 |
|
71 | # Installation
|
72 |
|
73 | npm install -g coffee-toaster
|
74 |
|
75 | # Usage
|
76 |
|
77 | ## Creating a new App
|
78 |
|
79 | CoffeeToaster suggests a very simple structure for initial projects, you can<BR>
|
80 | customize it as you like.
|
81 |
|
82 | toaster -n mynewapp
|
83 |
|
84 | You will be asked for some things:
|
85 |
|
86 | 1. **source folder** - Relative folderpath to your source folder.
|
87 | * i.e.: src
|
88 | 1. **release file** - Path to your release file.
|
89 | * i.e.: www/js/app.js
|
90 | 1. **http folder** - The folderpath to reach your debug file through http,<BR>
|
91 | in case it is not inside your root directory. Imagine that the 'www' is<BR>
|
92 | your root folder, so you'd just need to inform 'js' as the http folder.
|
93 | * i.e.: js
|
94 |
|
95 | Your release file will not be affected by the 'http folder' property.
|
96 |
|
97 | Considering all the default values, you'll end up with a structure as such:
|
98 |
|
99 | myawsomeapp/
|
100 | ├── src
|
101 | ├── vendors
|
102 | ├── www
|
103 | └── js
|
104 | └── toaster.coffee
|
105 |
|
106 | 4 directories, 1 file
|
107 |
|
108 | The toaster.coffee file will have this content:
|
109 |
|
110 | ````ruby
|
111 |
|
112 | # => SRC FOLDER
|
113 | toast 'src'
|
114 | # => VENDORS (optional)
|
115 | # vendors: ['vendors/x.js', 'vendors/y.js', ... ]
|
116 |
|
117 | # => OPTIONS (optional, default values listed)
|
118 | # bare: false
|
119 | # packaging: true
|
120 | # expose: ''
|
121 | # minify: false
|
122 |
|
123 | # => HTTPFOLDER (optional), RELEASE / DEBUG (required)
|
124 | httpfolder: 'js'
|
125 | release: 'www/js/app.js'
|
126 | debug: 'www/js/app-debug.js'
|
127 | ````
|
128 |
|
129 | ## Toasting an existing project
|
130 |
|
131 | Your can toast an existing project as such:
|
132 |
|
133 | cd existing-project
|
134 | toaster -i
|
135 |
|
136 | Or:
|
137 |
|
138 | toaster -i existing-project
|
139 |
|
140 | Some of the same information (src, release and http folder) will be required,<BR>
|
141 | answer everything according to your project's structure.
|
142 |
|
143 | A 'toaster.coffee' file will be created inside of it.
|
144 |
|
145 | ## When the magic happens
|
146 |
|
147 | To see all that CoffeeToaster can do for you, enter the project folder and<BR>
|
148 | type 'toaster -w' after creating or toasting a new project:
|
149 |
|
150 | cd existing-project
|
151 | toaster -w
|
152 |
|
153 | Or:
|
154 |
|
155 | toaster -w existing-project
|
156 |
|
157 | Your release file will be saved according your configuration.
|
158 |
|
159 | # Debug Mode
|
160 |
|
161 | In debug mode (option -d) all files will be compiled individually inside a<BR>
|
162 | folder called "toaster" in the same directory you've pointed your debug file,<BR>
|
163 | aiming to ease the debugging process.
|
164 |
|
165 | cd existing-project
|
166 | toaster -wd
|
167 |
|
168 | For example, if you have "release/app-debug.js", a folder will be created in<BR>
|
169 | "release/toaster" and all your CoffeeScript files will be compiled to<BR>
|
170 | Javascript within.
|
171 |
|
172 | Bellow is a representative directory structure:
|
173 |
|
174 | usage/
|
175 | ├── vendors
|
176 | ├── src
|
177 | │ ├── app
|
178 | │ │ └── app.coffee
|
179 | │ ├── artists
|
180 | │ │ ├── progressive
|
181 | │ │ │ ├── kingcrimson.coffee
|
182 | │ │ │ ├── themarsvolta.coffee
|
183 | │ │ │ └── tool.coffee
|
184 | │ │ └── triphop
|
185 | │ │ ├── lovage.coffee
|
186 | │ │ ├── massiveattack.coffee
|
187 | │ │ └── portishead.coffee
|
188 | │ └── genres
|
189 | │ ├── progressive.coffee
|
190 | │ └── triphop.coffee
|
191 | ├── www
|
192 | │ ├── index.html
|
193 | │ └── js
|
194 | │ ├── app.js
|
195 | │ ├── app-debug.js
|
196 | │ └── toaster
|
197 | │ ├── app
|
198 | │ │ └── app.js
|
199 | │ ├── artists
|
200 | │ │ ├── progressive
|
201 | │ │ │ ├── kingcrimson.js
|
202 | │ │ │ ├── themarsvolta.js
|
203 | │ │ │ └── tool.js
|
204 | │ │ └── triphop
|
205 | │ │ ├── lovage.js
|
206 | │ │ ├── massiveattack.js
|
207 | │ │ └── portishead.js
|
208 | │ └── genres
|
209 | │ ├── progressive.js
|
210 | │ └── triphop.js
|
211 | └── toaster.coffee
|
212 |
|
213 | The debug file you've chosen is the boot-loader responsible to load all your<BR>
|
214 | files into the right order.
|
215 |
|
216 | So in your .html you'll have two options:
|
217 |
|
218 | **1)** Include your release file.
|
219 |
|
220 | ````html
|
221 | <script src="js/app.js"></script>
|
222 | ````
|
223 |
|
224 | **2)** Include the toaster boot-loader (your debug mode).
|
225 |
|
226 | ````html
|
227 | <script src="js/app-debug.js"></script>
|
228 | ````
|
229 |
|
230 | # How does everything work?
|
231 |
|
232 | CoffeeToaster will create a file called 'toaster.coffee' in your app main folder.
|
233 |
|
234 | ## Config File (toaster.coffee)
|
235 |
|
236 | This file contains information of your app, i.e:
|
237 |
|
238 | ````ruby
|
239 |
|
240 | # => SRC FOLDER
|
241 | toast 'src'
|
242 | # => VENDORS (optional)
|
243 | # vendors: ['vendors/x.js', 'vendors/y.js', ... ]
|
244 |
|
245 | # => OPTIONS (optional, default values listed)
|
246 | # bare: false
|
247 | # packaging: true
|
248 | # expose: ''
|
249 | # minify: false
|
250 |
|
251 | # => HTTPFOLDER (optional), RELEASE / DEBUG (required)
|
252 | httpfolder: 'js'
|
253 | release: 'www/js/app.js'
|
254 | debug: 'www/js/app-debug.js'
|
255 | ````
|
256 |
|
257 | ### Vendors
|
258 |
|
259 | You can define vendors such as:
|
260 |
|
261 | ````ruby
|
262 |
|
263 | vendors: ['vendors/x.js', 'vendors/y.js', ... ]
|
264 | ````
|
265 |
|
266 | It's an ordered array of all your vendor's paths. These files must be purely<BR>
|
267 | javascript, preferably minified ones -- Toaster will not compile or minify<BR>
|
268 | them, only concatenate everything.
|
269 |
|
270 | ### Bare
|
271 |
|
272 | If true, compile your CS files without the top-level function safety wrapper:
|
273 |
|
274 | ````javascript
|
275 |
|
276 | (function() {
|
277 | # bunch of code
|
278 | }).call(this);
|
279 | ````
|
280 |
|
281 | So you will end up with just 'bunch of code':
|
282 |
|
283 |
|
284 | ````javascript
|
285 |
|
286 | # bunch of code
|
287 | ````
|
288 |
|
289 | ### Packaging
|
290 |
|
291 | If true, use all your folders as namespaces to your class definitions.
|
292 |
|
293 | If you have class 'Lovage' declared inside the "artists/triphop" folder, you<BR>
|
294 | can access it through 'artists.triphop.Lovage'.
|
295 |
|
296 | ````javascript
|
297 |
|
298 | # usual way
|
299 | new Lovage
|
300 |
|
301 | # with packaging=true
|
302 | new artists.triphop.Lovage
|
303 | ````
|
304 |
|
305 | ### Expose
|
306 |
|
307 | If informed, list all you packages of classes in the given scope. If you use<BR>
|
308 | 'window' as your expose scope, your classes will be available also in the<BR>
|
309 | window object -- or whatever scope you inform.
|
310 |
|
311 | ````javascript
|
312 |
|
313 | new window.artists.triphop.Lovage
|
314 | ````
|
315 |
|
316 | ### Minify
|
317 |
|
318 | If true, minify your release file -- debug files are never minified.
|
319 |
|
320 | ### HTTP Folder
|
321 |
|
322 | The folder path to reach your debug file through http, in case it is not<BR>
|
323 | inside your root directory. Imagine that the 'www' is your root folder, and<BR>
|
324 | you have a 'js' folder inside of it with your 'debug.js' file inside of it.
|
325 |
|
326 | Following this case you'd just need to inform 'js' as your http folder.
|
327 |
|
328 | So the declarations inside the debug boot loader will follow this location<BR>
|
329 | in order to import your scripts in debug mode, prepending your http folder<BR>
|
330 | to all file paths.
|
331 |
|
332 | Your release file will not be affected by this property.
|
333 |
|
334 | ### Release
|
335 |
|
336 | The file path to your release file.
|
337 |
|
338 | ### Debug
|
339 |
|
340 | The file path to your debug file.
|
341 |
|
342 | ## Conlusion
|
343 |
|
344 | So when you call 'toaster -w' in this directory, this config is loaded and<BR>
|
345 | every file and folder inside 'src' folder will be watched.
|
346 |
|
347 | If debug is enabled (option -d), files will be also compiled individually<BR>
|
348 | for a sane debugging routine inside the browser, in the same directory you<BR>
|
349 | have your debug file.
|
350 |
|
351 | Every time something changes, CoffeeToaster re-compiles all of your<BR>
|
352 | application by:
|
353 |
|
354 | * collecting all .coffee files and processing everything, adding package<BR>
|
355 | declarations to class definitions based on the folder they are located
|
356 | * re-ordering everything, always defining files and classes before<BR>
|
357 | they're needed
|
358 | * merge all yours vendors in the given order
|
359 | * declare root namespaces
|
360 | * merge everything
|
361 |
|
362 | Hold it! How the hell does it know when my files or classes are needed?
|
363 |
|
364 | ## Import directive
|
365 |
|
366 | The import directive is known by:
|
367 |
|
368 | * #<< app/views/user_view
|
369 | * #<< app/utils/*
|
370 |
|
371 | By putting '#<< app/views/user_view' in your CoffeeScript file, you're<BR>
|
372 | telling CoffeeToaster that there's a dependency.
|
373 |
|
374 | Wild cards '#<< app/utils/*' are also accepted as a handy option.
|
375 |
|
376 | # Examples
|
377 |
|
378 | You'll certainly find some useful resources in the usage example provided.<BR>
|
379 | Examine it and you'll understand how things works more instinctively.
|
380 |
|
381 | Install coffee-toaster, clone the usage example and try different config<BR>
|
382 | options, always looking for the differences in your javascript release file.
|
383 |
|
384 | > [Source Code](https://github.com/serpentem/coffee-toaster/tree/master/usage)
|
385 |
|
386 | # Issues
|
387 |
|
388 | Do not hesitate to open a feature request or a bug report.<BR>
|
389 | https://github.com/serpentem/coffee-toaster/issues
|
390 |
|
391 | # Mailing List
|
392 |
|
393 | A place to talk about it, ask anything, get in touch. Luckily you'll<BR>
|
394 | be answered sooner than later.<BR>
|
395 | https://groups.google.com/group/coffee-toaster
|
396 |
|
397 | # Changelog
|
398 |
|
399 | ## 0.5.5 - 04/19/2012
|
400 | * Config file was re-written to be more practical
|
401 | * Build routines removed in favor of simplicity
|
402 | * Multi-modules option is default now, without configuring anything
|
403 | * HTTP Folder property added to 'toaster.coffee' config file
|
404 | * Scaffolding routines improved according the design changes
|
405 |
|
406 | ## 0.5.0 - 04/12/2012
|
407 | * Packaging system completely revamped
|
408 | * Added some beauty to log messages
|
409 | * Growl integration implemented
|
410 | * Expose / Export aliases - export/expose your definitions to another scope
|
411 | * Minify support added
|
412 | * On/Off switches for:
|
413 | * Bare option to compile CoffeeScript with the 'bare' option
|
414 | * Packaging system
|
415 | * Minify
|
416 |
|
417 | ## 0.3.8 - 10/29/2011
|
418 | * Fixing bugs in generators
|
419 | * Fixing a bunch of small emergencial bugs
|
420 |
|
421 | ## 0.3.7 - 10/29/2011
|
422 | * Simplify config file syntax [feature done [#8](https://github.com/serpentem/coffee-toaster/issues/8)]
|
423 | * Adding buid routines [feature done [#9](https://github.com/serpentem/coffee-toaster/issues/9)]
|
424 | * Adding support for vendors across modules and build configs [feature [#10](https://github.com/serpentem/coffee-toaster/issues/10)]
|
425 |
|
426 | ## 0.3.6 - 10/25/2011
|
427 | * Critical bugfixes in the reorder routine
|
428 | * Optimizing architecture
|
429 | * Condensing src scructure
|
430 |
|
431 | ## 0.3.5 - 10/24/2011
|
432 | * Avoiding tmp files from being watched [closing issue [#4](http://github.com/serpentem/coffee-toaster/issues/4)]
|
433 | * Adding support for ordinary files again (with no class definitions inside)
|
434 | * Now all requirements must to be done based on filepath with slash<BR>
|
435 | notation "foldera/folderb/filename"
|
436 | * Adding extra base class validation
|
437 | * Lots of improvements and bugfixes
|
438 |
|
439 | ## 0.3.0 - 10/16/2011
|
440 | * Refactoring entire Script class
|
441 | * Support for extends directive have been removed, now all dependencies<BR>
|
442 | must be informed through '#<< package.name.ClassName'
|
443 | * Support for files without class declarations was (sadly) removed
|
444 | * Adding full package support automagically
|
445 | * Implementing wild-cards on requirements '#<< package.name.*'
|
446 |
|
447 | ## 0.2.2 - 10/02/2011
|
448 | * Starting tests implementation (using Vows BDD)
|
449 | * Implementing debug mode (-d --debug). Files are compiled individually<BR>
|
450 | plus a boot file (toaster.js) file that will load everything in the right order.
|
451 | * Improving interactive processes to become good guessers
|
452 | * Adding support for file requirements based on 'a/b/c/filepath'<BR>
|
453 | simultaneously with class requirements based in 'ClassName' notation (both<BR>
|
454 | are case sensitive)
|
455 | * Bumping 'build/coffee-toaster' submodule to use tag 0.2.2 (level up)
|
456 |
|
457 | ## 0.2.1 - 09/22/2011
|
458 | * Implementing OptionParser (using Optimist)
|
459 |
|
460 | ## 0.2.0 - 09/18/2011
|
461 | * Tag 0.1.2 is now used as submodule in order to self-toast (aka manage<BR>
|
462 | dependencies) of new versions of CoffeeToaster itself, starting from now
|
463 | * Refactoring everything, classes are now one per file, using dependency<BR>
|
464 | directives from CoffeeToaster itself. From now on, things should evolve<BR>
|
465 | a little easier.
|
466 | * Individualizing CoffeeScript handling
|
467 | * Starting plans for CoffeeKup and CoffeeCss support
|
468 |
|
469 | ## 0.1.2 - 09/17/2011
|
470 | * Fixing compilation method that was requiring coffee-script to be installed
|
471 | * Adding precise error handling
|
472 | * Checking circular dependency conflicts [closing issue [#2](http://github.com/serpentem/coffee-toaster/issues/2)]
|
473 |
|
474 | ## 0.1.1 - 09/16/2011
|
475 | * Adding basic error handling [closing issue [#1](http://github.com/serpentem/coffee-toaster/issues/1)]
|
476 |
|
477 | ## 0.1.0 - 09/11/2011
|
478 | * Scaffolding routine for new projects
|
479 | * Scaffolding routine for configuration file (toaster.coffee)
|
480 | * Dependency handlers:
|
481 | * Extends directive (class A extends B)
|
482 | * Include directive (#<< ClassNameA, ClassNameB..)
|
483 |
|
\ | No newline at end of file |