Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add binary installation instructions #232

Merged
merged 1 commit into from
Oct 20, 2016
Merged

Add binary installation instructions #232

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
74 changes: 62 additions & 12 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,20 +10,70 @@ Compliance Masonry is a command-line interface (CLI) that allows users to constr

![screen shot 2016-04-12 at 12 22 02 pm](https://cloud.githubusercontent.com/assets/4596845/14469165/5d27495c-00b1-11e6-9d28-327938463adf.png)

## Quick start

1. Install Go 1.6, and ensure your `GOPATH` is set. Using [gvm](https://github.com/moovweb/gvm) is recommended.
1. Install the tool

```bash
go get github.com/opencontrol/compliance-masonry
```

1. Run the CLI
## Installation
Compliance Masonry is packaged into a downloadable executable program for those
who want to use Compliance Masonry without the need to install any external
dependencies or programs. This is extremely beneficial for those who may to
jump right in without worrying about much technical setup.

### Mac OS X Installation
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe we should move this to the CONTRIBUTING file or something?

#### Technical Users - Mac OS X
In your terminal, run the following:
```sh
curl -L https://github.com/opencontrol/compliance-masonry/releases/download/v1.1.2/compliance-masonry_1.1.2_darwin_amd64.zip -o compliance-masonry.zip
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Minor: Have them cd ~/Downloads first, or rm -rf compliance-masonry_1.1.2_darwin_amd64/ after the fact.

unzip compliance-masonry.zip
cp compliance-masonry_1.1.2_darwin_amd64/compliance-masonry /usr/local/bin
```

```bash
compliance-masonry
```
#### Less Technical Users - Mac OS X
1. Go to the [Github Releases
Page](https://github.com/opencontrol/compliance-masonry/releases).
2. Download the package that corresponds to your machine and operating system.
- The following are common file endings for common systems configurations to
help you decide which one.
- For Mac OS X, you'll want the file ending `_darwin_amd64.zip`
3. Double-click on the downloaded package to unzip the archive and it
should result in a folder which contains a file called `compliance-masonry`.
4. Right click on `compliance-masonry` and select `Copy`
5. Open `Finder`
6. In the navigation bar, click `Go` -> `Go to Folder...`
7. Type in `/usr/local/bin` to open the `bin` folder
8. In the navigation bar, click `Edit` -> `Paste Item`
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

While I appreciate the sentiment behind this section, the reality is that users are going to be running Masonry from the command line anyway, so if they aren't comfortable with running those handful of commands above, they are going to have a hard time with the rest. Therefore, I would take this section out, for simplicity.


### Windows Installation
#### Technical Users - Windows
1. In the browser, go to the [Github Releases
Page](https://github.com/opencontrol/compliance-masonry/releases) and download
the zip file.
2. Unzip it.
3. Create a folder for the masonry binary. (e.g. `C:\Masonry\bin`)
4. Copy the `compliance-masonry.exe` file to `C:\Masonry\bin`
5. Open your PowerShell and run `set PATH=%PATH%;C:\Masonry\bin`.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Will this stick, or do they need to run it every time they open a new shell?


#### Less Technical Users - Windows
1. Go to the [Github Releases
Page](https://github.com/opencontrol/compliance-masonry/releases).
2. Download the package that corresponds to your machine and operating system.
- The following are common file endings for common systems configurations to
help you decide which one.
- For 32 Bit Windows, you'll want the file ending `_windows_386.zip`
- For 64 Bit Windows, you'll want the file ending `_windows_amd64.zip`
3. Double-click on the downloaded package to unzip the archive and it
should result in a folder which contains a file called `compliance-masonry.exe`.
4. Create a folder (e.g. `C:\Masonry\bin`) and copy `compliance-masonry.exe` into it.
5. Follow the instructions [here](http://www.howtogeek.com/118594/how-to-edit-your-system-path-for-easy-command-line-access/)
to add your folder (e.g. `C:\Masonry\bin`) to the `PATH` environment variable.
(In this article, replace `C:\Android\platform-tools` with your folder, e.g. `C:\Masonry\bin`).
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thoughts about merging the two sets of Windows instructions? Seems like they go through the same steps. Curious to hear from @brittag on this.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah, when possible I prefer writing one set of instructions for each system (with consolidated info) instead of two sets of instructions, for ease of maintenance. In my experience it's ok for more technical users to read more-detailed instructions - they'll just mentally translate to the faster advanced way to accomplish a task.


### Linux Installation
In your terminal, run the following:
```sh
# For 64 bit Linux
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe say

The instructions below are for 64-bit architectures. See the releases page for others.

Might not hurt to tell them how to find out their architecture, though I actually don't know a straightforward way to do this.

curl -L https://github.com/opencontrol/compliance-masonry/releases/download/v1.1.2/compliance-masonry_1.1.2_linux_amd64.tar.gz -o compliance-masonry.tar.gz
tar -xf compliance-masonry.tar.gz
cp compliance-masonry_1.1.2_linux_amd64/compliance-masonry /usr/local/bin
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ditto with the cleanup suggestion above.

```

## Creating an OpenControl project

Expand Down