github.com/thetechnoweenie/graven@v1.0.2/README.md (about) 1 # graven 2 3 Graven is a build management tool for Go projects. It takes light 4 cues from projects like Maven and Leiningen, but given Go's much 5 simpler environment and far different take on dependency management, 6 little is shared beyond the goals. 7 8 Want to know more? Read about the [Motivation for Graven](docs/motivation.md). 9 10 ### Tutorial Video 11 12 [](https://youtu.be/forR0rTmqec) 13 14 ## Prerequisites 15 16 Graven currently requires the following tools to be on your path: 17 18 * `go` - the Go build tool, used to compile and test your application. 19 * `git` - used during the release process to validate the state of your repo, 20 and tag your repo. 21 22 Of course if you don't plan to use the `release` command commands, you 23 can still use `graven` just for building, testing and packaging, and thus 24 would only require the `go` tool. 25 26 ## Installation 27 28 If you want to run the latest, you can just `go get` the tool. 29 30 ``` 31 go get -u github.com/cbegin/graven 32 ``` 33 34 For greater consistency and stability, you can run a specific relese version from: 35 36 * https://github.com/cbegin/graven/releases 37 38 ## Workflow Example 39 40 Whether your starting an entirely new project, or working with existing source, 41 the workflow should be the same. 42 43 Not all of these steps are always necessary. See below for a description of 44 implied workflow dependencies. 45 46 ```bash 47 # Once per project, run the init command and modify 48 # default project.yaml with relevant names and repos etc. 49 $ cd ./some/working/directory 50 $ graven init 51 $ vi project.yaml 52 53 # Typical development cycle 54 $ graven clean 55 $ graven build 56 $ graven test 57 $ graven package 58 59 # When you're ready to release 60 $ graven repo --login --name github 61 Please type or paste a github token (will not echo): 62 $ graven release 63 $ graven bump [major|minor|patch|QUALIFIER] 64 ``` 65 66 A typical development cycle looks like the following diagram. The `init` command 67 is run once per project, then `clean`, `build`, `test` and `package` are typically used 68 throughout the development cycle. Releases occur less frequently, and versions 69 are bumped after the release. 70 71 The `freeze` and `unfreeze` commands are optional and on a completely 72 independent flow, thus can be executed any time. They are discussed separately 73 here: [Freezing Dependencies](docs/freezing.md). 74 75 ``` 76 +----------+ 77 > | build | \ 78 / +----------+ \ 79 / \ 80 / v 81 +----------+ +----------+ +----------+ 82 | init |--->| clean | | test | 83 +----------+ +----------+ +----------+ 84 ^ / 85 \ / 86 \ +----------+ / 87 \| package |<- 88 +----------+ +----------+ 89 | freeze | | 90 +----------+ v 91 | +----------+ 92 | | release | 93 +-----v----+ +----------+ 94 | unfreeze | | 95 +----------+ | 96 +-----v----+ 97 | bump | 98 +----------+ 99 ``` 100 101 ## project.yaml example 102 103 **Before you have flashbacks of Maven POMs...** note that this is probably the 104 biggest project.yaml file you'll ever see. Most projects will have shorter, 105 simpler project.yaml files, and you'll rarely have to modify them once initialized. 106 107 The following documented structure (derived from this 108 very project) will help better understand what you can do with it. 109 110 ```yaml 111 # Name, initially derived from parent directory. 112 name: graven 113 # Version is typically managed with the graven bump command. 114 version: 0.6.6 115 # You can specify a required go version, supporting ranges. 116 go_version: ">=1.9.1" 117 # List of artifacts. Each artifact builds one or more packages into executables, 118 # and provides compiler flags, environment variables, and resources. 119 # Upon initialization, an artifact config will be generated for darwin, linux and 120 # windows. You can safely delete any artifacts you don't need. The classifier 121 # will be used in artifact names and target build directory names. 122 artifacts: 123 - classifier: darwin 124 # Each target is a package/executable combo with compiler flags and environment variables. 125 # Upon initialization, a target will be created for each main package found in the path. 126 # You can safely delete any you don't want. 127 targets: 128 - executable: bin/graven 129 package: . 130 flags: "" 131 env: {} 132 # archive supports zip and tar.gz (or tgz, as a single dot alias) 133 archive: tgz 134 resources: [] 135 # Environment variables, can be set at project, artifact and target level. 136 env: 137 GOARCH: amd64 138 GOOS: darwin 139 - classifier: linux 140 targets: 141 - executable: bin/graven 142 package: . 143 flags: "" 144 env: {} 145 archive: tar.gz 146 resources: [] 147 env: 148 GOARCH: amd64 149 GOOS: linux 150 - classifier: win 151 targets: 152 - executable: graven.exe 153 package: . 154 flags: "" 155 env: {} 156 archive: zip 157 resources: [] 158 env: 159 GOARCH: amd64 160 GOOS: windows 161 # Resources will be included in the packaged archive. Can be overridden at 162 # artifact level. 163 resources: 164 - LICENSE 165 # Configures a repository for deployment. 166 # Use graven repo --login --name [name] to authenticate 167 repositories: 168 github: 169 url: https://api.github.com/ 170 group: cbegin 171 artifact: graven 172 type: github 173 # Github repos only support releases 174 roles: 175 - release 176 artifactory: 177 url: http://localhost:8081/artifactory/releases/ 178 group: cbegin 179 artifact: graven 180 type: maven 181 # Supports both releases and frozen dependencies 182 roles: 183 - release 184 - dependency 185 nexus: 186 url: http://localhost:8082/nexus/content/repositories/releases/ 187 group: cbegin 188 artifact: graven 189 type: maven 190 # Supports both releases and frozen dependencies 191 roles: 192 - release 193 - dependency 194 docker: 195 url: docker.io 196 group: cbegin 197 artifact: graven 198 type: docker 199 file: Dockerfile 200 # Docker repos only support releases 201 roles: 202 - release 203 ``` 204 ## Name and Version 205 206 ``` 207 name: graven 208 version: 0.6.6 209 ``` 210 211 The name of your project will initially be set by the parent directory in which it was created when the 212 `init` command was run. You can change it to whatever you like, but it's recommended to keep it simple, 213 short and alphabetic. It may be used for generating other values. 214 215 The version of your project follows a minimalist set of semantic version practices. That being: 216 217 ``` 218 M.m.p-Q 219 ``` 220 * M: Major version. Incremented when the software changes significantly and typically in incompatible ways. 221 * m: Minor version. Incremented when new features are added, and backward compatibility is maintained. 222 * p: Patch version. Incremented when bugs are fixed. Backward compatibility is typically maintained, but is 223 * sometimes unavoidably broken. 224 * Q: Qualifier. This is used to qualify a pre-release build and is typically something like RC1, DEV or TEST. 225 226 ## Artifacts 227 228 ``` 229 artifacts: 230 - classifier: darwin 231 targets: 232 - executable: bin/graven 233 package: . 234 flags: "" 235 env: {} 236 archive: tgz 237 resources: [] 238 env: 239 GOARCH: amd64 240 GOOS: darwin 241 - ... 242 ``` 243 Each entity listed in the artifacts section represents a distributable artifact that consists of 244 one or more executables built from a number of packages compiled with specified flags and environment 245 variables. The resulting binaries are packaged up in an archive format (e.g. zip or tar.gz) and 246 additional resources can be included in the archive, specified in the resources array. Both resources 247 and environment variables can be specified at higher levels to avoid duplication. More specific 248 environment variables will override broader scoped ones. The classifier specifies a suffix for the 249 artifact that is usually used to indicate the target platform, but can be used to indicate anything 250 that differs among distributable artifacts. 251 252 ## Repositories 253 254 ``` 255 repositories: 256 artifactory: 257 url: http://localhost:8081/artifactory/releases/ 258 group: cbegin 259 artifact: graven 260 type: maven 261 # Supports both releases and frozen dependencies 262 roles: 263 - release 264 - dependency 265 ... 266 ``` 267 268 In the repositories section you can define both release and dependency repositories. A release repository 269 is where this project will be released. A dependency repository will be used to store frozen vendor 270 dependencies, so that you don't need to check in your vendor directories or .freezer directory. 271 272 Three repository types are currently supported: Github, Docker and Maven (including Nexus and Artifactory). 273 Their capabilities and settings are summarized in the table below. 274 275 | Field | Github | Docker | Maven | 276 |-------|--------|--------|-------| 277 | type | github | docker | maven | 278 | url | Github API URL | Docker registry URL | Maven release URL | 279 | group | Owner | Repository | Group ID | 280 | artifact | Repo | Image Name | Artifact ID | 281 | roles | release | release | release, dependency | 282 | file | unused | Dockerfile | unused | 283 284 ### Authenticating 285 286 In order to use a repository for releases or dependencies, you'll need to authenticate. 287 To do so, simply call `graven repo --login --name [repo-name]`. The credentials you enter 288 will be stored in your home directory in the .graven.yaml file. Your credentials will be 289 obfuscated to discourage over-the-shoulder or casual exposure. Even though a strong 290 encryption algorithm is used, the key is not secure and thus you should treat it as 291 such. 292 293