Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Browse files

release 1.1.0

  • Loading branch information...
commit bbacca1e847593bb88d40d096f45e17ecbe2e3fa 1 parent 66a47af
@popeindustries authored
Showing with 7 additions and 4 deletions.
  1. +3 −0  CHANGELOG.md
  2. +2 −2 README.md
  3. +2 −2 package.json
View
3  CHANGELOG.md
@@ -1,5 +1,8 @@
# Changelog
+**1.1.0** - Feb 17, 2014
+* improved handling of nested node_modules dependencies resolution by always converting relative `require` calls to absolute
+
**1.0.1** - Jan 10, 2014
* updated *browser-require* dependency to better handle root module resolution
View
4 README.md
@@ -4,14 +4,14 @@
**buddy(1)** is a build tool for js/css/html projects. It helps you manage third-party dependencies (optional add-on), compiles source code from higher order js/css/html languages (CoffeeScript/Handlebars/Dust/Stylus/Less/Jade/Twig), 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.
-**Current version:** 1.0.1 *[See [Change Log](https://github.com/popeindustries/buddy/blob/master/CHANGELOG.md) for more details]*
+**Current version:** 1.1.0 *[See [Change Log](https://github.com/popeindustries/buddy/blob/master/CHANGELOG.md) for more details]*
## Features
- Allows you to write js __modules__ without the module boilerplate (similar to Node.js)
- Resolves js module __dependencies__ automatically
- Supports efficient ___lazy___ runtime evaluation by storing js modules as strings
-- Resolves all relative dependencies on __deploy__
+- Resolves all relative dependencies
- __Compiles__ _CoffeeScript_, _Handlebars_, _Dust_, _Stylus_, _Less_, _Twig_, and _Jade_ source files
- __Concatenates__ js modules into a single file
- Runs js and css code through __linters__ to check for syntax errors
View
4 package.json
@@ -1,7 +1,7 @@
{
"name": "buddy",
"description": "A build tool for js/css/html projects.",
- "version": "1.0.1",
+ "version": "1.1.0",
"author": "popeindustries <alex@pope-industries.com>",
"keywords": ["build", "buildtool", "modules", "javascript", "coffeescript", "css", "styus", "less", "handlebars", "dust", "jade", "twig"],
"dependencies": {
@@ -43,6 +43,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 (optional add-on), compiles source code from higher order js/css/html languages (CoffeeScript/Handlebars/Dust/Stylus/Less/Jade/Twig), 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:** 1.0.0 *[See [Change Log](https://github.com/popeindustries/buddy/blob/master/CHANGELOG.md) 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 efficient ___lazy___ runtime evaluation by storing js modules as strings\n- Resolves all relative dependencies on __deploy__\n- __Compiles__ _CoffeeScript_, _Handlebars_, _Dust_, _Stylus_, _Less_, _Twig_, 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- [Add-on] __Serves__ static files from specified directory on specified port\n- [Add-on] __Refreshes__ connected browsers after each change\n- __Inlines__ css `@imports` automatically\n- __Inlines__ html `<script>` and `<link>` tags when flagged with `inline` attributes\n- __Inlines__ json content with `require(\"path/to/my.json\")`\n- Supports execution of a ___script___ after each build\n- Supports execution of ___hook___ scripts `afterEach` file is processed, and `before` and `after` a target is built\n- [Add-on] Copies __packages__ from GitHub to your project\n- [Add-on] 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...run `buddy init` or manually 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.1.0\",\n \"devDependencies\": {\n \"buddy\": \"1.0.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 || path/to/buddy.js || path/to/buddy.json]\n\nCommands:\n\n init set up a basic buddy project\n install [config] install dependencies [ADD-ON buddy-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 [ADD-ON buddy-server]\n -s, --serve create a webserver to serve static files during watch [ADD-ON buddy-server]\n -S, --script run script 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\n*See [buddy-dependencies](https://github.com/popeindustries/buddy-dependencies) for `install` command 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.1.0\",\n \"dependencies\": {\n \"simple-browser-require\": \"*\"\n },\n \"devDependencies\": {\n \"buddy\": \"1.0.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:\n\n```json\npackage.json\n{\n \"name\": \"myproject\",\n \"description\": \"This is my web project\",\n \"version\": \"0.1.0\",\n \"dependencies\": {\n \"simple-browser-require\": \"*\"\n \"underscore\": \"1.4.4\"\n },\n \"devDependencies\": {\n \"buddy\": \"1.0.0\"\n },\n \"buddy\": {\n \"build\": {\n \"js\": {\n \"sources\": [\"src\"],\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.1.0\",\n \"dependencies\": {\n \"simple-browser-require\": \"*\"\n },\n \"devDependencies\": {\n \"buddy\": \"1.0.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.1.0\",\n \"dependencies\": {\n \"simple-browser-require\": \"*\"\n },\n \"devDependencies\": {\n \"buddy\": \"1.0.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 server project\",\n \"version\": \"0.1.0\",\n \"devDependencies\": {\n \"buddy\": \"1.0.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\nAlias a custom build of **jquery**:\n\n```json\npackage.json\n{\n \"name\": \"myproject\",\n \"description\": \"This is my server project\",\n \"version\": \"0.1.0\",\n \"devDependencies\": {\n \"buddy\": \"1.0.0\"\n },\n \"buddy\": {\n \"build\": {\n \"js\": {\n \"sources\": [\"src\"],\n \"targets\": [\n {\n \"input\": \"src/main.js\",\n \"output\": \"www/main.js\",\n \"alias\": {\n \"jquery\": \"./lib/js/jquery-custom-2.0.js\"\n }\n }\n ]\n }\n }\n }\n}\n```\n```javascript\nvar jquery = require('jquery');\n```\n\nModify the file output with an `afterEach` hook:\n\n```json\npackage.json\n{\n \"name\": \"myproject\",\n \"description\": \"This is my server project\",\n \"version\": \"0.1.0\",\n \"devDependencies\": {\n \"buddy\": \"1.0.0\"\n },\n \"buddy\": {\n \"build\": {\n \"js\": {\n \"sources\": [\"src\"],\n \"targets\": [\n {\n \"input\": \"src/main.js\",\n \"output\": \"www/main.js\",\n \"afterEach\": \"context.content = require('fs').readFileSync(require('path').resolve('./scripts/header.js'), 'utf8') + context.content; callback(null);\"\n }\n ]\n }\n }\n }\n}\n```\n```bash\n$ buddy build\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 [via add-on [buddy-server](https://github.com/popeindustries/buddy-server)]:\n\n```json\npackage.json\n{\n \"name\": \"myproject\",\n \"description\": \"This is my web project\",\n \"version\": \"0.1.0\",\n \"devDependencies\": {\n \"buddy\": \"1.0.0\",\n \"buddy-server\": \"0.4.x\"\n },\n \"buddy\": {\n \"build\": {\n \"js\": {\n \"targets\": [\n {\n \"input\": \"main.js\",\n \"output\": \"www\"\n }\n ]\n },\n \"html\": {\n \"targets\": [\n {\n \"input\": \"index.html\",\n \"output\": \"www\"\n }\n ]\n }\n },\n \"server\": {\n \"directory\": \"www\",\n \"port\": 8080\n }\n }\n}\n```\n```bash\n$ buddy watch --reload --serve\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 ('node_modules' are added by default).\n sources: ['a/js/source/directory', 'another/js/source/directory'],\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/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 // A script to run before a target is built.\n before: 'console.log(context); callback();',\n // A script to run after a target is built.\n after: './hooks/after.js',\n // A script to run after each output file is ready to be written to disk.\n afterEach: 'context.content = \"foo\"; callback();',\n // A flag indicating that require.js boilerplate be added to the output file\n boilerplate: true,\n // A flag indicating that the entry point module should require itself (bootstrap)\n bootstrap: true,\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/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/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/css/directory', 'another/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/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,\n // though @import'ed dependencies are still resolved and inlined.\n input: 'a/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 // Alternatively, a destination file for packaging/minification\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' 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// Run a command after build\nexports.script = 'command --flags';\n\n// Configure webserver\nexports.server = {\n // Defaults to project root\n directory: 'a/project/directory',\n // Defaults to 8080\n port: 8000\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- **before**, **after**, **afterEach**: hooks for modifying the build process (see [hooks](https://github.com/popeindustries/buddy/#hooks))\n\n- **boilerplate**: a flag to specify inclusion of [browser-require](https://github.com/popeindustries/browser-require) source code in the output file\n\n- **bootstrap**: a flag to specify that the entry-point module be automatically require'd to force application startup\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\nvar module = require('module'); // from node_modules\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 * ids are case-sensitive:\n ```\n 'package/MyClass.js' > 'package/MyClass'\n ```\n\nSee [node.js modules](http://nodejs.org/api/modules.html) for more info on modules.\n\n***NOTE***: ```require``` boilerplate needs to be included in the browser to enable module loading. It's recommended to ```install``` a library like [browser-require](https://github.com/popeindustries/browser-require) (npm: simple-browser-require), or set the `boilerplate` flag to have it included automatically.\n\n### HOOKS\n\nIt is possible to intervene in the build process through the use of *hooks*. Hooks are assigned to specific targets and defined in the target configuration. There are three types available:\n\n- **before**: executed before a *target* is built\n\n- **after**: executed after a *target* is built\n\n- **afterEach**: executed after an output *file* is processed, but before it is written to disk\n\nHooks can be written as inline JavaScript, or loaded from a file if a path is specified:\n\n```json\n{\n ...\n \"targets\": [\n {\n \"input\": \"somefile.js\",\n \"output\": \"somedir\",\n \"before\": \"console.log('before hook'); callback(null);\",\n \"after\": \"path/to/afterHook.js\"\n }\n ]\n ...\n}\n```\n\nAll hooks are passed the following arguments:\n\n- **context**: the `target` (before and after) or `file` (afterEach) instance\n\n- **options**: the runtime options used to execute buddy (`compress`, `lazy`, `reload`, `watch`, `deploy`, etc)\n\n- **callback**: a callback function that accepts an optional `error`. **MUST** be called in order to return control back to the program.\n\n### ALIASES\n\nSpecifying aliases allow you to override the default behaviour for automatically resolving module ids. Aliases are defined in the target configuration:\n\n```json\n{\n ...\n \"targets\": [\n {\n \"input\": \"somefile.js\",\n \"output\": \"somedir\",\n \"alias\": {\n \"jquery\": \"./lib/js/jquery-custom-2.0.js\",\n \"dust\": \"./node_modules/dustjs-linkedin/dist/dust-core-1.2.3.js\"\n }\n }\n ]\n ...\n}\n```\n```javascript\nvar jquery = require('jquery')\n , dust = require('dust');\n```\n\n### DEPENDENCIES\n\n*See [buddy-dependencies](https://github.com/popeindustries/buddy-dependencies).*\n\n## License\n\n(The MIT License)\n\nCopyright (c) 2011-2014 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.\n",
+ "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 (optional add-on), compiles source code from higher order js/css/html languages (CoffeeScript/Handlebars/Dust/Stylus/Less/Jade/Twig), 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:** 1.1.0 *[See [Change Log](https://github.com/popeindustries/buddy/blob/master/CHANGELOG.md) 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 efficient ___lazy___ runtime evaluation by storing js modules as strings\n- Resolves all relative dependencies\n- __Compiles__ _CoffeeScript_, _Handlebars_, _Dust_, _Stylus_, _Less_, _Twig_, 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- [Add-on] __Serves__ static files from specified directory on specified port\n- [Add-on] __Refreshes__ connected browsers after each change\n- __Inlines__ css `@imports` automatically\n- __Inlines__ html `<script>` and `<link>` tags when flagged with `inline` attributes\n- __Inlines__ json content with `require(\"path/to/my.json\")`\n- Supports execution of a ___script___ after each build\n- Supports execution of ___hook___ scripts `afterEach` file is processed, and `before` and `after` a target is built\n- [Add-on] Copies __packages__ from GitHub to your project\n- [Add-on] 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...run `buddy init` or manually 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.1.0\",\n \"devDependencies\": {\n \"buddy\": \"1.0.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 || path/to/buddy.js || path/to/buddy.json]\n\nCommands:\n\n init set up a basic buddy project\n install [config] install dependencies [ADD-ON buddy-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 [ADD-ON buddy-server]\n -s, --serve create a webserver to serve static files during watch [ADD-ON buddy-server]\n -S, --script run script 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\n*See [buddy-dependencies](https://github.com/popeindustries/buddy-dependencies) for `install` command 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.1.0\",\n \"dependencies\": {\n \"simple-browser-require\": \"*\"\n },\n \"devDependencies\": {\n \"buddy\": \"1.0.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:\n\n```json\npackage.json\n{\n \"name\": \"myproject\",\n \"description\": \"This is my web project\",\n \"version\": \"0.1.0\",\n \"dependencies\": {\n \"simple-browser-require\": \"*\"\n \"underscore\": \"1.4.4\"\n },\n \"devDependencies\": {\n \"buddy\": \"1.0.0\"\n },\n \"buddy\": {\n \"build\": {\n \"js\": {\n \"sources\": [\"src\"],\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.1.0\",\n \"dependencies\": {\n \"simple-browser-require\": \"*\"\n },\n \"devDependencies\": {\n \"buddy\": \"1.0.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.1.0\",\n \"dependencies\": {\n \"simple-browser-require\": \"*\"\n },\n \"devDependencies\": {\n \"buddy\": \"1.0.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 server project\",\n \"version\": \"0.1.0\",\n \"devDependencies\": {\n \"buddy\": \"1.0.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\nAlias a custom build of **jquery**:\n\n```json\npackage.json\n{\n \"name\": \"myproject\",\n \"description\": \"This is my server project\",\n \"version\": \"0.1.0\",\n \"devDependencies\": {\n \"buddy\": \"1.0.0\"\n },\n \"buddy\": {\n \"build\": {\n \"js\": {\n \"sources\": [\"src\"],\n \"targets\": [\n {\n \"input\": \"src/main.js\",\n \"output\": \"www/main.js\",\n \"alias\": {\n \"jquery\": \"./lib/js/jquery-custom-2.0.js\"\n }\n }\n ]\n }\n }\n }\n}\n```\n```javascript\nvar jquery = require('jquery');\n```\n\nModify the file output with an `afterEach` hook:\n\n```json\npackage.json\n{\n \"name\": \"myproject\",\n \"description\": \"This is my server project\",\n \"version\": \"0.1.0\",\n \"devDependencies\": {\n \"buddy\": \"1.0.0\"\n },\n \"buddy\": {\n \"build\": {\n \"js\": {\n \"sources\": [\"src\"],\n \"targets\": [\n {\n \"input\": \"src/main.js\",\n \"output\": \"www/main.js\",\n \"afterEach\": \"context.content = require('fs').readFileSync(require('path').resolve('./scripts/header.js'), 'utf8') + context.content; callback(null);\"\n }\n ]\n }\n }\n }\n}\n```\n```bash\n$ buddy build\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 [via add-on [buddy-server](https://github.com/popeindustries/buddy-server)]:\n\n```json\npackage.json\n{\n \"name\": \"myproject\",\n \"description\": \"This is my web project\",\n \"version\": \"0.1.0\",\n \"devDependencies\": {\n \"buddy\": \"1.0.0\",\n \"buddy-server\": \"0.4.x\"\n },\n \"buddy\": {\n \"build\": {\n \"js\": {\n \"targets\": [\n {\n \"input\": \"main.js\",\n \"output\": \"www\"\n }\n ]\n },\n \"html\": {\n \"targets\": [\n {\n \"input\": \"index.html\",\n \"output\": \"www\"\n }\n ]\n }\n },\n \"server\": {\n \"directory\": \"www\",\n \"port\": 8080\n }\n }\n}\n```\n```bash\n$ buddy watch --reload --serve\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 ('node_modules' are added by default).\n sources: ['a/js/source/directory', 'another/js/source/directory'],\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/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 // A script to run before a target is built.\n before: 'console.log(context); callback();',\n // A script to run after a target is built.\n after: './hooks/after.js',\n // A script to run after each output file is ready to be written to disk.\n afterEach: 'context.content = \"foo\"; callback();',\n // A flag indicating that require.js boilerplate be added to the output file\n boilerplate: true,\n // A flag indicating that the entry point module should require itself (bootstrap)\n bootstrap: true,\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/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/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/css/directory', 'another/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/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,\n // though @import'ed dependencies are still resolved and inlined.\n input: 'a/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 // Alternatively, a destination file for packaging/minification\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' 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// Run a command after build\nexports.script = 'command --flags';\n\n// Configure webserver\nexports.server = {\n // Defaults to project root\n directory: 'a/project/directory',\n // Defaults to 8080\n port: 8000\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- **before**, **after**, **afterEach**: hooks for modifying the build process (see [hooks](https://github.com/popeindustries/buddy/#hooks))\n\n- **boilerplate**: a flag to specify inclusion of [browser-require](https://github.com/popeindustries/browser-require) source code in the output file\n\n- **bootstrap**: a flag to specify that the entry-point module be automatically require'd to force application startup\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\nvar module = require('module'); // from node_modules\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 * ids are case-sensitive:\n ```\n 'package/MyClass.js' > 'package/MyClass'\n ```\n\nSee [node.js modules](http://nodejs.org/api/modules.html) for more info on modules.\n\n***NOTE***: ```require``` boilerplate needs to be included in the browser to enable module loading. It's recommended to ```install``` a library like [browser-require](https://github.com/popeindustries/browser-require) (npm: simple-browser-require), or set the `boilerplate` flag to have it included automatically.\n\n### HOOKS\n\nIt is possible to intervene in the build process through the use of *hooks*. Hooks are assigned to specific targets and defined in the target configuration. There are three types available:\n\n- **before**: executed before a *target* is built\n\n- **after**: executed after a *target* is built\n\n- **afterEach**: executed after an output *file* is processed, but before it is written to disk\n\nHooks can be written as inline JavaScript, or loaded from a file if a path is specified:\n\n```json\n{\n ...\n \"targets\": [\n {\n \"input\": \"somefile.js\",\n \"output\": \"somedir\",\n \"before\": \"console.log('before hook'); callback(null);\",\n \"after\": \"path/to/afterHook.js\"\n }\n ]\n ...\n}\n```\n\nAll hooks are passed the following arguments:\n\n- **context**: the `target` (before and after) or `file` (afterEach) instance\n\n- **options**: the runtime options used to execute buddy (`compress`, `lazy`, `reload`, `watch`, `deploy`, etc)\n\n- **callback**: a callback function that accepts an optional `error`. **MUST** be called in order to return control back to the program.\n\n### ALIASES\n\nSpecifying aliases allow you to override the default behaviour for automatically resolving module ids. Aliases are defined in the target configuration:\n\n```json\n{\n ...\n \"targets\": [\n {\n \"input\": \"somefile.js\",\n \"output\": \"somedir\",\n \"alias\": {\n \"jquery\": \"./lib/js/jquery-custom-2.0.js\",\n \"dust\": \"./node_modules/dustjs-linkedin/dist/dust-core-1.2.3.js\"\n }\n }\n ]\n ...\n}\n```\n```javascript\nvar jquery = require('jquery')\n , dust = require('dust');\n```\n\n### DEPENDENCIES\n\n*See [buddy-dependencies](https://github.com/popeindustries/buddy-dependencies).*\n\n## License\n\n(The MIT License)\n\nCopyright (c) 2011-2014 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.\n",
"license": "MIT"
}
Please sign in to comment.
Something went wrong with that request. Please try again.