README overhaul
This commit is contained in:
Will Farrington
parent
766f9c4894
commit
c3808d88b6
1 changed files with 102 additions and 64 deletions
114
README.md
114
README.md
|
|
@ -8,56 +8,94 @@ This repository template is just a basic example of _how_ to do things with them
|
|||
|
||||
## Getting Started
|
||||
|
||||
1. Install Xcode Command Line Tools and/or full Xcode.
|
||||
* If using full Xcode, you'll need to agree to the license by running: `xcodebuild -license`
|
||||
1. Create a new repository on GitHub as your user for your Boxen. (eg.
|
||||
`wfarr/my-boxen`). **Make sure it is a private repository!**
|
||||
1. Use your install of [boxen-web](https://github.com/boxen/boxen-web) or get running manually like so:
|
||||
```
|
||||
sudo mkdir -p /opt/boxen
|
||||
sudo chown ${USER}:admin /opt/boxen
|
||||
mkdir -p ~/src/my-boxen
|
||||
cd ~/src/my-boxen
|
||||
git init
|
||||
git remote add upstream https://github.com/boxen/our-boxen
|
||||
git fetch upstream
|
||||
git checkout -b master upstream/master
|
||||
git remote add origin https://github.com/wfarr/my-boxen
|
||||
git push origin master
|
||||
To give you a brief overview, we're going to:
|
||||
|
||||
script/boxen
|
||||
```
|
||||
* Install dependencies (basically XCode)
|
||||
* Bootstrap a boxen for your self/team/org/company
|
||||
* Then convert your local copy of that boxen to the post-bootstrapped version
|
||||
|
||||
1. Close and reopen your Terminal. If you have a shell config file
|
||||
(eg. `~/.bashrc`) you'll need to add this at the very end:
|
||||
`[ -f /opt/boxen/env.sh ] && source /opt/boxen/env.sh`, and reload
|
||||
your shell.
|
||||
1. Confirm the Boxen env has loaded: `boxen --env`
|
||||
There are a few potential conflicts to keep in mind.
|
||||
Boxen does its best not to get in the way of a dirty system,
|
||||
but you should check into the following before attempting to install your
|
||||
boxen on any machine (we do some checks before every Boxen run to try
|
||||
and detect most of these and tell you anyway):
|
||||
|
||||
Now you have your own my-boxen repo that you can hack on.
|
||||
You may have noticed we didn't ask you to fork the repo.
|
||||
This is because when our-boxen goes open source that'd have some
|
||||
implications about your fork also potentially being public.
|
||||
That's obviously quite bad, so that's why we strongly suggest you
|
||||
create an entirely separate repo and simply pull the code in, as shown above.
|
||||
* Boxen __requires__ at least the XCode Command Line Tools installed.
|
||||
* Boxen __will not__ work with an existing rvm install.
|
||||
* Boxen __may not__ play nice with an existing rbenv install.
|
||||
* Boxen __may not__ play nice with an existing chruby install.
|
||||
* Boxen __may not__ play nice with an existing homebrew install.
|
||||
* Boxen __may not__ play nice with an existing nvm install.
|
||||
* Boxen __recommends__ installing the full XCode.
|
||||
|
||||
## Getting your users started _after_ your "fork" exists
|
||||
### Dependencies
|
||||
|
||||
1. Install the Xcode Command Line Tools (full Xcode install optional).
|
||||
1. Point them at your private install of [boxen-web](https://github.com/boxen/boxen-web), **OR** have them run the following:
|
||||
**Install the XCode Command Lines Tools and/or full XCode.**
|
||||
This will grant you the most predictable behavior in building apps like
|
||||
MacVim.
|
||||
|
||||
How do you do it?
|
||||
|
||||
1. Install XCode from the Mac App Store.
|
||||
1. Open XCode.
|
||||
1. Open the Preferences window (`Cmd-,`).
|
||||
1. Go to the Downloads tab.
|
||||
1. Install the Command Line Tools.
|
||||
|
||||
### Bootstrapping
|
||||
|
||||
Create a **new** git repository somewhere.
|
||||
It can be private or public -- it really doesn't matter.
|
||||
If you're making a repository on GitHub, you _may not_ want to fork this repo
|
||||
to get started.
|
||||
The reason for that is that you can't really make private forks of public
|
||||
repositories easily.
|
||||
|
||||
Once you've done that, you can run the following to get bootstrap
|
||||
your boxen:
|
||||
|
||||
```
|
||||
sudo mkdir -p /opt/boxen
|
||||
sudo chown ${USER}:admin /opt/boxen
|
||||
git clone https://github.com/yourorg/yourreponame.git /opt/boxen/repo
|
||||
git clone https://github.com/boxen/our-boxen /opt/boxen/repo
|
||||
cd /opt/boxen/repo
|
||||
script/boxen
|
||||
|
||||
# add boxen to your shell config, at the end, eg.
|
||||
echo '[ -f /opt/boxen/env.sh ] && source /opt/boxen/env.sh'
|
||||
git remote rm origin
|
||||
git remote add origin <the location of my new git repository>
|
||||
git push -u origin master
|
||||
```
|
||||
|
||||
Open a new terminal, `boxen --env` to confirm.
|
||||
### Distributing
|
||||
|
||||
That's enough to get your boxen into a usable state on other machines,
|
||||
usually.
|
||||
From there, we recommend setting up
|
||||
[boxen-web](https://github.com/boxen/boxen-web)
|
||||
as an easy way to automate letting other folks install your boxen.
|
||||
|
||||
If you _don't_ want to use boxen-web, folks can get using your boxen like so:
|
||||
|
||||
```
|
||||
sudo mkdir -p /opt/boxen
|
||||
sudo chown ${USER}:admin /opt/boxen
|
||||
git clone <location of my new git repository> /opt/boxen/repo
|
||||
cd /opt/boxen/repo
|
||||
script/boxen
|
||||
```
|
||||
|
||||
It should run successfully, and should tell you to source a shell script
|
||||
in your environment.
|
||||
For users without a bash or zsh config or a `~/.profile` file,
|
||||
Boxen will create a shim for you that will work correctly.
|
||||
If you do have a `~/.bashrc` or `~/.zshrc`, your shell will not use
|
||||
`~/.profile` so you'll need to add a line like so at _the end of your config_:
|
||||
|
||||
``` sh
|
||||
[ -f /opt/boxen/env.sh ] && source /opt/boxen/env.sh
|
||||
```
|
||||
|
||||
Once your shell is ready, open a new tab/window in your Terminal
|
||||
and you should be able to successfully run `boxen --env`.
|
||||
If that runs cleanly, you're in good shape.
|
||||
|
||||
## What You Get
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue