~axwalk/juju-core/lp1303195-manual-ubuntuuser-bash

juju-core

=========

juju is devops distilled.

Getting started

===============

`juju-core` is written in Go (http://golang.org), a modern, compiled, statically

typed, concurrent language. This document describes how to build `juju-core`

from source.

If you are looking for binary releases of `juju-core`, they are

available from the Juju stable PPA, `https://launchpad.net/~juju/+archive/stable`,

and can be installed with:

    sudo apt-add-repository ppa:juju/stable

    sudo apt-get update

    sudo apt-get install juju

Installing prerequisites

------------------------

You can use `make install-dependencies` or, if you prefer to install

them manually, check the Makefile target.

This will add some PPAs to ensure that you can install the required

golang and mongodb-server versions for precise onwards, in addition to the

other dependencies.

Setting GOPATH

--------------

When working with the source of Go programs, you should define a path within

your home directory (or other workspace) which will be your `GOPATH`. `GOPATH`

is similar to Java's `CLASSPATH` or Python's `~/.local`. `GOPATH` is documented

online at `http://golang.org/pkg/go/build/` and inside the `go` tool itself

    go help gopath

Various conventions exist for naming the location of your `GOPATH`, but it should

exist, and be writable by you. For example

    export GOPATH=${HOME}/work

    mkdir $GOPATH

will define and create `$HOME/work` as your local `GOPATH`. The `go` tool itself

will create three subdirectories inside your `GOPATH` when required; `src`, `pkg`

and `bin`, which hold the source of Go programs, compiled packages and compiled

binaries, respectively.

Setting `GOPATH` correctly is critical when developing Go programs. Set and

export it as part of your login script.

Add `$GOPATH/bin` to your `PATH`, so you can run the go programs you install:

    PATH="$PATH:$GOPATH/bin"

Getting juju-core

=================

The easiest way to get the source for `juju-core` is to use the `go get` command.

    go get -v launchpad.net/juju-core/...

This command will checkout the source of `juju-core` and inspect it for any unmet

Go package dependencies, downloading those as well. `go get` will also build and

install `juju-core` and its dependencies. To checkout without installing, use the

`-d` flag. More details on the `go get` flags are available using

    go help get

At this point you will have the bzr working copy of the `juju-core` source at

`$GOPATH/launchpad.net/juju-core`. The source for any dependent packages will

also be available inside `$GOPATH`. You can use `bzr pull`, or the less convenient

`go get -u launchpad.net/juju-core/...` to update the source from time to time.

If you want to know more about contributing to `juju-core`, please read the

`CONTRIBUTING` companion to this file.

Building juju-core

==================

    go install -v launchpad.net/juju-core/...

Will build juju and install the binary commands into `$GOPATH/bin`. It is likely

if you have just completed the previous step to get the `juju-core` source, the

install process will produce no output, as the final executables are up-to-date.

Using juju-core

===============

After following the steps above you will have the `juju` client installed in

`GOPATH/bin/juju`. You should ensure that this version of `juju` appears earlier

in your path than any packaged versions of `juju-core`, or older Python juju

commands. You can verify this using

    which juju

You should be able to bootstrap a local environment now with the following

(Note: the use of sudo for bootstrap here is only required for the local

provider because it uses LXC, which requires root privileges)

    juju init

    juju switch local

    sudo juju bootstrap

--upload-tools

--------------

The `juju` client program, and the juju 'tools' are deployed in lockstep. When a

release of `juju-core` is made, the compiled tools matching that version of juju

are extracted and uploaded to a known location. This consumes a release version

number, and implies that no tools are available for the next, development, version

of juju. Therefore, when using the development version of juju you will need to

pass an additional flag, `--upload-tools` to instruct the `juju` client to build

a set of tools from source and upload them to the environment as part of the

bootstrap process.

    juju bootstrap -e your-environment --upload-tools {--debug}

Installing bash completion for juju

===================================

    make install-etc

Will install Bash completion for `juju` cli to

`/etc/bash_completion.d/juju-core` It does dynamic completion for commands

requiring service, unit or machine names (like e.g. juju status <service>,

juju ssh <instance>, juju terminate-machine <machine#>, etc),

by parsing cached `juju status` output for speedup. It also does

command flags completion by parsing `juju help ...` output.