Skip to content
Browse files

update description and travis badge

  • Loading branch information...
1 parent e2dc455 commit 8b138698f4ca44f05d651689bab982c9b544d944 @popeindustries committed
Showing with 4 additions and 4 deletions.
  1. +2 −2 README.md
  2. +2 −2 package.json
View
4 README.md
@@ -1,5 +1,5 @@
-<!-- [![Build Status](https://travis-ci.org/popeindustries/buddy.png)](https://travis-ci.org/popeindustries/buddy)
- -->
+[![Build Status](https://travis-ci.org/popeindustries/buddy.png)](https://travis-ci.org/popeindustries/buddy)
+
# buddy(1)
**buddy(1)** is a build tool for js/css/html projects. It helps you manage third-party dependencies, compiles source code from higher order js/css/html languages (CoffeeScript/LiveScript/Handlebars/Stylus/Less/Jade), automatically wraps js files in module definitions, statically resolves module dependencies, and concatenates (and optionally compresses) all souces into a single file for more efficient delivery to the browser.
View
4 package.json
@@ -1,6 +1,6 @@
{
"name": "buddy",
- "description": "A build tool for js/css/html projects. Manages third-party dependencies, compiles source code, automatically modularizes js sources, statically resolves module dependencies, and lints/concatenates/compresses output.",
+ "description": "A build tool for js/css/html projects.",
"version": "0.9.3",
"author": "popeindustries <alex@pope-industries.com>",
"keywords": ["build", "buildtool", "modules", "javascript", "coffeescript", "css", "styus", "less", "livescript", "handlebars", "jade"],
@@ -46,6 +46,6 @@
"url": "git://github.com/popeindustries/buddy.git"
},
"readmeFilename": "README.md",
- "readme": "<!-- [![Build Status](https://travis-ci.org/popeindustries/buddy.png)](https://travis-ci.org/popeindustries/buddy)\n -->\n# buddy(1)\n\n**buddy(1)** is a build tool for js/css/html projects. It helps you manage third-party dependencies, compiles source code from higher order js/css/html languages (CoffeeScript/LiveScript/Handlebars/Stylus/Less/Jade), automatically wraps js files in module definitions, statically resolves module dependencies, and concatenates (and optionally compresses) all souces into a single file for more efficient delivery to the browser.\n\n**Current version:** 0.9.3 *[See [Change Log](#a1) below for more details]*\n\n## Features\n\n- Allows you to write js __modules__ without the module boilerplate (similar to Node.js)\n- Resolves js module __dependencies__ automatically\n- Supports ___lazy___ runtime evaluation by storing js modules as strings\n- __Compiles__ _CoffeeScript_, _LiveScript_, _Handlebars_, _Stylus_, _Less_, and _Jade_ source files\n- __Concatenates__ js modules into a single file\n- Runs js and css code through __linters__ to check for syntax errors\n- __Watches__ for source changes and builds automatically\n- __Serves__ static files from specified directory on specified port\n- __Refreshes__ connected browsers after each change\n- __Inlines__ css `@imports` automatically\n- Supports execution of a ___test___ script after each build\n- Copies __libraries__ from GitHub to your project\n- Copies __assets__ from a local destination to your project\n\n## Installation\n\nTo avoid running **buddy(1)** directly as a global command, and thus avoid versioning problems across different projects, it is highly recommended that you instead install the separate [buddy-cli](https://github.com/popeindustries/buddy-cli) command line interface system-wide:\n\n```bash\n$ npm -g install buddy-cli\n```\n\n...then create a *package.json* file for each project, locally installing **buddy** as a devDependency:\n\n```json\n{\n \"name\": \"myproject\",\n \"description\": \"This is my web project\",\n \"version\": \"0.0.1\",\n \"devDependencies\": {\n \"buddy\": \"0.9.0\"\n }\n}\n```\n```bash\n$ cd path/to/project\n$ npm install\n```\n\n## Usage\n\n```text\nUsage: buddy [options] <command> [path/to/package.json or path/to/buddy.js or path/to/buddy.json]>\n\nCommands:\n\n install [config] install dependencies\n build [config] build js and css sources\n watch [config] watch js and css source files and build changes\n deploy [config] build compressed js and css sources\n ls list all previously created files and directories\n clean remove all previously created files and directories\n\nOptions:\n\n -h, --help output usage information\n -V, --version output the version number\n -c, --compress compress output for production deployment\n -l, --lint check output for syntax and logic errors\n -r, --reload reload all connected live-reload clients on file change during watch\n -s, --serve create a webserver to serve static files during watch\n -t, --test run test command on build completion\n -L, --lazy convert js modules for lazy evaluation\n -v, --verbose print all messages for debugging\n```\n\n### Examples\n\nGenerate `www/main.js` by concatenating and modularizing all dependencies in `src` or `libs/js` referenced in `src/main.js`:\n\n```json\npackage.json\n{\n \"name\": \"myproject\",\n \"description\": \"This is my web project\",\n \"version\": \"0.0.1\",\n \"dependencies\": {\n \"browser-require\": \"git://github.com/popeindustries/browser-require.git\"\n },\n \"devDependencies\": {\n \"buddy\": \"0.9.0\"\n },\n \"buddy\": {\n \"build\": {\n \"js\": {\n \"sources\": [\"src\", \"libs/js\"],\n \"targets\": [\n {\n \"input\": \"src/main.js\",\n \"output\": \"www/main.js\"\n }\n ]\n }\n }\n }\n}\n```\n```bash\n$ buddy build\n```\n\nGenerate `www/main.js` with references to dependencies installed via npm, ignoring Buddy specific packages:\n\n```json\npackage.json\n{\n \"name\": \"myproject\",\n \"description\": \"This is my web project\",\n \"version\": \"0.0.1\",\n \"dependencies\": {\n \"browser-require\": \"git://github.com/popeindustries/browser-require.git\",\n \"underscore\": \"1.4.4\"\n },\n \"devDependencies\": {\n \"buddy\": \"0.9.0\"\n },\n \"buddy\": {\n \"build\": {\n \"js\": {\n \"sources\": [\"src\", \"node_modules\", \"!node_modules/buddy\", \"!node_modules/browser-require\"],\n \"targets\": [\n {\n \"input\": \"src/main.js\",\n \"output\": \"www/main.js\"\n }\n ]\n }\n }\n }\n}\n```\n```bash\n$ buddy build\n```\n\nFirst compile all CoffeeScript files in `libs/src/coffee`, then generate `www/main.js` by concatenating and modularizing all dependencies referenced in 'src/main.js':\n\n```json\npackage.json\n{\n \"name\": \"myproject\",\n \"description\": \"This is my web project\",\n \"version\": \"0.0.1\",\n \"dependencies\": {\n \"browser-require\": \"git://github.com/popeindustries/browser-require.git\"\n },\n \"devDependencies\": {\n \"buddy\": \"0.9.0\"\n },\n \"buddy\": {\n \"build\": {\n \"js\": {\n \"sources\": [\"src\", \"libs/js\", \"libs/src/coffee\"],\n \"targets\": [\n {\n \"input\": \"libs/src/coffee\",\n \"output\": \"libs/js\"\n },\n {\n \"input\": \"src/main.js\",\n \"output\": \"www/main.js\"\n }\n ]\n }\n }\n }\n}\n```\n```bash\n$ buddy build\n```\n\nGenerate `www/main.js` and an additional widget `www/widget.js` using shared sources (avoid duplicating dependencies):\n\n```json\npackage.json\n{\n \"name\": \"myproject\",\n \"description\": \"This is my web project\",\n \"version\": \"0.0.1\",\n \"dependencies\": {\n \"browser-require\": \"git://github.com/popeindustries/browser-require.git\"\n },\n \"devDependencies\": {\n \"buddy\": \"0.9.0\"\n },\n \"buddy\": {\n \"build\": {\n \"js\": {\n \"sources\": [\"src\", \"libs/js\"],\n \"targets\": [\n {\n \"input\": \"src/main.js\",\n \"output\": \"www/main.js\",\n \"targets\": [\n {\n \"input\": \"src/widget.js\",\n \"output\": \"www/widget.js\"\n }\n ]\n }\n ]\n }\n }\n }\n}\n```\n```bash\n$ buddy build\n```\n\nCompile a CoffeeScript project for Node.js, skipping module wrapping and concatenation:\n\n```json\npackage.json\n{\n \"name\": \"myproject\",\n \"description\": \"This is my node project\",\n \"version\": \"0.0.1\",\n \"devDependencies\": {\n \"buddy\": \"0.9.0\"\n },\n \"buddy\": {\n \"build\": {\n \"js\": {\n \"sources\": [\"src/coffee\"],\n \"targets\": [\n {\n \"input\": \"src/coffee\",\n \"output\": \"js\",\n \"modular\": false\n }\n ]\n }\n }\n }\n}\n```\n```bash\n$ buddy build\n```\n\nCopy project boilerplate from a local directory into the project root:\n\n```json\npackage.json\n{\n \"name\": \"myproject\",\n \"description\": \"This is my web project\",\n \"version\": \"0.0.1\",\n \"devDependencies\": {\n \"buddy\": \"0.9.0\"\n },\n \"buddy\": {\n \"dependencies\": {\n \".\": {\n \"sources\": [\"../../boilerplate/project\"]\n }\n }\n }\n```\n```bash\n$ buddy install\n```\n\nDownload js dependencies `browser-require` and `jQuery`, then concatenate and compress to `www/libs.js` for inclusion in html:\n\n```json\npackage.json\n{\n \"name\": \"myproject\",\n \"description\": \"This is my web project\",\n \"version\": \"0.0.1\",\n \"devDependencies\": {\n \"buddy\": \"0.9.0\"\n },\n \"buddy\": {\n \"dependencies\": {\n \"libs/vendor\": {\n \"sources\": [\n \"popeindustries/browser-require\",\n \"jquery@1.9.1\"\n ],\n \"output\": \"www/libs.js\"\n }\n }\n }\n```\n```bash\n$ buddy install\n```\n\nDownload `visionmedia/nib` Stylus sources, specifying a specific directory to be referenced in your builds:\n\n```json\npackage.json\n{\n \"name\": \"myproject\",\n \"description\": \"This is my web project\",\n \"version\": \"0.0.1\",\n \"devDependencies\": {\n \"buddy\": \"0.9.0\"\n },\n \"buddy\": {\n \"dependencies\": {\n \"libs/src/css\": {\n \"sources\": [\n \"visionmedia/nib#lib/nib\"\n ]\n }\n }\n }\n}\n```\n```bash\n$ buddy install\n```\n\nStart a basic web server and refresh the browser (using the Live-Reload browser plugin) after each build triggered by source file changes:\n\n```json\npackage.json\n{\n \"name\": \"myproject\",\n \"description\": \"This is my web project\",\n \"version\": \"0.0.1\",\n \"devDependencies\": {\n \"buddy\": \"0.9.0\"\n },\n \"buddy\": {\n \"settings\": {\n \"server\": {\n \"directory\": \"www\",\n \"port\": 8080\n }\n }\n }\n}\n```\n```bash\n$ buddy watch -rs\n```\n\n### Configuration\n\nComplete annotated `buddy.js` configuration file:\n\n```js\n// Project build configuration.\nexports.build = {\n js: {\n // Directories containing potential js source files for this project.\n sources: ['a/coffeescript/source/directory', 'a/js/source/directory', '!a/js/source/directory/ignored'],\n // One or more js build targets.\n targets: [\n {\n // An entrypoint js (or equivalent) file to be wrapped in a module definition,\n // concatenated with all it's resolved dependencies.\n input: 'a/coffeescript/or/js/file',\n // A destination in which to save the processed input.\n // If a directory is specified, the input file name will be used.\n output: 'a/js/file/or/directory',\n // An alternate destination in which to save the compressed output.\n output_compressed: 'a/js/file/or/directory',\n // Targets can have children.\n // Any sources included in the parent target will NOT be included in the child.\n targets: [\n {\n input: 'a/coffeescript/or/js/file',\n output: 'a/js/file/or/directory'\n }\n ]\n },\n {\n // Files are batch processed when a directory is used as input.\n input: 'a/coffeescript/or/js/directory',\n output: 'a/js/directory',\n // Skips module wrapping (ex: for use in server environments).\n modular: false\n }\n ]\n },\n css: {\n // Directories containing potential css source files for this project.\n sources: ['a/stylus/directory', 'a/less/directory', 'a/css/directory'],\n // One or more css build targets\n targets: [\n {\n // An entrypoint css (or equivalent) file to be processed,\n // concatenated with all it's resolved dependencies.\n input: 'a/stylus/less/or/css/file',\n // A destination in which to save the processed input.\n // If a directory is specified, the input file name will be used.\n output: 'a/css/file/or/directory'\n },\n {\n // Files are batch processed when a directory is used as input, though @import'ed dependencies are still resolved.\n input: 'a/stylus/less/or/css/directory',\n output: 'a/css/directory'\n }\n ]\n }\n}\n\n// Project dependency configuration.\nexports.dependencies = {\n // A destination directory in which to place third-party library dependencies.\n 'a/vendor/directory': {\n // An ordered list of dependencies\n sources: [\n // A github user/repo.\n // Install the 'browser-require' source when using Node-style modules.\n 'popeindustries/browser-require',\n // A named library with or without version (ex: jquery@latest, backbone, backbone@1.0.0).\n // Version identifiers follow the npm semantic versioning rules.\n 'library@version'\n ],\n // Dependencies can be packaged and minified to a destination file\n output: 'a/js/file'\n },\n // A destination directory in which to place source library dependencies.\n 'a/source/directory': {\n sources: [\n // A github user/repo.\n // Will use the 'main' or 'scripts' properties of\n // components.json or package.json to identify the file to install.\n 'username/repo',\n // A github user/repo with specific file or directory locations.\n 'username/repo#a/file/or/directory|another/file/or/directory',\n // A local file or directory to copy and install.\n 'a/file/or/directory'\n ]\n }\n}\n\n// Project settings configuration.\nexports.settings = {\n // Run a command after build\n test: 'command --flags',\n // Configure webserver\n server: {\n // Defaults to project root\n directory: 'a/project/directory',\n // Defaults to 8080\n port: 8000\n },\n // Override the default plugins, and/or include custom plugins.\n plugins: {\n js: {\n // Append one or more js compilers to the default 'coffeescript'.\n compilers: ['a/file', 'another/file'],\n // Change the default 'uglifyjs' compressor to a custom specification.\n compressor: 'a/file',\n // Change the default 'jshint' linter to a custom specification.\n linter: 'a/file',\n // Change the default 'node' module type to 'amd' or a custom specification.\n module: 'amd'\n },\n css: {\n // Append one or more css compilers to the default 'stylus' and 'less'.\n compilers: ['a/file', 'another/file'],\n // Change the default 'cleancss' compressor to a custom specification.\n compressor: 'a/file',\n // Change the default 'csslint' linter to a custom specification.\n linter: 'a/file'\n }\n }\n}\n```\n\n## Concepts\n\n### BUILD\n\n**Project Root**: The directory from which all paths resolve to. Determined by location of the configuration file.\n\n**Sources**: An array of directories from which all referenced files are retrieved from. ***Note:*** A *js* module's id is derived from it's relative path to it's source directory.\n\n**Targets**: Objects that specify the *input* and *output* files or directories for each build. Targets are built in sequence, allowing builds to be chained together. ***Note:*** A *js* target can also have nested child targets, ensuring that dependencies are not duplicated across related builds.\n\n**Target parameters**:\n\n- *input*: file or directory to build. If js (or equivalent) file, all dependencies referenced will be concatenated together for output.\nIf directory, all compileable files will be compiled, wrapped in module definitions (js), and output to individual js/css files.\n\n- *output*: file or directory to output to.\n\n- *targets*: a nested target that prevents the duplication of source code with it's parent target.\n\n- *modular*: a flag to prevent js files from being wrapped with a module definition.\n\n- *output_compressed*: an alternate file or directory to use for compressed output.\n\n### MODULES\n\nEach js file is wrapped in a module declaration based on the file's location. Dependencies are determined by the use of ```require()``` statements:\n\n```javascript\nvar lib = require('./my/lib'); // in current package\nvar SomeClass = require('../someclass'); // in parent package\nvar util = require('utils/util'); // from root package\n\nlib.doSomething();\nvar something = new SomeClass();\nutil.log('hey');\n```\n\nSpecifying a module's public behaviour is achieved by decorating an ```exports``` object:\n\n```javascript\nvar myModuleVar = 'my module';\n\nexports.myModuleMethod = function() {\n return myModuleVar;\n};\n```\n\n...or overwriting the ```exports``` object completely:\n\n```javascript\nfunction MyModule() {\n this.myVar = 'my instance var';\n};\n\nMyModule.prototype.myMethod = function() {\n return this.myVar;\n};\n\nmodule.exports = MyModule;\n```\n\nEach module is provided with a ```module```, ```exports```, and ```require``` reference.\n\nWhen ```require()```-ing a module, keep in mind that the module id is resolved based on the following rules:\n\n * packages begin at the root folder specified in *build > js > sources*:\n```\n'Users/alex/project/src/package/main.js' > 'package/main'\n```\n * uppercase filenames are converted to lowercase module ids:\n```\n'my/package/Class.js' > 'my/package/class'\n```\n\nSee [node.js modules](http://nodejs.org/docs/v0.8.0/api/modules.html) for more info on modules.\n\n***NOTE***: ```require``` boilerplate needs to be included on the page to enable module loading. It's recommended to ```install``` a library like *popeindustries/browser-require*.\n\n### DEPENDENCIES\n\nDependency resources are installed from local locations or remotely from Github.\n\n**Sources**: An array of local or remote resource locations.\n\n- **destination**: each group of sources will be installed to the project relative location specified.\n\n- **identifier**: github ```username/repo``` identifiers are preferred, but it is also possible to use identifiers from the [bower](https://github.com/twitter/bower) package manager: ```'jquery', 'backbone', 'underscore'```\n\n- **versioning**: github sources can specify a version by appending ```@``` and a npm-style symantic version: ```'*', '1.2.3', '1.x', '~1.2.0', '>=1.2.3'```\n\n- **resources**: specific resources can be specified by appending ```#``` and a list of ```|``` separated relative file or directory locations: ```'username/repo#a/file/or/directory|another/file/or/directory'```\n\n**Output**: A file destination to concatenate and compress the source contents. The order of *sources* determines the content order.\n\n<a name=\"a1\"/>\n## Changelog\n\n**0.9.3** - March 11, 2013\n* fixed bug that prevented file changes from refreshing the browser during live-reload `watch`\n\n**0.9.2** - March 5, 2013\n* fixed bug that prevented file dependencies from being reset between builds during `watch`\n\n**0.9.1** - March 5, 2013\n* added support for using [buddy-cli](https://github.com/popeindustries/buddy-cli)\n\n**0.9.0** - February 28, 2013\n* added basic webserver with `-s --serve` flag\n* added support for LiveScript js files\n* added support for precompiling Handlebars templates to .js\n\n**0.8.0** - February 27, 2013\n* moved dependency installer, terminal printing, file watching, and fs utils into separate projects\n* added basic jade html template support\n* css dependencies are now able to be imported multiple times in the same build target\n\n**0.7.3** - February 18, 2013\n* added ignore syntax for build sources: `[\"a/source/directory\", \"!a/source/directory/ignored\"]`\n* added build target property to specify the name and location of compressed output: `output_compressed`\n* fixed an error related to index.js module renaming so that it only affects files in the root of source folders. Avoids multiple `index` modules\n\n**0.7.2** - February 17, 2013\n* build target input files that are not in an existing source location, but in the project path, are added automatically\n* `package/index.js` files are now given a module name of `package` instead of `package/index`\n\n**0.7.1** - February 16, 2013\n* added support for definining configuration in package.json under a `buddy` entry\n* fixed dependency install error for zipballs that don't match their unzipped folder names\n* upgraded dependencies\n\n**0.7.0** - January 7, 2013\n* bye bye CoffeeScript - migrated to js only source\n* upgraded dependencies\n\n**0.6.11** - December 21, 2012\n* fix css comment removal deleting base64 content\n\n**0.6.10** - December 21, 2012\n* updated _Uglify-js_ compressor to 2.0\n\n**0.6.9** - December 14, 2012\n* fixed _watch_ not adding new file during renames\n\n**0.6.8** - December 13, 2012\n* fixed _install_ crash\n* _install_ now overwrites previously downloaded resources\n* properly handle duplicate `@import` rules while inlining\n\n**0.6.7** - December 11, 2012\n* added _--lazy_ option for generating js modules for lazy evaluation; module contents are encoded as strings to be passed to a Function constructor on first require()\n\n**0.6.6** - December 6, 2012\n* added live-reload support for _watch_ command with _--reload_\n* re-enabled linting support\n\n**0.6.5** - December 5, 2012\n* fix for *watch* command firing repeated change events\n* fix for *watch* command not properly building targets on change\n* fix for child target building shared resources\n\n**0.6.4** - December 4, 2012\n* fix for _--test_ not displaying both stdout and stderr\n* added wrapping of batch files in module definitions if _options.modular_ is not false\n* fix for building targets that contain no source\n\n**0.6.3** - December 4, 2012\n* fix for _watch_ command attempting to watch a source that doesn't exist\n* added support for default json config file type\n\n**0.6.2** - December 4, 2012\n* fix for css _@import_ inlining\n\n**0.6.1** - December 3, 2012\n* added _--test_ to watch command\n\n**0.6.0** - December 3, 2012\n* complete rewrite for async file operations\n* added _--test_ flag for executing a command after build\n* added _--verbose_ flag for outputting detailed notifications during build\n* added _ls_ command to list all generated files\n* added inlining of '@import' rules for all css source types\n* simplified dependency resource parsing on install; only parse 'main' field in component.json/package.json\n\n**0.5.4** - November 23, 2012\n* regression fix for _clean_ command\n* improved _.buddy-filelog_ force clean\n* improved notifications for _install_ and *clean* commands\n\n**0.5.3** - November 23, 2012\n* refactored _install_ command behaviour; no longer uses git operations, changed syntax for specifying version ('@') and resources ('#'), added ability to list several resources __[breaking change]__\n* _.buddy-filelog_ now stores relative paths for compatibility on different systems\n* file deletions limited to resources under the project root\n\n**0.5.2** - Novemver 20, 2012\n* added _watch_ command; handle add, remove, and change of source files\n\n**0.5.1** - Novemver 14, 2012\n* added _clean_ command to remove all generated files\n* added hidden _.buddy-filelog_ file for tracking files changes between sessions\n* fix for false-negative module wrapping test\n\n**0.5.0** - November 13, 2012\n* _compile_ command renamed to *build* __[breaking change]__\n* changed module naming for compatibility with recent versions of Node.js (camel case no longer converted to underscores) __[breaking change]__\n* changed configuration file type to 'js' from 'json'; added _dependencies_ and _settings_ __[breaking change]__\n* changed configuration _target_ parameters to _input/output_ from _in/out_ __[breaking change]__\n* changed configuration _target_ parameter to _modular_ from _nodejs_ __[breaking change]__\n* concatenated js modules no longer self-booting; need to ```require('main');``` manually __[breaking change]__\n* _require_ boilerplate no longer included in generated source; install _popeindustries/browser-require_ or equivalent __[breaking change]__\n* removed _watch_ command (temporarily) __[breaking change]__\n* added _install_ command and project dependency management\n* added plugin support for compilers, compressors, linters, and modules; added support for custom plugins\n* added code linting\n* all errors now throw\n* complete code base refactor\n\n## License\n\n(The MIT License)\n\nCopyright (c) 2011 Pope-Industries &lt;alex@pope-industries.com&gt;\n\nPermission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the 'Software'), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.\n\nTHE 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.",
+ "readme": "[![Build Status](https://travis-ci.org/popeindustries/buddy.png)](https://travis-ci.org/popeindustries/buddy)\n\n# buddy(1)\n\n**buddy(1)** is a build tool for js/css/html projects. It helps you manage third-party dependencies, compiles source code from higher order js/css/html languages (CoffeeScript/LiveScript/Handlebars/Stylus/Less/Jade), automatically wraps js files in module definitions, statically resolves module dependencies, and concatenates (and optionally compresses) all souces into a single file for more efficient delivery to the browser.\n\n**Current version:** 0.9.3 *[See [Change Log](#a1) below for more details]*\n\n## Features\n\n- Allows you to write js __modules__ without the module boilerplate (similar to Node.js)\n- Resolves js module __dependencies__ automatically\n- Supports ___lazy___ runtime evaluation by storing js modules as strings\n- __Compiles__ _CoffeeScript_, _LiveScript_, _Handlebars_, _Stylus_, _Less_, and _Jade_ source files\n- __Concatenates__ js modules into a single file\n- Runs js and css code through __linters__ to check for syntax errors\n- __Watches__ for source changes and builds automatically\n- __Serves__ static files from specified directory on specified port\n- __Refreshes__ connected browsers after each change\n- __Inlines__ css `@imports` automatically\n- Supports execution of a ___test___ script after each build\n- Copies __libraries__ from GitHub to your project\n- Copies __assets__ from a local destination to your project\n\n## Installation\n\nTo avoid running **buddy(1)** directly as a global command, and thus avoid versioning problems across different projects, it is highly recommended that you instead install the separate [buddy-cli](https://github.com/popeindustries/buddy-cli) command line interface system-wide:\n\n```bash\n$ npm -g install buddy-cli\n```\n\n...then create a *package.json* file for each project, locally installing **buddy** as a devDependency:\n\n```json\n{\n \"name\": \"myproject\",\n \"description\": \"This is my web project\",\n \"version\": \"0.0.1\",\n \"devDependencies\": {\n \"buddy\": \"0.9.0\"\n }\n}\n```\n```bash\n$ cd path/to/project\n$ npm install\n```\n\n## Usage\n\n```text\nUsage: buddy [options] <command> [path/to/package.json or path/to/buddy.js or path/to/buddy.json]>\n\nCommands:\n\n install [config] install dependencies\n build [config] build js and css sources\n watch [config] watch js and css source files and build changes\n deploy [config] build compressed js and css sources\n ls list all previously created files and directories\n clean remove all previously created files and directories\n\nOptions:\n\n -h, --help output usage information\n -V, --version output the version number\n -c, --compress compress output for production deployment\n -l, --lint check output for syntax and logic errors\n -r, --reload reload all connected live-reload clients on file change during watch\n -s, --serve create a webserver to serve static files during watch\n -t, --test run test command on build completion\n -L, --lazy convert js modules for lazy evaluation\n -v, --verbose print all messages for debugging\n```\n\n### Examples\n\nGenerate `www/main.js` by concatenating and modularizing all dependencies in `src` or `libs/js` referenced in `src/main.js`:\n\n```json\npackage.json\n{\n \"name\": \"myproject\",\n \"description\": \"This is my web project\",\n \"version\": \"0.0.1\",\n \"dependencies\": {\n \"browser-require\": \"git://github.com/popeindustries/browser-require.git\"\n },\n \"devDependencies\": {\n \"buddy\": \"0.9.0\"\n },\n \"buddy\": {\n \"build\": {\n \"js\": {\n \"sources\": [\"src\", \"libs/js\"],\n \"targets\": [\n {\n \"input\": \"src/main.js\",\n \"output\": \"www/main.js\"\n }\n ]\n }\n }\n }\n}\n```\n```bash\n$ buddy build\n```\n\nGenerate `www/main.js` with references to dependencies installed via npm, ignoring Buddy specific packages:\n\n```json\npackage.json\n{\n \"name\": \"myproject\",\n \"description\": \"This is my web project\",\n \"version\": \"0.0.1\",\n \"dependencies\": {\n \"browser-require\": \"git://github.com/popeindustries/browser-require.git\",\n \"underscore\": \"1.4.4\"\n },\n \"devDependencies\": {\n \"buddy\": \"0.9.0\"\n },\n \"buddy\": {\n \"build\": {\n \"js\": {\n \"sources\": [\"src\", \"node_modules\", \"!node_modules/buddy\", \"!node_modules/browser-require\"],\n \"targets\": [\n {\n \"input\": \"src/main.js\",\n \"output\": \"www/main.js\"\n }\n ]\n }\n }\n }\n}\n```\n```bash\n$ buddy build\n```\n\nFirst compile all CoffeeScript files in `libs/src/coffee`, then generate `www/main.js` by concatenating and modularizing all dependencies referenced in 'src/main.js':\n\n```json\npackage.json\n{\n \"name\": \"myproject\",\n \"description\": \"This is my web project\",\n \"version\": \"0.0.1\",\n \"dependencies\": {\n \"browser-require\": \"git://github.com/popeindustries/browser-require.git\"\n },\n \"devDependencies\": {\n \"buddy\": \"0.9.0\"\n },\n \"buddy\": {\n \"build\": {\n \"js\": {\n \"sources\": [\"src\", \"libs/js\", \"libs/src/coffee\"],\n \"targets\": [\n {\n \"input\": \"libs/src/coffee\",\n \"output\": \"libs/js\"\n },\n {\n \"input\": \"src/main.js\",\n \"output\": \"www/main.js\"\n }\n ]\n }\n }\n }\n}\n```\n```bash\n$ buddy build\n```\n\nGenerate `www/main.js` and an additional widget `www/widget.js` using shared sources (avoid duplicating dependencies):\n\n```json\npackage.json\n{\n \"name\": \"myproject\",\n \"description\": \"This is my web project\",\n \"version\": \"0.0.1\",\n \"dependencies\": {\n \"browser-require\": \"git://github.com/popeindustries/browser-require.git\"\n },\n \"devDependencies\": {\n \"buddy\": \"0.9.0\"\n },\n \"buddy\": {\n \"build\": {\n \"js\": {\n \"sources\": [\"src\", \"libs/js\"],\n \"targets\": [\n {\n \"input\": \"src/main.js\",\n \"output\": \"www/main.js\",\n \"targets\": [\n {\n \"input\": \"src/widget.js\",\n \"output\": \"www/widget.js\"\n }\n ]\n }\n ]\n }\n }\n }\n}\n```\n```bash\n$ buddy build\n```\n\nCompile a CoffeeScript project for Node.js, skipping module wrapping and concatenation:\n\n```json\npackage.json\n{\n \"name\": \"myproject\",\n \"description\": \"This is my node project\",\n \"version\": \"0.0.1\",\n \"devDependencies\": {\n \"buddy\": \"0.9.0\"\n },\n \"buddy\": {\n \"build\": {\n \"js\": {\n \"sources\": [\"src/coffee\"],\n \"targets\": [\n {\n \"input\": \"src/coffee\",\n \"output\": \"js\",\n \"modular\": false\n }\n ]\n }\n }\n }\n}\n```\n```bash\n$ buddy build\n```\n\nCopy project boilerplate from a local directory into the project root:\n\n```json\npackage.json\n{\n \"name\": \"myproject\",\n \"description\": \"This is my web project\",\n \"version\": \"0.0.1\",\n \"devDependencies\": {\n \"buddy\": \"0.9.0\"\n },\n \"buddy\": {\n \"dependencies\": {\n \".\": {\n \"sources\": [\"../../boilerplate/project\"]\n }\n }\n }\n```\n```bash\n$ buddy install\n```\n\nDownload js dependencies `browser-require` and `jQuery`, then concatenate and compress to `www/libs.js` for inclusion in html:\n\n```json\npackage.json\n{\n \"name\": \"myproject\",\n \"description\": \"This is my web project\",\n \"version\": \"0.0.1\",\n \"devDependencies\": {\n \"buddy\": \"0.9.0\"\n },\n \"buddy\": {\n \"dependencies\": {\n \"libs/vendor\": {\n \"sources\": [\n \"popeindustries/browser-require\",\n \"jquery@1.9.1\"\n ],\n \"output\": \"www/libs.js\"\n }\n }\n }\n```\n```bash\n$ buddy install\n```\n\nDownload `visionmedia/nib` Stylus sources, specifying a specific directory to be referenced in your builds:\n\n```json\npackage.json\n{\n \"name\": \"myproject\",\n \"description\": \"This is my web project\",\n \"version\": \"0.0.1\",\n \"devDependencies\": {\n \"buddy\": \"0.9.0\"\n },\n \"buddy\": {\n \"dependencies\": {\n \"libs/src/css\": {\n \"sources\": [\n \"visionmedia/nib#lib/nib\"\n ]\n }\n }\n }\n}\n```\n```bash\n$ buddy install\n```\n\nStart a basic web server and refresh the browser (using the Live-Reload browser plugin) after each build triggered by source file changes:\n\n```json\npackage.json\n{\n \"name\": \"myproject\",\n \"description\": \"This is my web project\",\n \"version\": \"0.0.1\",\n \"devDependencies\": {\n \"buddy\": \"0.9.0\"\n },\n \"buddy\": {\n \"settings\": {\n \"server\": {\n \"directory\": \"www\",\n \"port\": 8080\n }\n }\n }\n}\n```\n```bash\n$ buddy watch -rs\n```\n\n### Configuration\n\nComplete annotated `buddy.js` configuration file:\n\n```js\n// Project build configuration.\nexports.build = {\n js: {\n // Directories containing potential js source files for this project.\n sources: ['a/coffeescript/source/directory', 'a/js/source/directory', '!a/js/source/directory/ignored'],\n // One or more js build targets.\n targets: [\n {\n // An entrypoint js (or equivalent) file to be wrapped in a module definition,\n // concatenated with all it's resolved dependencies.\n input: 'a/coffeescript/or/js/file',\n // A destination in which to save the processed input.\n // If a directory is specified, the input file name will be used.\n output: 'a/js/file/or/directory',\n // An alternate destination in which to save the compressed output.\n output_compressed: 'a/js/file/or/directory',\n // Targets can have children.\n // Any sources included in the parent target will NOT be included in the child.\n targets: [\n {\n input: 'a/coffeescript/or/js/file',\n output: 'a/js/file/or/directory'\n }\n ]\n },\n {\n // Files are batch processed when a directory is used as input.\n input: 'a/coffeescript/or/js/directory',\n output: 'a/js/directory',\n // Skips module wrapping (ex: for use in server environments).\n modular: false\n }\n ]\n },\n css: {\n // Directories containing potential css source files for this project.\n sources: ['a/stylus/directory', 'a/less/directory', 'a/css/directory'],\n // One or more css build targets\n targets: [\n {\n // An entrypoint css (or equivalent) file to be processed,\n // concatenated with all it's resolved dependencies.\n input: 'a/stylus/less/or/css/file',\n // A destination in which to save the processed input.\n // If a directory is specified, the input file name will be used.\n output: 'a/css/file/or/directory'\n },\n {\n // Files are batch processed when a directory is used as input, though @import'ed dependencies are still resolved.\n input: 'a/stylus/less/or/css/directory',\n output: 'a/css/directory'\n }\n ]\n }\n}\n\n// Project dependency configuration.\nexports.dependencies = {\n // A destination directory in which to place third-party library dependencies.\n 'a/vendor/directory': {\n // An ordered list of dependencies\n sources: [\n // A github user/repo.\n // Install the 'browser-require' source when using Node-style modules.\n 'popeindustries/browser-require',\n // A named library with or without version (ex: jquery@latest, backbone, backbone@1.0.0).\n // Version identifiers follow the npm semantic versioning rules.\n 'library@version'\n ],\n // Dependencies can be packaged and minified to a destination file\n output: 'a/js/file'\n },\n // A destination directory in which to place source library dependencies.\n 'a/source/directory': {\n sources: [\n // A github user/repo.\n // Will use the 'main' or 'scripts' properties of\n // components.json or package.json to identify the file to install.\n 'username/repo',\n // A github user/repo with specific file or directory locations.\n 'username/repo#a/file/or/directory|another/file/or/directory',\n // A local file or directory to copy and install.\n 'a/file/or/directory'\n ]\n }\n}\n\n// Project settings configuration.\nexports.settings = {\n // Run a command after build\n test: 'command --flags',\n // Configure webserver\n server: {\n // Defaults to project root\n directory: 'a/project/directory',\n // Defaults to 8080\n port: 8000\n },\n // Override the default plugins, and/or include custom plugins.\n plugins: {\n js: {\n // Append one or more js compilers to the default 'coffeescript'.\n compilers: ['a/file', 'another/file'],\n // Change the default 'uglifyjs' compressor to a custom specification.\n compressor: 'a/file',\n // Change the default 'jshint' linter to a custom specification.\n linter: 'a/file',\n // Change the default 'node' module type to 'amd' or a custom specification.\n module: 'amd'\n },\n css: {\n // Append one or more css compilers to the default 'stylus' and 'less'.\n compilers: ['a/file', 'another/file'],\n // Change the default 'cleancss' compressor to a custom specification.\n compressor: 'a/file',\n // Change the default 'csslint' linter to a custom specification.\n linter: 'a/file'\n }\n }\n}\n```\n\n## Concepts\n\n### BUILD\n\n**Project Root**: The directory from which all paths resolve to. Determined by location of the configuration file.\n\n**Sources**: An array of directories from which all referenced files are retrieved from. ***Note:*** A *js* module's id is derived from it's relative path to it's source directory.\n\n**Targets**: Objects that specify the *input* and *output* files or directories for each build. Targets are built in sequence, allowing builds to be chained together. ***Note:*** A *js* target can also have nested child targets, ensuring that dependencies are not duplicated across related builds.\n\n**Target parameters**:\n\n- *input*: file or directory to build. If js (or equivalent) file, all dependencies referenced will be concatenated together for output.\nIf directory, all compileable files will be compiled, wrapped in module definitions (js), and output to individual js/css files.\n\n- *output*: file or directory to output to.\n\n- *targets*: a nested target that prevents the duplication of source code with it's parent target.\n\n- *modular*: a flag to prevent js files from being wrapped with a module definition.\n\n- *output_compressed*: an alternate file or directory to use for compressed output.\n\n### MODULES\n\nEach js file is wrapped in a module declaration based on the file's location. Dependencies are determined by the use of ```require()``` statements:\n\n```javascript\nvar lib = require('./my/lib'); // in current package\nvar SomeClass = require('../someclass'); // in parent package\nvar util = require('utils/util'); // from root package\n\nlib.doSomething();\nvar something = new SomeClass();\nutil.log('hey');\n```\n\nSpecifying a module's public behaviour is achieved by decorating an ```exports``` object:\n\n```javascript\nvar myModuleVar = 'my module';\n\nexports.myModuleMethod = function() {\n return myModuleVar;\n};\n```\n\n...or overwriting the ```exports``` object completely:\n\n```javascript\nfunction MyModule() {\n this.myVar = 'my instance var';\n};\n\nMyModule.prototype.myMethod = function() {\n return this.myVar;\n};\n\nmodule.exports = MyModule;\n```\n\nEach module is provided with a ```module```, ```exports```, and ```require``` reference.\n\nWhen ```require()```-ing a module, keep in mind that the module id is resolved based on the following rules:\n\n * packages begin at the root folder specified in *build > js > sources*:\n```\n'Users/alex/project/src/package/main.js' > 'package/main'\n```\n * uppercase filenames are converted to lowercase module ids:\n```\n'my/package/Class.js' > 'my/package/class'\n```\n\nSee [node.js modules](http://nodejs.org/docs/v0.8.0/api/modules.html) for more info on modules.\n\n***NOTE***: ```require``` boilerplate needs to be included on the page to enable module loading. It's recommended to ```install``` a library like *popeindustries/browser-require*.\n\n### DEPENDENCIES\n\nDependency resources are installed from local locations or remotely from Github.\n\n**Sources**: An array of local or remote resource locations.\n\n- **destination**: each group of sources will be installed to the project relative location specified.\n\n- **identifier**: github ```username/repo``` identifiers are preferred, but it is also possible to use identifiers from the [bower](https://github.com/twitter/bower) package manager: ```'jquery', 'backbone', 'underscore'```\n\n- **versioning**: github sources can specify a version by appending ```@``` and a npm-style symantic version: ```'*', '1.2.3', '1.x', '~1.2.0', '>=1.2.3'```\n\n- **resources**: specific resources can be specified by appending ```#``` and a list of ```|``` separated relative file or directory locations: ```'username/repo#a/file/or/directory|another/file/or/directory'```\n\n**Output**: A file destination to concatenate and compress the source contents. The order of *sources* determines the content order.\n\n<a name=\"a1\"/>\n## Changelog\n\n**0.9.3** - March 11, 2013\n* fixed bug that prevented file changes from refreshing the browser during live-reload `watch`\n\n**0.9.2** - March 5, 2013\n* fixed bug that prevented file dependencies from being reset between builds during `watch`\n\n**0.9.1** - March 5, 2013\n* added support for using [buddy-cli](https://github.com/popeindustries/buddy-cli)\n\n**0.9.0** - February 28, 2013\n* added basic webserver with `-s --serve` flag\n* added support for LiveScript js files\n* added support for precompiling Handlebars templates to .js\n\n**0.8.0** - February 27, 2013\n* moved dependency installer, terminal printing, file watching, and fs utils into separate projects\n* added basic jade html template support\n* css dependencies are now able to be imported multiple times in the same build target\n\n**0.7.3** - February 18, 2013\n* added ignore syntax for build sources: `[\"a/source/directory\", \"!a/source/directory/ignored\"]`\n* added build target property to specify the name and location of compressed output: `output_compressed`\n* fixed an error related to index.js module renaming so that it only affects files in the root of source folders. Avoids multiple `index` modules\n\n**0.7.2** - February 17, 2013\n* build target input files that are not in an existing source location, but in the project path, are added automatically\n* `package/index.js` files are now given a module name of `package` instead of `package/index`\n\n**0.7.1** - February 16, 2013\n* added support for definining configuration in package.json under a `buddy` entry\n* fixed dependency install error for zipballs that don't match their unzipped folder names\n* upgraded dependencies\n\n**0.7.0** - January 7, 2013\n* bye bye CoffeeScript - migrated to js only source\n* upgraded dependencies\n\n**0.6.11** - December 21, 2012\n* fix css comment removal deleting base64 content\n\n**0.6.10** - December 21, 2012\n* updated _Uglify-js_ compressor to 2.0\n\n**0.6.9** - December 14, 2012\n* fixed _watch_ not adding new file during renames\n\n**0.6.8** - December 13, 2012\n* fixed _install_ crash\n* _install_ now overwrites previously downloaded resources\n* properly handle duplicate `@import` rules while inlining\n\n**0.6.7** - December 11, 2012\n* added _--lazy_ option for generating js modules for lazy evaluation; module contents are encoded as strings to be passed to a Function constructor on first require()\n\n**0.6.6** - December 6, 2012\n* added live-reload support for _watch_ command with _--reload_\n* re-enabled linting support\n\n**0.6.5** - December 5, 2012\n* fix for *watch* command firing repeated change events\n* fix for *watch* command not properly building targets on change\n* fix for child target building shared resources\n\n**0.6.4** - December 4, 2012\n* fix for _--test_ not displaying both stdout and stderr\n* added wrapping of batch files in module definitions if _options.modular_ is not false\n* fix for building targets that contain no source\n\n**0.6.3** - December 4, 2012\n* fix for _watch_ command attempting to watch a source that doesn't exist\n* added support for default json config file type\n\n**0.6.2** - December 4, 2012\n* fix for css _@import_ inlining\n\n**0.6.1** - December 3, 2012\n* added _--test_ to watch command\n\n**0.6.0** - December 3, 2012\n* complete rewrite for async file operations\n* added _--test_ flag for executing a command after build\n* added _--verbose_ flag for outputting detailed notifications during build\n* added _ls_ command to list all generated files\n* added inlining of '@import' rules for all css source types\n* simplified dependency resource parsing on install; only parse 'main' field in component.json/package.json\n\n**0.5.4** - November 23, 2012\n* regression fix for _clean_ command\n* improved _.buddy-filelog_ force clean\n* improved notifications for _install_ and *clean* commands\n\n**0.5.3** - November 23, 2012\n* refactored _install_ command behaviour; no longer uses git operations, changed syntax for specifying version ('@') and resources ('#'), added ability to list several resources __[breaking change]__\n* _.buddy-filelog_ now stores relative paths for compatibility on different systems\n* file deletions limited to resources under the project root\n\n**0.5.2** - Novemver 20, 2012\n* added _watch_ command; handle add, remove, and change of source files\n\n**0.5.1** - Novemver 14, 2012\n* added _clean_ command to remove all generated files\n* added hidden _.buddy-filelog_ file for tracking files changes between sessions\n* fix for false-negative module wrapping test\n\n**0.5.0** - November 13, 2012\n* _compile_ command renamed to *build* __[breaking change]__\n* changed module naming for compatibility with recent versions of Node.js (camel case no longer converted to underscores) __[breaking change]__\n* changed configuration file type to 'js' from 'json'; added _dependencies_ and _settings_ __[breaking change]__\n* changed configuration _target_ parameters to _input/output_ from _in/out_ __[breaking change]__\n* changed configuration _target_ parameter to _modular_ from _nodejs_ __[breaking change]__\n* concatenated js modules no longer self-booting; need to ```require('main');``` manually __[breaking change]__\n* _require_ boilerplate no longer included in generated source; install _popeindustries/browser-require_ or equivalent __[breaking change]__\n* removed _watch_ command (temporarily) __[breaking change]__\n* added _install_ command and project dependency management\n* added plugin support for compilers, compressors, linters, and modules; added support for custom plugins\n* added code linting\n* all errors now throw\n* complete code base refactor\n\n## License\n\n(The MIT License)\n\nCopyright (c) 2011 Pope-Industries &lt;alex@pope-industries.com&gt;\n\nPermission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the 'Software'), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.\n\nTHE 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.",
"license": "MIT"
}

0 comments on commit 8b13869

Please sign in to comment.
Something went wrong with that request. Please try again.