The following guide is mainly targeted towards a Linux or Mac OSX development machine. If you are on Windows, we recommend to take a look at Getting started with almighty-core development on Windows.
You need to install:
-
go(>= v1.6) -
git -
mercurial -
make
Run the following command to find out your Go version.
$ go version
You must at least have Go version 1.6. Our code uses a code generation tool called goa and it doesn’t play nice together with Go 1.5.
Ensure the environment variable GO15VENDOREXPERIMENT
is set, for example by running export GO15VENDOREXPERIMENT=1.
In Go 1.6 it is enabled by default and in Go 1.7 it is always enabled
without the ability to turn it off.
If set, the GO15VENDOREXPERIMENT
variable tells go to look for dependencies not only in the GOPATH (as usual)
but also in a vendor directory located in the source directory.
See Fetch dependencies to see an explanaition on how we deal with dependencies.
This project uses glide as a package manager for Go.
To install glide, go to the release page and download the newest binary for your operating system.
Unpack the archive that you’ve downloaded and place the glide executable
somewhere so that it is in your PATH.
To check if everything is working, type glide --version in a terminal.
$ glide --version glide version v0.11.0
Try to use at least version 0.11.0 as we haven’t tested another version.
Assuming you have Go installed and configured (have $GOPATH setup) here is
how to build.
Check out the code
$ git clone https://github.com/almighty/almighty-core $GOPATH/src/github.com/almighty/almighty-core
Like most other projects, this one depends on various other projects that need to be downloaded.
We also generate some code from design files that shall make it into our final artifacts.
To fetch the dependencies, generate code and finally build the project you can
type make in a freshly clone repository of this project.
$ cd $GOPATH/src/github.com/almighty/almighty-core $ make
There is no need to fetch the dependencies, or re-generate code every time you
want to compile. That’s why we offer special make targets for these topics:
This will download all the dependencies for this project inside a directory
called vendor. This way we can ensure that every developer and our CI system
is using the same version.
$ cd $GOPATH/src/github.com/almighty/almighty-core $ make deps
For dependency management of go packages we use glide.
The file glide.yaml contains all dependencies.
It is not suggested that you edit the file by hand but if you want to
understand the format for this file, look here.
You need to run this command if you just checked out the code and later if you’ve modified the designs.
$ cd $GOPATH/src/github.com/almighty/almighty-core $ make generate
If you want to just build the ALM server and client, run make build.
$ cd $GOPATH/src/github.com/almighty/almighty-core $ make build
This removes all downloaded dependencies, all generated code and compiled artifacts.
$ cd $GOPATH/src/github.com/almighty/almighty-core $ make clean
Here’s how to run all available tests. All tests will check all Go packages
except those in the vendor/ directory.
| unit-tests |
Unit tests have the minimum requirement on time and environment setup. $ cd $GOPATH/src/github.com/almighty/almighty-core $ make test-unit |
| integration-tests |
Integration tests demand more setup (i.e. the PostgreSQL DB must be already running) and probably time. $ cd $GOPATH/src/github.com/almighty/almighty-core $ make test-integration |
| all |
To run both, the unit and the integration tests you can run $ cd $GOPATH/src/github.com/almighty/almighty-core $ make test-all |
To visualize the coverage of unit, integration, or all tests you can run these commands:
-
$ make coverage-unit -
$ make coverage-integration -
$ make coverage-all
|
Note
|
If the tests (see Tests) have not yet run, or if the sources have changed since the last time the tests ran, they will be re-run to produce up to date coverage profiles. |
Each of the above tests (see Tests) produces a coverage profile by default. Those coverage files are available under
tmp/coverage/<package>/coverage.<test>.mode-<mode>
Here’s how the <placeholders> expand
<package>
|
something like |
<test>
|
|
<mode>
|
Sets the mode for coverage analysis for the packages being tested.
Possible values for
|
In addition to all individual coverage information for each package, we also create three more files:
tmp/coverage.unit.mode-<mode>
|
This file collects all the coverage profiles for all unit tests. |
tmp/coverage.integration.mode-<mode>
|
This file collects all the coverage profiles for all integration tests. |
tmp/coverage.mode-<mode>
|
This file is the merge result of the two afore mentioned files and thus gives coverage information for all tests. |
If no configuration file is specified when the core is started, these are the defaults.
#------------------------
# Postgres configuration
#------------------------
postgres.host: localhost
postgres.port: 5432
postgres.user: postgres
postgres.password: mysecretpassword
postgres.sslmode: disable
# The number of times alm server will attempt to open a connection to the database before it gives up
postgres.connection.maxretries: 50
# Duration to wait before trying to connect again
postgres.connection.retrysleep: 1s
#------------------------
# HTTP configuration
#------------------------
http.address: 0.0.0.0:8080
#------------------------
# Misc.
#------------------------
# Enable development related features, e.g. token generation endpoint
developer.mode.enabled: falseAlthough this is a YAML file, we highly suggest to stick to this rather lenghty notation instead of nesting structs.
To override configuration values using environment variables, use the prefix
ALMIGHTY_ and replace the dots in the variables names with underscores.
For example to override postgres.password, set the environment variable ALMIGHTY_POSTGRES_PASSWORD to the value of you liking.
|
Note
|
Environment variables override the default values and the ones you’ve set in your config file. |
Start up dependent docker services using docker-compose and runs auto reload on source change tool fresh.
$ cd $GOPATH/src/github.com/almighty/almighty-core $ make dev
The above steps start the API Server on port 8080.
Test out the build by executing CLI commands in a different terminal.
|
Note
|
The CLI needs the API Server which was started on executing make dev to be up and running. Please do not kill the process. Alternatively if you haven’t run make dev you could just start the server by running ./bin/alm.
|
Create a work item type.
./bin/alm-cli create workitemtype --payload '{"fields":{"system.owner":{"Type":{"Kind":"user"},"Required":true},"system.state":{"Type":{"Kind":"string"},"Required":false}},"name":"Epic"}' -H localhost:8080 --pp
Note: Work Item Type Name is unique. If one tries to create another work item type with same name, error will be trown.
Retrieve the work item type.
$ ./bin/alm-cli show workitemtype --name "Epic" -H localhost:8080
List all available work item types.
$ ./bin/alm-cli list workitemtype -H localhost:8080 --pp
Create a work item.
Based on WorkItemType created above, we can create WorkItem.
We need to use name of work item type in the type field below.
$ ./bin/alm-cli create workitem --payload '{"type": "Epic", "fields": { "system.owner": "tmaeder", "system.state": "open" }}' -H localhost:8080
Retrieve the work item.
$ ./bin/alm-cli show workitem --id 1 -H localhost:8080 --pp
This section shows how to install a Go debugger (delve) and how to actually do some debugging from a terminal.
For somebody coming from a C/C++ background this should feed very familiar as the GNU Debugger or GDB command line interface has similar commands. The following table illustrates just a few of the similarities.
| Function | GNU Debugger | Go debugger (dlv) |
|---|---|---|
Connect to a running program |
|
|
Set a breakpoint |
|
|
Continue after hitting a breakpoint or attaching to a program |
|
|
Show a backtrace for the current location |
|
|
More commands can be found in the Delve documentation.
Install the delve debugger by running:
$ go get github.com/derekparker/delve/cmd/dlv
This will create the file $GOPATH/bin/dlv so in order to run the dlv
executable from anywhere, make sure you have $GOPATH/bin in your $PATH.
Here are instructions to install delve on different platforms.
In this example we’ll debug a running ALM server using delve and set a breakpoint
on the function WorkitemController.Show.
|
Note
|
To see other ways to run dlv, see the usage page.
|
Let’s assume the binary ./bin/alm is running.
To attach the debugger to your running almight-core server,run:
$ dlv attach $(pidof ./bin/alm)
The will bring you into the delve shell which looks like this:
Type 'help' for list of commands. (dlv)
The ./bin/alm program is paused right now. Once we’ve set a breakpoint we will
let it run again.
Now, set the breakpoint
on the on the WorkitemController.Show function that is defined in workitem.go:
(dlv) break WorkitemController.Show
As mentioned before the almighty-core server is paused and we need to bring it back into a run state. To do this, we let the program continue:
(dlv) continue
Open another shell and fetch an existing workitem using curl:
$ curl http://localhost:8080/api/workitems/1
(Replace the 1 with an existing workitem ID if needed)
Now, your debugger shell show something like this:
> main.(*WorkitemController).Show() /tmp/go/src/github.com/almighty/almighty-core/workitem.go:30 (hits goroutine(11):1 total:3) (PC: 0x405633) (dlv)
The program is paused again for you to inspect it and the curl command has not returned yet.
To show a backtrace of how we got here in terms of stack frames, run:
(dlv) bt
The output might look similar to this but it can change over time and as development goes on:
0 0x0000000000405633 in main.(*WorkitemController).Show at /tmp/go/src/github.com/almighty/almighty-core/workitem.go:30 1 0x0000000000520014 in github.com/almighty/almighty-core/app.MountWorkitemController.func3 at /tmp/go/src/github.com/almighty/almighty-core/app/controllers.go:222 2 0x00000000005202fe in github.com/almighty/almighty-core/app.handleWorkitemOrigin.func1 at /tmp/go/src/github.com/almighty/almighty-core/app/controllers.go:257 3 0x0000000000540868 in github.com/almighty/almighty-core/vendor/github.com/goadesign/goa.(*Controller).MuxHandler.func1.1 at /tmp/go/src/github.com/almighty/almighty-core/vendor/github.com/goadesign/goa/service.go:250 4 0x00000000005d6d3e in github.com/almighty/almighty-core/vendor/github.com/goadesign/goa/middleware.Recover.func1.1 at /tmp/go/src/github.com/almighty/almighty-core/vendor/github.com/goadesign/goa/middleware/recover.go:37 5 0x00000000005d3b9c in github.com/almighty/almighty-core/vendor/github.com/goadesign/goa/middleware.ErrorHandler.func1.1 at /tmp/go/src/github.com/almighty/almighty-core/vendor/github.com/goadesign/goa/middleware/error_handler.go:19 6 0x00000000005d5649 in github.com/almighty/almighty-core/vendor/github.com/goadesign/goa/middleware.LogRequest.func1.1 at /tmp/go/src/github.com/almighty/almighty-core/vendor/github.com/goadesign/goa/middleware/log_request.go:65 7 0x00000000005d7229 in github.com/almighty/almighty-core/vendor/github.com/goadesign/goa/middleware.RequestIDWithHeaderAndLengthLimit.func1.1 at /tmp/go/src/github.com/almighty/almighty-core/vendor/github.com/goadesign/goa/middleware/request_id.go:63 8 0x000000000054192c in github.com/almighty/almighty-core/vendor/github.com/goadesign/goa.(*Controller).MuxHandler.func1 at /tmp/go/src/github.com/almighty/almighty-core/vendor/github.com/goadesign/goa/service.go:283 9 0x000000000053faf9 in github.com/almighty/almighty-core/vendor/github.com/goadesign/goa.(*mux).Handle.func1 at /tmp/go/src/github.com/almighty/almighty-core/vendor/github.com/goadesign/goa/mux.go:57 10 0x000000000076c3c2 in github.com/almighty/almighty-core/vendor/github.com/dimfeld/httptreemux.(*TreeMux).ServeHTTP at /tmp/go/src/github.com/almighty/almighty-core/vendor/github.com/dimfeld/httptreemux/router.go:247
The first incrementing number on every second line stands for the number of the stackframe. Stackframe 0 is one where we set the breakpoint earlier.
While there are many interesting ways to inspect your program using the delve debugger, we will instead let our program continue to run and thereby proceed with delivering the workitem to the curl command.
(dlv) continue
Check the shell in which you ran the curl command to see if you have go a result.
To exit the debugger you can use the exit
command or press Ctrl+d, just like you would exit any Bash for example:
(dlv) exit Would you like to kill the process? [Y/n] y
You are being asked if you want to kill the process and the answer to this question very much depends on the way you’ve started delve. If you’ve attached to a running process like we did, the answer to this question is probably no. And if you’ve just started the program under test for debugging purposes then you might as well answer y to stop it.
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent