go-libp2p is a p2p networking stack based on the principle of modularity. Its modules are scattered across a number of Git repos. We have recently migrated from gx to gomod as the primary dependency and build management tool.
To make developing with gomod easy, this meta-repository aggregates all
go-libp2p repos under a single roof via git submodules, and provides a
management script (./workspace.sh) for automating common workflows.
This setup is currently at pilot stage and heavily WIP. Feedback and contributions are welcome. Some wishlist items include:
- go mod <> IPFS integration, to consume and publish content-addressed dependencies easily. Stebalien/ipgo is one possible direction.
- Automating the "bubbling" and update workflow, via scripts or tooling such as renovate.
- Shared libp2p/IPFS workspace.
- Nightly master builds.
This pre-commit hook will alert you when you are trying to commit go.mod file with local replace directives. This is useful pattern for developing, but has no place on remote.
It is best to install it as global githook. Instructions here.
Getting started
This will initialise the submodules by cloning repos into their relevant subdirectories.
$ git clone --recursive <this repo>
Switch to local module resolution
Interlinks all repos for local development through replace directives.
$ ./workspace.sh local
Switch to remote module resolution
Removes the replace directives added by local.
$ ./workspace.sh remote
Stash local changes and update all repos from origin/master
$ ./workspace.sh remote # to reset go.mod files to original
$ ./workspace.sh refresh
Gomod is great for mono-repo projects that depend on 3rd party dependencies, but there are some challenges when working with an intervowen set of modularised packages:
- Go tools resolve module versions from remotes.
- Developers want to make changesets across a number of local repos and have them visible by interdependent modules.
Aggregating modules under one roof, and using go mod replace directives to
interlink them locally via replace directives, provides a neat GOPATH-like
development experience.
Detour: GOPATH vs go modules
The GOPATH monolith is irrelevant in the Go modules universe. Now you can
check out modules anywhere in the filesystem.
Running go get from inside a Go module will download packages into the global
go mod cache ($GOPATH/pkg/mod), where they are indexed by module path and
version.
All go tools (go build, go test, etc.) are now module-friendly. They
automatically add require directives go go.mod for new imports in code,
download packages from remotes, and more. It's like magic.
NOTE: Running go get in a tree without a go.mod will still place that
package under your GOPATH. Running go commands from within your GOPATH
will behave like before (i.e. no module-based builds) even if the package has a
go.mod, unless you explicitly set GO111MODULE=on.
Fun fact: Go mod makes bold assertions about immutability, and this transpires
even to file permissions under the module cache. A quick ls -l therein shows
that go strips away write permissions from downloaded modules, even for the
owner.
Familiarise yourself with Go modules. In particular, pay attention to how minimal version selection works.
Reacquaint yourself with go commands. Most of the commands you know and have
come to love (go get, go build, go test) now deal with modules
transparently. Suggested read: go command manual,
and pay special attention to the sections dedicated to modules behaviour.