Skip to content

Commit

Permalink
docs(readme): users should 'make install' instead of 'go build'
Browse files Browse the repository at this point in the history
  • Loading branch information
@b5
b5 committed Nov 30, 2020
1 parent e6a0a67 commit ed4b87e
Showing 1 changed file with 38 additions and 55 deletions.
93 changes: 38 additions & 55 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,13 +2,13 @@

[![Qri](https://img.shields.io/badge/made%20by-qri-magenta.svg?style=flat-square)](https://qri.io) [![GoDoc](https://godoc.org/github.com/qri-io/qri?status.svg)](http://godoc.org/github.com/qri-io/qri) [![License](https://img.shields.io/github/license/qri-io/qri.svg?style=flat-square)](./LICENSE) [![Codecov](https://img.shields.io/codecov/c/github/qri-io/qri.svg?style=flat-square)](https://codecov.io/gh/qri-io/qri) [![CI](https://img.shields.io/circleci/project/github/qri-io/qri.svg?style=flat-square)](https://circleci.com/gh/qri-io/qri)

<h1 align="center">Qri Backend and CLI</h1>
<h1 align="center">Qri CLI</h1>

<div align="center">
<img alt="logo" src="https://qri.io/img/blobs/blob_trio.png" width="128">
</div>
<div align="center">
<strong>a global dataset version control system (GDVCS) built on the distributed web</strong>
<strong>a dataset version control system built on the distributed web</strong>
</div>

<div align="center">
Expand Down Expand Up @@ -54,7 +54,7 @@
| "I want to help build the Qri backend" | [Read the Contributing guides](https://github.com/qri-io/qri/blob/master/CONTRIBUTOR.md) |
| "I want to build Qri from source" | [Build Qri from source](#build)

__qri is a global dataset version control system (GDVCS) built on the distributed web__
__qri is a global dataset version control system built on the distributed web__

Breaking that down:

Expand All @@ -72,47 +72,27 @@ If you’re unfamiliar with *version control,* particularly the distributed kind

Because qri is *global* and *content-addressed*, adding data to qri also checks the entire network to see if someone has added it before. Since qri is focused solely on datasets, it can provide meaningful search results. Every change on qri is associated with a peer, creating an audit-able trail you can use to quickly see what has changed and who has changed it. All datasets on qri are automatically described at the time of ingest using a flexible schema that makes data naturally inter-operate. Qri comes with tools to turn *all* datasets on the network into a JSON API with a single command. Finally, all changes in qri are tracked & synced.

## Packages

Qri is comprised of many specialized packages. Below you will find a summary of each package.

| Package | Go Docs | Go Report Card | Description |
|---------|---------|----------------|-------------|
| [`api`](https://github.com/qri-io/qri/tree/master/api) | [![Go Docs](https://godoc.org/github.com/qri-io/qri?status.svg)](https://godoc.org/github.com/qri-io/qri/api) | [![report](https://goreportcard.com/badge/github.com/qri-io/qri)](https://goreportcard.com/report/github.com/qri-io/qri) | user accessible layer, primarily made for communication with our frontend webapp |
| [`cmd`](https://github.com/qri-io/qri/tree/master/cmd) | [![Go Docs](https://godoc.org/github.com/qri-io/qri?status.svg)](https://godoc.org/github.com/qri-io/qri/cmd) | [![report](https://goreportcard.com/badge/github.com/qri-io/qri)](https://goreportcard.com/report/github.com/qri-io/qri) | our command line interface |
| [`config`](https://github.com/qri-io/qri/tree/master/config) | [![Go Docs](https://godoc.org/github.com/qri-io/qri?status.svg)](https://godoc.org/github.com/qri-io/qri/config) | [![report](https://goreportcard.com/badge/github.com/qri-io/qri)](https://goreportcard.com/report/github.com/qri-io/qri) | user configuration details, includes peer's profile |
| [`lib`](https://github.com/qri-io/qri/tree/master/lib) | [![Go Docs](https://godoc.org/github.com/qri-io/qri?status.svg)](https://godoc.org/github.com/qri-io/qri/lib) | [![report](https://goreportcard.com/badge/github.com/qri-io/qri)](https://goreportcard.com/report/github.com/qri-io/qri) | takes arguments from the cmd and api layer and forms proper requests to call to the action layer |
| [`p2p`](https://github.com/qri-io/qri/tree/master/p2p) | [![Go Docs](https://godoc.org/github.com/qri-io/qri?status.svg)](https://godoc.org/github.com/qri-io/qri/p2p) | [![report](https://goreportcard.com/badge/github.com/qri-io/qri)](https://goreportcard.com/report/github.com/qri-io/qri) | the peer to peer communication layer of qri |
| [`repo`](https://github.com/qri-io/qri/tree/master/repo) | [![Go Docs](https://godoc.org/github.com/qri-io/qri?status.svg)](https://godoc.org/github.com/qri-io/qri/repo) | [![report](https://goreportcard.com/badge/github.com/qri-io/qri)](https://goreportcard.com/report/github.com/qri-io/qri) | the repository: saving, removing, and storing datasets, profiles, and the config |
| [`dataset`](https://github.com/qri-io/dataset) | [![Go Docs](https://godoc.org/github.com/qri-io/dataset?status.svg)](https://godoc.org/github.com/qri-io/dataset) | [![report](https://goreportcard.com/badge/github.com/qri-io/dataset)](https://goreportcard.com/report/github.com/qri-io/dataset) | the blueprint for a dataset, the atoms that make up qri |
| [`registry`](https://github.com/qri-io/qri/tree/master/registry) | [![Go Docs](https://godoc.org/github.com/qri-io/qri?status.svg)](https://godoc.org/github.com/qri-io/qri/registry) | [![report](https://goreportcard.com/badge/github.com/qri-io/qri)](https://goreportcard.com/report/github.com/qri-io/qri) | the blueprint for a registry: the service that allows profiles to be unique and datasets to be searchable |
| [`starlib`](https://github.com/qri-io/starlib) | [![Go Docs](https://godoc.org/github.com/qri-io/starlib?status.svg)](https://godoc.org/github.com/qri-io/starlib) | [![report](https://goreportcard.com/badge/github.com/qri-io/starlib)](https://goreportcard.com/report/github.com/qri-io/starlib) | the starlark standard library available for qri transform scripts |
| [`qfs`](https://github.com/qri-io/qfs) | [![Go Docs](https://godoc.org/github.com/qri-io/qfs?status.svg)](https://godoc.org/github.com/qri-io/qfs) | [![report](https://goreportcard.com/badge/github.com/qri-io/qfs)](https://goreportcard.com/report/github.com/qri-io/qfs) | "qri file sytem" is Qri's file system abstraction for getting & storing data from different sources |
| [`ioes`](https://github.com/qri-io/ioes) | [![Go Docs](https://godoc.org/github.com/qri-io/ioes?status.svg)](https://godoc.org/github.com/qri-io/ioes) | [![report](https://goreportcard.com/badge/github.com/qri-io/ioes)](https://goreportcard.com/report/github.com/qri-io/ioes) | package to handle in, out, and error streams: gives us better control of where we send output and errors |
| [`jsonschema`](https://github.com/qri-io/jsonschema) | [![Go Docs](https://godoc.org/github.com/qri-io/jsonschema?status.svg)](https://godoc.org/github.com/qri-io/jsonschema) | [![report](https://goreportcard.com/badge/github.com/qri-io/jsonschema)](https://goreportcard.com/report/github.com/qri-io/jsonschema) | used to describe the structure of a dataset, so we can validate datasets and determine dataset interop |

### Outside Libraries

The following packages are not under Qri, but are important dependencies, so we display their latest versions for convenience.

| Package | Version |
|--------|-------|
| `ipfs` | [![ipfs version](https://img.shields.io/badge/ipfs-v0.6.0-blue.svg)](https://github.com/ipfs/go-ipfs/) |

<a id="build"></a>
## Building From Source

To build qri you'll need the [go programming language](https://golang.org/dl/) on your machine. We require at least `go` version 1.13 to build qri.
To build qri you'll need the [go programming language](https://golang.org/dl/) on your machine.

If you are new to using `go`, you should set your PATH environment variable to include the location that your go tool installs binaries to, which is usually `~/go/bin`. For more information about environment variables see [this tutorial](https://www.twilio.com/blog/2017/01/how-to-set-environment-variables.html).
```shell
$ git clone https://github.com/qri-io/qri
$ cd qri
$ make install
```

Building then depends upon your operating system:
If this is your first time building, this command will have a lot of output. That's good! Its means it's working :) It'll take a minute or two to build.

### Mac OSX
After this is done, there will be a new binary `qri` in your `~/go/bin` directory if using go modules, and `$GOPATH/bin` directory otherwise. You should be able to run:

Having `go` installed is enough, proceed to <a href="#building">building</a>.
```shell
$ qri help
```
and see help output.

### Windows
### Building on Windows

To start, make sure that you have enabled [Developer Mode](https://docs.microsoft.com/en-us/windows/uwp/get-started/enable-your-device-for-development). A library that we depend on needs it enabled in order to properly handle symlinks. If not done, you'll likely get the error message "A required privilege is not held by the client".

Expand All @@ -136,7 +116,7 @@ Due to how msys2 treats the `PATH` variable, you also need to add a new environm

Once these steps are complete, proceed to <a href="#building">building</a>.

### Linux
### Building on Rasberry PI

On a Raspberry PI, you'll need to increase your swap file size in order to build. Normal desktop and server linux OSes should be fine to proceed to <a href="#building">building</a>.

Expand All @@ -162,30 +142,33 @@ sudo dphys-swapfile swapon

Otherwise linux machines with reduced memory will have other ways to increase their swap file sizes. Check documentation for your particular machine.

### Building

In your terminal, navigate to some directory that you want to work within. Let's say we're using a directory in our home folder called "go-code".

```shell
$ cd go-code
$ git clone https://github.com/qri-io/qri
```
## Packages

Once this repository is cloned, enter it and install:
Qri is comprised of many specialized packages. Below you will find a summary of each package.

```shell
$ cd qri
$ go install
```
| Package | Go Docs | Go Report Card | Description |
|---------|---------|----------------|-------------|
| [`api`](https://github.com/qri-io/qri/tree/master/api) | [![Go Docs](https://godoc.org/github.com/qri-io/qri?status.svg)](https://godoc.org/github.com/qri-io/qri/api) | [![report](https://goreportcard.com/badge/github.com/qri-io/qri)](https://goreportcard.com/report/github.com/qri-io/qri) | user accessible layer, primarily made for communication with our frontend webapp |
| [`cmd`](https://github.com/qri-io/qri/tree/master/cmd) | [![Go Docs](https://godoc.org/github.com/qri-io/qri?status.svg)](https://godoc.org/github.com/qri-io/qri/cmd) | [![report](https://goreportcard.com/badge/github.com/qri-io/qri)](https://goreportcard.com/report/github.com/qri-io/qri) | our command line interface |
| [`config`](https://github.com/qri-io/qri/tree/master/config) | [![Go Docs](https://godoc.org/github.com/qri-io/qri?status.svg)](https://godoc.org/github.com/qri-io/qri/config) | [![report](https://goreportcard.com/badge/github.com/qri-io/qri)](https://goreportcard.com/report/github.com/qri-io/qri) | user configuration details, includes peer's profile |
| [`lib`](https://github.com/qri-io/qri/tree/master/lib) | [![Go Docs](https://godoc.org/github.com/qri-io/qri?status.svg)](https://godoc.org/github.com/qri-io/qri/lib) | [![report](https://goreportcard.com/badge/github.com/qri-io/qri)](https://goreportcard.com/report/github.com/qri-io/qri) | takes arguments from the cmd and api layer and forms proper requests to call to the action layer |
| [`p2p`](https://github.com/qri-io/qri/tree/master/p2p) | [![Go Docs](https://godoc.org/github.com/qri-io/qri?status.svg)](https://godoc.org/github.com/qri-io/qri/p2p) | [![report](https://goreportcard.com/badge/github.com/qri-io/qri)](https://goreportcard.com/report/github.com/qri-io/qri) | the peer to peer communication layer of qri |
| [`repo`](https://github.com/qri-io/qri/tree/master/repo) | [![Go Docs](https://godoc.org/github.com/qri-io/qri?status.svg)](https://godoc.org/github.com/qri-io/qri/repo) | [![report](https://goreportcard.com/badge/github.com/qri-io/qri)](https://goreportcard.com/report/github.com/qri-io/qri) | the repository: saving, removing, and storing datasets, profiles, and the config |
| [`dataset`](https://github.com/qri-io/dataset) | [![Go Docs](https://godoc.org/github.com/qri-io/dataset?status.svg)](https://godoc.org/github.com/qri-io/dataset) | [![report](https://goreportcard.com/badge/github.com/qri-io/dataset)](https://goreportcard.com/report/github.com/qri-io/dataset) | the blueprint for a dataset, the atoms that make up qri |
| [`registry`](https://github.com/qri-io/qri/tree/master/registry) | [![Go Docs](https://godoc.org/github.com/qri-io/qri?status.svg)](https://godoc.org/github.com/qri-io/qri/registry) | [![report](https://goreportcard.com/badge/github.com/qri-io/qri)](https://goreportcard.com/report/github.com/qri-io/qri) | the blueprint for a registry: the service that allows profiles to be unique and datasets to be searchable |
| [`starlib`](https://github.com/qri-io/starlib) | [![Go Docs](https://godoc.org/github.com/qri-io/starlib?status.svg)](https://godoc.org/github.com/qri-io/starlib) | [![report](https://goreportcard.com/badge/github.com/qri-io/starlib)](https://goreportcard.com/report/github.com/qri-io/starlib) | the starlark standard library available for qri transform scripts |
| [`qfs`](https://github.com/qri-io/qfs) | [![Go Docs](https://godoc.org/github.com/qri-io/qfs?status.svg)](https://godoc.org/github.com/qri-io/qfs) | [![report](https://goreportcard.com/badge/github.com/qri-io/qfs)](https://goreportcard.com/report/github.com/qri-io/qfs) | "qri file sytem" is Qri's file system abstraction for getting & storing data from different sources |
| [`ioes`](https://github.com/qri-io/ioes) | [![Go Docs](https://godoc.org/github.com/qri-io/ioes?status.svg)](https://godoc.org/github.com/qri-io/ioes) | [![report](https://goreportcard.com/badge/github.com/qri-io/ioes)](https://goreportcard.com/report/github.com/qri-io/ioes) | package to handle in, out, and error streams: gives us better control of where we send output and errors |
| [`jsonschema`](https://github.com/qri-io/jsonschema) | [![Go Docs](https://godoc.org/github.com/qri-io/jsonschema?status.svg)](https://godoc.org/github.com/qri-io/jsonschema) | [![report](https://goreportcard.com/badge/github.com/qri-io/jsonschema)](https://goreportcard.com/report/github.com/qri-io/jsonschema) | used to describe the structure of a dataset, so we can validate datasets and determine dataset interop |

If this is your first time building, this command will have a lot of output. That's good! Its means it's working :) It'll take a minute or two to build.
### Outside Libraries

After this is done, there will be a new binary `qri` in your `~/go/bin` directory if using go modules, and `$GOPATH/bin` directory otherwise. You should be able to run:
The following packages are not under Qri, but are important dependencies, so we display their latest versions for convenience.

```shell
$ qri help
```
and see help output.
| Package | Version |
|--------|-------|
| `ipfs` | [![ipfs version](https://img.shields.io/badge/ipfs-v0.6.0-blue.svg)](https://github.com/ipfs/go-ipfs/) |


###### This documentation has been adapted from the [Cycle.js](https://github.com/cyclejs/cyclejs) documentation.

0 comments on commit ed4b87e

Please sign in to comment.