From 1aa58d424324959b331577211b699c6181ae7331 Mon Sep 17 00:00:00 2001
From: Mikey O'Toole <mikey@mjco.uk>
Date: Thu, 4 Oct 2018 11:13:53 +0100
Subject: [PATCH] Clarifications to buildkit path docs - added "real world"
example of .bash_profile/.profile config.
---
docs/tools/buildkit.md | 37 ++++++++++++++++++++++++-------------
1 file changed, 24 insertions(+), 13 deletions(-)
diff --git a/docs/tools/buildkit.md b/docs/tools/buildkit.md
index 927e43f7..b19a24d6 100644
--- a/docs/tools/buildkit.md
+++ b/docs/tools/buildkit.md
@@ -22,7 +22,7 @@ curl -Ls https://civicrm.org/get-buildkit.sh | bash -s -- --full --dir ~/buildki
* When executing the above command, you should *not* run as `root`, as it *will* cause failures. However, you *should* have `sudo` permissions.
* The `--full` option is *very opinionated*; it specifically installs `php`, `apache`, and `mysql` (rather than `hhvm`, `nginx`, `lighttpd`, or `percona`). If you try to mix `--full` with alternative systems, then expect conflicts.
* If you use the Ubuntu feature for "encrypted home directories", then don't put buildkit in `~/buildkit`. Consider `/opt/buildkit`, `/srv/buildkit`, or some other location that remains available during reboot.
-
+
After running the above command, then proceed to the [post-installation configuration](#config).
### Vagrant
@@ -111,20 +111,31 @@ If you want to ensure that the buildkit CLI tools are always available, then:
1. Determine the location of your shell configuration file. This is usually `~/.bash_profile`, or `~/.profile`. You may have to create one.
1. At the end of the file, add `PATH="/path/to/buildkit/bin:$PATH"`.
-1. If you are on a mac, you can close and re-open your terminal. On other systems, you will need to log-out or source your `~/.profile`
+1. If you are on a mac, you can close and re-open your terminal. On other systems, you will need to log-out or source your `~/.profile` with `source ~/.profile`.
1. Enter the command `civibuild -h`. This should display a help screen for civibuild. If you get 'command not found', then check your path and retry the steps above.
+
+!!! tip
+ For most installations with the standard buildkit install script the following lines in your shell configuration file will work.
+ ``` bash
+ # Add ~/buildkit/bin to path if it exists.
+ if [ -d "$HOME/buildkit/bin" ] ; then
+ PATH="$HOME/buildkit/bin:$PATH"
+ fi
+ ```
+
+
!!! note "More on bash `$PATH`"
On most OS's `~/.profile` is run only once when you login to your desktop. There is a distinction between "login shells" and "non-login shells" which you don't really need to worry about, except that the distinction is the reason that you should set your `$PATH` in your `~/.profile` and not your `~/.bashrc`.
-
+
When you open a terminal (non-login), `~/.bashrc` will be executed. The common idiom for changing the path is to add to the `$PATH`, not rebuild it, so if you update your `$PATH` every time a shell is invoked, your `$PATH` will continually grow. This is not really a problem, but you might want to be aware of this.
-
+
If you are on a mac, the situation is reversed. That is, your `$PATH` is not set when you login into your desktop and every terminal you open is a "login shell" and `~/.profile` will be executed every time.
-
+
You do not need to run `export PATH=...` because your system certainly has already exported the `$PATH` variable and you only need to update it.
-
- References:
+
+ References:
* <https://unix.stackexchange.com/a/26059>
* <https://superuser.com/questions/244964/mac-os-x-bashrc-not-working#244990>
@@ -149,30 +160,30 @@ If you want to ensure that the buildkit CLI tools are always available, then:
### Configuring `amp` {:#amp-config}
-Buildkit provides a tool called `amp` which [civibuild](/tools/civibuild.md) uses when it needs to set up a new site. Before you can use `civibuild`, need to configure `amp` by telling it a bit about your system (e.g. what webserver you're using).
+Buildkit provides a tool called `amp` which [civibuild](/tools/civibuild.md) uses when it needs to set up a new site. Before you can use `civibuild`, need to configure `amp` by telling it a bit about your system (e.g. what webserver you're using).
1. Run the interactive configuration tool.
```
$ amp config
```
-
+
!!! tip "tips"
* Run this as a non-`root` user who has `sudo` permission. This will ensure that new files are owned by a regular user, and (if necessary) it enables `civibuild` to restart your webserver and edit `/etc/hosts`.
* Pay close attention to any instructions given in the output of this command.
* To check which version of apache you have, run `apachectl -v`.
-
+
!!! caution
- We strongly recommend using Apache as your webserver because support for nginx is limited.
+ We strongly recommend using Apache as your webserver because support for nginx is limited.
1. Test amp's configuration
```
$ amp test
```
-
+
The test is successful if you see `Received expected response` at the end.
-
+
If the test produces any errors, you might try re-running the above config steps and/or asking for help in the [developer chat room](https://chat.civicrm.org/civicrm/channels/dev).
1. After `amp` is configured, you can move on to running [civibuild](/tools/civibuild.md) to build a local development installation of CiviCRM.
--
GitLab