Welcome to the Stellar Go monorepo. These instructions help launch 🚀 you into making and testing code changes to this repository.
For details about what's in this repository and how it is organized read the README.md.
If you're aiming to submit a contribution make sure to also read the contributing guidelines.
If you're making changes to Horizon, look for documentation in its docs directory for specific instructions.
To checkout, build, and run most tests these tools are required:
- Git
- Go (this repository is officially supported on the last two releases of Go)
To run some tests these tools are also required:
- PostgreSQL 9.6+ server running locally, or set environment variables (e.g.
PGHOST, etc) for alternative host. - MySQL 10.1+ server running locally.
Check the code out anywhere, using a GOPATH is not required.
git clone https://github.com/stellar/go
Dependencies are managed using Modules. Dependencies for the packages you are building will be installed automatically when running any Go command that requires them. If you need to pre-download all dependencies for the repository for offline development, run go mod download.
See Dependency management for more details.
go test ./...
go run ./services/<service>
go run ./tools/<tool>
Dependencies are managed using Modules and are tracked in the repository across three files:
- go.mod: Contains a list of direct dependencies, and some indirect dependencies (see why).
- go.sum: Contains hashes for dependencies that are used for verifying downloaded dependencies.
- go.list: A file that is unique to this Go repository, containing the output of
go list -m all, and captures all direct and indirect dependencies and their versions used in builds and tests within this repository. This is not a lock file but instead it helps us track over time which versions are being used for builds and tests, and to see when that changes in PR diffs.
Add new dependencies by adding the import paths to the code. The next time you execute a Go command the tool will update the go.mod and go.sum files.
To add a specific version of a dependency use go get:
go get <importpath>@<version>
Go modules files track the minimum dependency required, not the exact dependency version that will be used. To validate the version of the dependency being used update the go.list file by running go mod -m all > go.list.
Before opening a PR make sure to run these commands to tidy the module files:
go mod tidygo list -m all > go.list
Update an existing dependency by using go get:
go get <importpath>@<version>
Go modules files track the minimum dependency required, not the exact dependency version that will be used. To validate the version of the dependency being used update the go.list file by running go mod -m all > go.list.
Before opening a PR make sure to run these commands to tidy the module files:
go mod tidy
go list -m all > go.list
Remove a dependency by removing all import paths from the code, then use the following commands to remove any unneeded direct or indirect dependencies:
go mod tidy
go list -m all > go.list
Note: go list -m all may show that the dependency is still being used. It will be possible that the dependency is still an indirect dependency. If it's important to understand why the dependency is still being used, use go mod why <importpath>/... and go mod graph | grep <importpath> to understand which modules are importing it.
When updating or adding dependencies it's critical that we review what the
changes are in those dependencies that we are introducing into our builds. When
dependencies change the diff for the go.list file may be too complex to
understand. In those situations use the golistcmp tool to get a list of
changing modules, as well as GitHub links for easy access to diff review.
git checkout master
go list -m -json all > go.list.master
git checkout <branch>
golistcmp go.list.master <(go list -m -json all)