From 70187699aa467980c7dd831851c97d5b447509e9 Mon Sep 17 00:00:00 2001 From: Beau Simensen Date: Wed, 18 Jan 2012 09:04:55 -0800 Subject: [PATCH 1/6] vendor bins documentation --- doc/faqs/vendor-bins.md | 72 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 72 insertions(+) create mode 100644 doc/faqs/vendor-bins.md diff --git a/doc/faqs/vendor-bins.md b/doc/faqs/vendor-bins.md new file mode 100644 index 000000000..fd2fdf7ab --- /dev/null +++ b/doc/faqs/vendor-bins.md @@ -0,0 +1,72 @@ +# bin and vendor/bin + +## What is a bin? + +Any runnable code that a Composer package would like to pass along +to a user who installs the package should be listed as a bin. + +If a package contains other runnable code that is not needed by the +user (like build or compile scripts) that code need not be listed +as a bin. + + +## How is it defined? + +It is defined by adding the `bin` key to a project's `composer.json`. +It is specified as an array of files so multiple bins can be added +for any given project. + +~~~json +{ + "bin": ["bin/my-script", "bin/my-other-script"] +} +~~~ + + +## What does defining a bin in composer.json do? + +It instructs Composer to install the package's bins to `vendor/bin` +for any project that **depends** on that project. + +This is a convenient way to expose useful runnable code that would +otherwise be hidden deep in the `vendor/` directory. + + +## What happens when Composer is run on a composer.json that defines bins? + +For the bins that a package defines directly, nothing happens. + + +## What happens when Composer is run on a composer.json that has dependencies with bins listed? + +Composer looks for the bins defined in all of the dependencies. A +symlink is created from each dependency's bins to `vendor/bin`. + +Say package `my-vendor/project-a` has bins setup like this: + +~~~json +{ + "name": "my-vendor/project-a", + "bin": ["bin/project-a-bin"] +} +~~~ + +Running `composer install` for this `composer.json` will not do +anything with `bin/project-a-bin`. + +Say project `my-vendor/project-b` has requirements setup like this: + +~~~json +{ + "name": "my-vendor/project-b", + "requires": { + "my-vendor/project-a": "*" + } +} +~~~ + +Running `composer install` for this `composer.json` will look at +all of project-b's dependencies and install them to `vendor/bin`. + +In this case, Composer will create a symlink from +`vendor/my-vendor/project-a/bin/project-a-bin` to `vendor/bin/project-a`. \ No newline at end of file From d21fca24a6ef9f3e5459c6d49a3859719d2f2c67 Mon Sep 17 00:00:00 2001 From: Beau Simensen Date: Wed, 18 Jan 2012 09:17:41 -0800 Subject: [PATCH 2/6] Forgot a bit. :-/ --- doc/faqs/vendor-bins.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/faqs/vendor-bins.md b/doc/faqs/vendor-bins.md index fd2fdf7ab..b6cf8dfed 100644 --- a/doc/faqs/vendor-bins.md +++ b/doc/faqs/vendor-bins.md @@ -69,4 +69,4 @@ Running `composer install` for this `composer.json` will look at all of project-b's dependencies and install them to `vendor/bin`. In this case, Composer will create a symlink from -`vendor/my-vendor/project-a/bin/project-a-bin` to `vendor/bin/project-a`. \ No newline at end of file +`vendor/my-vendor/project-a/bin/project-a-bin` to `vendor/bin/project-a-bin`. \ No newline at end of file From 8507bcf2981a9ccdd46d7acac2e61626025c9510 Mon Sep 17 00:00:00 2001 From: Beau Simensen Date: Wed, 18 Jan 2012 09:59:04 -0800 Subject: [PATCH 3/6] Updates per @stof --- doc/faqs/vendor-bins.md | 23 +++++++++++++++-------- 1 file changed, 15 insertions(+), 8 deletions(-) diff --git a/doc/faqs/vendor-bins.md b/doc/faqs/vendor-bins.md index b6cf8dfed..f904f54c0 100644 --- a/doc/faqs/vendor-bins.md +++ b/doc/faqs/vendor-bins.md @@ -6,7 +6,7 @@ Any runnable code that a Composer package would like to pass along to a user who installs the package should be listed as a bin. If a package contains other runnable code that is not needed by the -user (like build or compile scripts) that code need not be listed +user (like build or compile scripts) that code should not be listed as a bin. @@ -16,11 +16,11 @@ It is defined by adding the `bin` key to a project's `composer.json`. It is specified as an array of files so multiple bins can be added for any given project. -~~~json +```json { "bin": ["bin/my-script", "bin/my-other-script"] } -~~~ +``` ## What does defining a bin in composer.json do? @@ -44,29 +44,36 @@ symlink is created from each dependency's bins to `vendor/bin`. Say package `my-vendor/project-a` has bins setup like this: -~~~json +```json { "name": "my-vendor/project-a", "bin": ["bin/project-a-bin"] } -~~~ +``` Running `composer install` for this `composer.json` will not do anything with `bin/project-a-bin`. Say project `my-vendor/project-b` has requirements setup like this: -~~~json +```json { "name": "my-vendor/project-b", "requires": { "my-vendor/project-a": "*" } } -~~~ +``` Running `composer install` for this `composer.json` will look at all of project-b's dependencies and install them to `vendor/bin`. In this case, Composer will create a symlink from -`vendor/my-vendor/project-a/bin/project-a-bin` to `vendor/bin/project-a-bin`. \ No newline at end of file +`vendor/my-vendor/project-a/bin/project-a-bin` to `vendor/bin/project-a-bin`. + + +## What about Windows and .bat files? + +Composer will automatically create `.bat` files for bins installed in a +Windows environment. Package maintainers should not list self managed +`.bat` files as bins. \ No newline at end of file From 4748e1dacb7fdd9fccdbcb5c7b43a4fb548f29ea Mon Sep 17 00:00:00 2001 From: Beau Simensen Date: Wed, 18 Jan 2012 12:11:16 -0800 Subject: [PATCH 4/6] Tweaks on Windows section of the doc --- doc/faqs/vendor-bins.md | 19 ++++++++++++++----- 1 file changed, 14 insertions(+), 5 deletions(-) diff --git a/doc/faqs/vendor-bins.md b/doc/faqs/vendor-bins.md index f904f54c0..15be0f3f0 100644 --- a/doc/faqs/vendor-bins.md +++ b/doc/faqs/vendor-bins.md @@ -68,12 +68,21 @@ Say project `my-vendor/project-b` has requirements setup like this: Running `composer install` for this `composer.json` will look at all of project-b's dependencies and install them to `vendor/bin`. -In this case, Composer will create a symlink from -`vendor/my-vendor/project-a/bin/project-a-bin` to `vendor/bin/project-a-bin`. +In this case, Composer will make `vendor/my-vendor/project-a/bin/project-a-bin` +available as `vendor/bin/project-a-bin`. On a Unix-like platform +this is accomplished by creating a symlink. ## What about Windows and .bat files? -Composer will automatically create `.bat` files for bins installed in a -Windows environment. Package maintainers should not list self managed -`.bat` files as bins. \ No newline at end of file +Packages managed entirely by Composer do not *need* to contain any +`.bat` files for Windows compatibility. Composer handles installation +of bins in a special way when run in a Windows environment: + + * A `.bat` files is generated automatically to reference the bin + * A Unix-style proxy file with the same name as the bin is generated + automatically (useful for Cygwin or Git Bash) + +Packages that need to support workflows that may not include Composer +are welcome to maintain custom `.bat` files. In this case, the package +should **not** list the `.bat` file as a bin as it is not needed. From 1b908d4f8073a0bdf9512dc97aba92b71d01ae8d Mon Sep 17 00:00:00 2001 From: Beau Simensen Date: Wed, 18 Jan 2012 22:54:59 -0800 Subject: [PATCH 5/6] Changing vendor bin configuration --- doc/faqs/vendor-bins.md | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/doc/faqs/vendor-bins.md b/doc/faqs/vendor-bins.md index 15be0f3f0..990e2b73d 100644 --- a/doc/faqs/vendor-bins.md +++ b/doc/faqs/vendor-bins.md @@ -86,3 +86,25 @@ of bins in a special way when run in a Windows environment: Packages that need to support workflows that may not include Composer are welcome to maintain custom `.bat` files. In this case, the package should **not** list the `.bat` file as a bin as it is not needed. + + +## Can vendor bins be installed somewhere other than vendor/bin? + +Yes, there are two ways that an alternate vendor bin location can be specified. + + * Setting the `vendor-dir` configuration setting in `composer.json` + * Setting the environment variable `COMPOSER_VENDOR_DIR` + +An example of the former looks like this: + +```json +{ + "config": { + "vendor-dir": "scripts" + } +} +``` + +Running `composer install` for this `composer.json` will result in +all of the vendor bins being installed in `scripts/` instead of +`vendor/bin/`. \ No newline at end of file From c1d1482393b6aa64074ecdaa748397a9aa7d12e7 Mon Sep 17 00:00:00 2001 From: Beau Simensen Date: Thu, 19 Jan 2012 20:57:57 -0800 Subject: [PATCH 6/6] This was nowhere near accurate before. Must have been thinking about the wrong then when I wrote this. --- doc/faqs/vendor-bins.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/faqs/vendor-bins.md b/doc/faqs/vendor-bins.md index 990e2b73d..1c8f6a85d 100644 --- a/doc/faqs/vendor-bins.md +++ b/doc/faqs/vendor-bins.md @@ -92,15 +92,15 @@ should **not** list the `.bat` file as a bin as it is not needed. Yes, there are two ways that an alternate vendor bin location can be specified. - * Setting the `vendor-dir` configuration setting in `composer.json` - * Setting the environment variable `COMPOSER_VENDOR_DIR` + * Setting the `bin-dir` configuration setting in `composer.json` + * Setting the environment variable `COMPOSER_BIN_DIR` An example of the former looks like this: ```json { "config": { - "vendor-dir": "scripts" + "bin-dir": "scripts" } } ```