Skip to content

Commit

Permalink
add HACKING.md and move content from README.md over
Browse files Browse the repository at this point in the history
  • Loading branch information
@mvo5
mvo5 committed Sep 16, 2016
1 parent 9b85469 commit 8b1a7dd
Show file tree
Hide file tree
Showing 2 changed files with 166 additions and 153 deletions.
160 changes: 160 additions & 0 deletions HACKING.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,160 @@
# Hacking on snapd

Hacking on snapd is fun and straightfoward. The code is extensively
unit tested and we use the [spread](https://github.com/snapcore/spread)
integration test framework for the integration/system level tests.

## Development

### Setting up a 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
[http://golang.org/pkg/go/build/](online) 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 the snappy sources

The easiest way to get the source for `snappy` is to use the `go get` command.

go get -d -v github.com/snapcore/snapd/...

This command will checkout the source of `snappy` and inspect it for any unmet
Go package dependencies, downloading those as well. `go get` will also build
and install `snappy` 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 git local repository of the `snappy` source at
`$GOPATH/github.com/snapcore/snapd`. The source for any
dependent packages will also be available inside `$GOPATH`.

### Dependencies handling

To generate dependencies.tsv you need `godeps`, so

go get launchpad.net/godeps

To obtain the correct dependencies for the project, run:

godeps -t -u dependencies.tsv

You can use the script `get-deps.sh` to run the two previous steps.

If the dependencies need updating

godeps -t ./... > dependencies.tsv

### Building

To build, once the sources are available and `GOPATH` is set, you can just run

go build -o /tmp/snap github.com/snapcore/snapd/cmd/snap

to get the `snap` binary in /tmp (or without -o to get it in the current
working directory). Alternatively:

go install github.com/snapcore/snapd/...

to have it available in `$GOPATH/bin`

### Contributing

Contributions are always welcome! Please make sure that you sign the
Canonical contributor licence agreement at
http://www.ubuntu.com/legal/contributors

Snappy can be found on Github, so in order to fork the source and contribute,
go to https://github.com/snapcore/snapd. Check out [Github's help
pages](https://help.github.com/) to find out how to set up your local branch,
commit changes and create pull requests.

We value good tests, so when you fix a bug or add a new feature we highly
encourage you to create a test in $source_testing.go. See also the section
about Testing.

### Testing

To run the various tests that we have to ensure a high quality source just run:

./run-checks

This will check if the source format is consistent, that it build, all tests
work as expected and that "go vet" and "golint" have nothing to complain.

You can run individual test for a sub-package by changing into that directory and:

go test -check.f $testname

If a test hangs, you can enable verbose mode:

go test -v -check.vv

(or -check.v for less verbose output).

There is more to read about the testing framework on the [website](https://labix.org/gocheck)

### Running the spread tests

To run the spread tests locally you need the latest version of spread
from https://github.com/snapcore/spread. It can be installed via:

$ sudo apt install qemu-kvm autopkgtest
$ sudo snap install spread

Then setup the environment via:

$ mkdir -p .spread/qemu
$ cd .spread/qemu
$ adt-buildvm-ubuntu-cloud
$ mv adt-xenial-amd64-cloud.img ubuntu-16.04.img

And you can run the tests via:

$ spread -v qemu:

For quick reuse you can use:

$ spread -keep qemu:

It will print how to reuse the systems. Make sure to use
`export REUSE_PROJECT=1` in your environment too.


### Testing snapd on a snappy system

To test the `snapd` REST API daemon on a snappy system you need to
transfer it to the snappy system and then run:

sudo systemctl stop snapd.service snapd.socket
sudo /lib/systemd/systemd-activate -E SNAPD_DEBUG=1 -l /run/snapd.socket -l /run/snapd-snap.socket ./snapd

This will stop the installed snapd and activate the new one. Once it's
printed out something like `Listening on /run/snapd.socket as 3.` you
should then

sudo chmod 0666 /run/snapd.socket

so the socket has the right permissions (otherwise you need `sudo` to
connect).
159 changes: 6 additions & 153 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,162 +1,15 @@
[![Build Status][travis-image]][travis-url] [![Coverage Status][coveralls-image]][coveralls-url]
# snapd

The snapd and snap tools enable systems to work with .snap files.
The snapd and snap tools enable systems to work with .snap files. See
[snapcraft.io](http://snapcraft.io) for a high level overview about
snap files and the snapd application.

## Development

### Setting up a 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
[http://golang.org/pkg/go/build/](online) 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 the snappy sources

The easiest way to get the source for `snappy` is to use the `go get` command.

go get -d -v github.com/snapcore/snapd/...

This command will checkout the source of `snappy` and inspect it for any unmet
Go package dependencies, downloading those as well. `go get` will also build
and install `snappy` 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 git local repository of the `snappy` source at
`$GOPATH/github.com/snapcore/snapd`. The source for any
dependent packages will also be available inside `$GOPATH`.

### Dependencies handling

To generate dependencies.tsv you need `godeps`, so

go get launchpad.net/godeps

To obtain the correct dependencies for the project, run:

godeps -t -u dependencies.tsv

You can use the script `get-deps.sh` to run the two previous steps.

If the dependencies need updating

godeps -t ./... > dependencies.tsv

### Building

To build, once the sources are available and `GOPATH` is set, you can just run

go build -o /tmp/snap github.com/snapcore/snapd/cmd/snap

to get the `snap` binary in /tmp (or without -o to get it in the current
working directory). Alternatively:

go install github.com/snapcore/snapd/...

to have it available in `$GOPATH/bin`

### Contributing

Contributions are always welcome! Please make sure that you sign the
Canonical contributor licence agreement at
http://www.ubuntu.com/legal/contributors

Snappy can be found on Github, so in order to fork the source and contribute,
go to https://github.com/snapcore/snapd. Check out [Github's help
pages](https://help.github.com/) to find out how to set up your local branch,
commit changes and create pull requests.

We value good tests, so when you fix a bug or add a new feature we highly
encourage you to create a test in $source_testing.go. See also the section
about Testing.

### Testing

To run the various tests that we have to ensure a high quality source just run:

./run-checks

This will check if the source format is consistent, that it build, all tests
work as expected and that "go vet" and "golint" have nothing to complain.

You can run individual test for a sub-package by changing into that directory and:

go test -check.f $testname

If a test hangs, you can enable verbose mode:

go test -v -check.vv

(or -check.v for less verbose output).

There is more to read about the testing framework on the [website](https://labix.org/gocheck)

### Running the spread tests

To run the spread tests locally you need the latest version of spread
from https://github.com/snapcore/spread. It can be installed via:

$ sudo apt install qemu-kvm autopkgtest
$ sudo snap install spread

Then setup the environment via:

$ mkdir -p .spread/qemu
$ cd .spread/qemu
$ adt-buildvm-ubuntu-cloud
$ mv adt-xenial-amd64-cloud.img ubuntu-16.04.img

And you can run the tests via:

$ spread -v qemu:

For quick reuse you can use:

$ spread -keep qemu:

It will print how to reuse the systems. Make sure to use
`export REUSE_PROJECT=1` in your environment too.


### Testing snapd on a snappy system

To test the `snapd` REST API daemon on a snappy system you need to
transfer it to the snappy system and then run:

sudo systemctl stop snapd.service snapd.socket
sudo /lib/systemd/systemd-activate -E SNAPD_DEBUG=1 -l /run/snapd.socket -l /run/snapd-snap.socket ./snapd

This will stop the installed snapd and activate the new one. Once it's
printed out something like `Listening on /run/snapd.socket as 3.` you
should then

sudo chmod 0666 /run/snapd.socket

so the socket has the right permissions (otherwise you need `sudo` to
connect).
See
[HACKING.md](https://github.com/snapcore/snapd/blob/master/HACKING.md)
for in-depth details how to hack on snapd.

## Reporting bugs

Expand Down

0 comments on commit 8b1a7dd

Please sign in to comment.