Vendoring? Foolish human!
What is this?
Many folks are frustated with the
$GOPATH single workspace model, it doesn't let them check out the source of a project in a directory of their choice and it does not let them have multiple copies of a project checked out at the same time.
Similarly many folks are frustrated with the
gb project model, which gives you the ability to check out a project anywhere you want, but has no solution for libraries, and gb projects are not go gettable.
kang is an experiment to try to provide a solution that:
- lets you checkout a project anywhere you want
- does not force you to give up interoperability with go get.
$GOPATH is required by the go tool is twofold
importstatements are resolved by the go tool relative to a fixed absolute root;
- a location to store dependencies fetched by
gb showed that point 2 could be solved by writing a new build tool that did not wrap the go tool and thus was not forced to reorganise the world to fit into the
The problem with point 1 is whenever the go tool builds a package in a directory, it must answer the question of "what is the full import path of this package".
$GOPATH model answers this question by subtracting the prefix of
$GOPATH/src from the path to the directory of the current package; the remainder is the package's fully qualified import path.
This is why if you checkout a package outside a
$GOPATH workspace, the go tool cannot figure out the packages' fully qualified import path and everything falls apart.
kang solves this by recording the expected import prefix in a manifest file, and it is that prefix, rather than one computed by
$GOPATH directory arithmetic, that is used to dermine the fully qualified import path.
There is no other way to do this, the prefix is mandatory, either you encode it in the location of the directory on disk (relative to known point,
$GOPATH) or you encode it in a file.
Seeing as a manfiest file, the
.kangfile is required, kang puts other useful things in there, like the remote dependency information (well, it will, when we get to that bit).
The location of the
.kangfile determines the root of a project, which is usually (but not required to be) the root of the project's repository, simliar to gb walking up the directory tree to find
src/ or git doing the same for
.kangfile contains one or more lines of the format
name key=value [key=value]...
Elements can be separated by whitespace (space and tab). Lines that do not begin with a letter or number are ignored. This provides a simple mechanism for commentary
.kangfile must contain a line donating the import path prefix, or root, for this project.
# This project's import path prefix project prefix=github.com/constabulary/kang # some comment github.com/pkg/profile version=0.1.0 ; some other comment // third kind of comment lines starting with blank lines are also ignored github.com/pkg/sftp version=0.2.1
kang requires that each external dependency be listed in the project
This can be in one of three forms
# version=SEMVER # Note, it's version=1.1.0, not version=v1.1.0 github.com/fatih/color version=1.1.0 # tag=TAG github.com/mattn/go-colorable tag=0.0.6 # commit=SHA1 golang.org/x/net commit=4971afd
This will cause kang to search its cache, sorted in
.kang/cache for the source of each dependency
Note: Automatic fetching of missing dependencies is not yet implemented.
kang requires Go 1.7.3 or later.
kang is self hosting. You can either checkout the source of this repo and run
go get github.com/constabulary/kang/...
note: not done, see roadmap and TODO.
kang build will build all the source in a project, it can be issued anywhere in the project.
kang test will test all the packages in a project, ditto.
Both commands (will) automatically fetch dependencies if they are not present inside the project (location to be determined, probably
Both commands automatically cache as much as possible for fast incremental compilation.
Here are the big ticket items before kang is a working proof of concept.
- kang test support.
- automatic dependency fetching.
- cgo support.
- cross compile support.
Lots to do.
- move kang.Package.IsStale off kang.Package; someone who holds a Package value should use pkg.NotStale, setting it should be a property of the package loader.
.kangfileand parse contents (format will probably reuse gb's depfile parsing logic; the requirement is must be supported by the Go std lib and must support comments).
- detect source of a project (currently hard coded in
- unit tests
- functional and integration tests
- kang has forked a number of gb components, merge the changes required back into gb so both kang and gb use the same build and test primatives.
Bug reports are most welcome.
Pull requests must include a
fixes #NNN or
updates #NNN comment.
Please discuss your design on the accompanying issue before submitting a pull request. If there is no suitable issue, please open one to discuss the feature before slinging code. Thank you.