github.com/sdboyer/gps@v0.16.3/README.md (about)

     1  <p align="center">
     2  <img 
     3      src="header.png"
     4      width="800" height="255" border="0" alt="gps">
     5  <br>
     6  <a href="https://circleci.com/gh/sdboyer/gps"><img src="https://circleci.com/gh/sdboyer/gps.svg?style=shield" alt="Build Status"></a>
     7  <a href="https://ci.appveyor.com/project/sdboyer/gps"><img src="https://ci.appveyor.com/api/projects/status/github/sdboyer/gps?svg=true&branch=master&passingText=Windows%20-%20OK&failingText=Windows%20-%20failed&pendingText=Windows%20-%20pending" alt="Windows Build Status"></a>
     8  <a href="https://goreportcard.com/report/github.com/sdboyer/gps"><img src="https://goreportcard.com/badge/github.com/sdboyer/gps" alt="Build Status"></a>
     9  <a href="https://codecov.io/gh/sdboyer/gps"><img src="https://codecov.io/gh/sdboyer/gps/branch/master/graph/badge.svg" alt="Codecov" /></a>
    10  <a href="https://godoc.org/github.com/sdboyer/gps"><img src="https://godoc.org/github.com/sdboyer/gps?status.svg" alt="GoDoc"></a>
    11  </p>
    12  
    13  ---
    14  
    15  `gps` is the Go Packaging Solver. It is an engine for tackling dependency
    16  management problems in Go. It is trivial - [about 35 lines of
    17  code](https://github.com/sdboyer/gps/blob/master/example.go) - to replicate the
    18  fetching bits of `go get` using `gps`.
    19  
    20  `gps` is _not_ Yet Another Go Package Management Tool. Rather, it's a library
    21  that package management (and adjacent) tools can use to solve the
    22  [hard](https://en.wikipedia.org/wiki/Boolean_satisfiability_problem) parts of
    23  the problem in a consistent,
    24  [holistic](https://medium.com/@sdboyer/so-you-want-to-write-a-package-manager-4ae9c17d9527)
    25  way. It is a distillation of the ideas behind language package managers like
    26  [bundler](http://bundler.io), [npm](https://www.npmjs.com/),
    27  [elm-package](https://github.com/elm-lang/elm-package),
    28  [cargo](https://crates.io/) (and others) into a library, artisanally
    29  handcrafted with ❤️ for Go's specific requirements.
    30  
    31  `gps` was [on track](https://github.com/Masterminds/glide/issues/565) to become
    32  the engine behind [glide](https://glide.sh); however, those efforts have been
    33  discontinued in favor of gps powering the [experimental, eventually-official
    34  Go tooling](https://github.com/golang/dep).
    35  
    36  The wiki has a [general introduction to the `gps`
    37  approach](https://github.com/sdboyer/gps/wiki/Introduction-to-gps), as well
    38  as guides for folks [implementing
    39  tools](https://github.com/sdboyer/gps/wiki/gps-for-Implementors) or [looking
    40  to contribute](https://github.com/sdboyer/gps/wiki/gps-for-Contributors).
    41  
    42  ## Wait...a package management _library_?!
    43  
    44  Yup. See [the rationale](https://github.com/sdboyer/gps/wiki/Rationale).
    45  
    46  ## Features
    47  
    48  A feature list for a package management library is a bit different than one for
    49  a package management tool. Instead of listing the things an end-user can do,
    50  we list the choices a tool *can* make and offer, in some form, to its users, as
    51  well as the non-choices/assumptions/constraints that `gps` imposes on a tool.
    52  
    53  ### Non-Choices
    54  
    55  We'd love for `gps`'s non-choices to be noncontroversial. But that's not always
    56  the case.
    57  
    58  Nevertheless, these non-choices remain because, taken as a whole, they make
    59  experiments and discussion around Go package management coherent and
    60  productive.
    61  
    62  * Go >=1.6, or 1.5 with `GO15VENDOREXPERIMENT = 1` set
    63  * Everything under `vendor/` is volatile and controlled solely by the tool
    64  * A central cache of repositories is used (cannot be `GOPATH`)
    65  * A [**project**](https://godoc.org/github.com/sdboyer/gps#ProjectRoot) concept:
    66    a tree of packages, all covered by one `vendor` directory
    67  * A [**manifest** and
    68    **lock**](https://github.com/sdboyer/gps/wiki/gps-for-Implementors#manifests-and-locks)
    69    approach to tracking version and constraint information
    70  * Upstream sources are one of `git`, `bzr`, `hg` or `svn` repositories
    71  * What the available versions are for a given project/repository (all branches, tags, or revs are eligible)
    72    * In general, semver tags are preferred to branches, are preferred to plain tags
    73  * The actual packages that must be present (determined through import graph static analysis)
    74    * How the import graph is statically analyzed - similar to `go/build`, but with a combinatorial view of build tags ([not yet implemented](https://github.com/sdboyer/gps/issues/99))
    75  * All packages from the same source (repository) must be the same version
    76  * Package import cycles are not allowed ([not yet implemented](https://github.com/sdboyer/gps/issues/66))
    77  
    78  There are also some current non-choices that we would like to push into the realm of choice:
    79  
    80  * Importable projects that are not bound to the repository root
    81  * Source inference around different import path patterns (e.g., how `github.com/*` or `my_company/*` are handled)
    82  
    83  ### Choices
    84  
    85  These choices represent many of the ways that `gps`-based tools could
    86  substantively differ from each other.
    87  
    88  Some of these are choices designed to encompass all options for topics on which
    89  reasonable people have disagreed. Others are simply important controls that no
    90  general library could know _a priori_.
    91  
    92  * How to store manifest and lock information (file(s)? a db?)
    93  * Which of the other package managers to interoperate with
    94  * Which types of version constraints to allow the user to specify (e.g., allowing [semver ranges](https://docs.npmjs.com/misc/semver) or not)
    95  * Whether or not to strip nested `vendor` directories
    96  * Which packages in the import graph to [ignore](https://github.com/sdboyer/gps/wiki/gps-for-Implementors#ignoring-packages) (if any)
    97  * What constraint [overrides](https://github.com/sdboyer/gps/wiki/gps-for-Implementors#overrides) to apply (if any)
    98  * What [informational output](https://github.com/sdboyer/gps/wiki/gps-for-Implementors#trace-and-tracelogger) to show the end user
    99  * What dependency version constraints are declared by the [root project](https://github.com/sdboyer/gps/wiki/gps-for-Implementors#manifest-data)
   100  * What dependency version constraints are declared by [all dependencies](https://github.com/sdboyer/gps/wiki/gps-for-Implementors#the-projectanalyzer)
   101  * Given a [previous solution](https://github.com/sdboyer/gps/wiki/gps-for-Implementors#lock-data), [which versions to let change, and how](https://github.com/sdboyer/gps/wiki/gps-for-Implementors#tochange-changeall-and-downgrade)
   102    * In the absence of a previous solution, whether or not to use [preferred versions](https://github.com/sdboyer/gps/wiki/gps-for-Implementors#preferred-versions)
   103  * Allowing, or not, the user to [swap in different source locations](https://github.com/sdboyer/gps/wiki/gps-for-Implementors#projectidentifier) for import paths (e.g. forks)
   104  * Specifying additional input/source packages not reachable from the root import graph
   105  
   106  This list may not be exhaustive - see the
   107  [implementor's guide](https://github.com/sdboyer/gps/wiki/gps-for-Implementors)
   108  for a proper treatment.
   109  
   110  ## Contributing
   111  
   112  Yay, contributing! Please see
   113  [CONTRIBUTING.md](https://github.com/sdboyer/gps/blob/master/CONTRIBUTING.md).
   114  Note that `gps` also abides by a [Code of
   115  Conduct](https://github.com/sdboyer/gps/blob/master/CODE_OF_CONDUCT.md), and is MIT-licensed.