github.com/jonsyu1/godel@v0.0.0-20171017211503-64567a0cf169/docs/Dist.md (about) 1 Summary 2 ------- 3 `./godelw dist` builds distributions for the products in the project based on the dist configuration. 4 5 Tutorial start state 6 -------------------- 7 8 * `$GOPATH/src/github.com/nmiyake/echgo` exists and is the working directory 9 * Project contains `godel` and `godelw` 10 * Project contains `main.go` 11 * Project contains `.gitignore` that ignores IDEA files 12 * Project contains `echo/echo.go`, `echo/echo_test.go` and `echo/echoer.go` 13 * `godel/config/dist.yml` is configured to build `echgo` 14 * Project is tagged as 0.0.1 15 16 ([Link](https://github.com/nmiyake/echgo/tree/7799802bb82db52e99dda67edf9c98333b28fca3)) 17 18 Dist 19 ---- 20 21 Now that we have created a product and defined a build configuration for it, we can move to defining how the 22 distribution for the product is created. At the bare minimum, most hosting services typically require a product to be 23 packaged as a `tgz` (or some other archive format). Additionally, some products may want the distribution to contain 24 artifacts other than the binary (such as documentation or resources). 25 26 Start by running `./godelw dist` in the project to observe the default behavior: 27 28 ``` 29 ➜ ./godelw dist 30 Creating distribution for echgo at /Volumes/git/go/src/github.com/nmiyake/echgo/dist/echgo-0.0.1-darwin-amd64.tgz, /Volumes/git/go/src/github.com/nmiyake/echgo/dist/echgo-0.0.1-linux-amd64.tgz 31 Finished creating distribution for echgo 32 ``` 33 34 The default dist settings creates a tgz distribution for each `bin` output for its declared OS/architecture pairs (or 35 the OS/architecture of the host platform if none are specified) that contains only the binary for the target platform. 36 In this case, because the build configuration specified that the product should be built for `darwin-amd64` and 37 `linux-amd64`, the task created distribution artifacts for those two targets. The example above performed only the 38 distribution task because the binaries for the products were already present and up-to-date. If this were not the case, 39 the `dist` task would build the required binaries before running. 40 41 Similarly to the `build` command, `dist` writes its output to the `dist` directory by default (the output directory can 42 be configured using the `output-dir` property). The `./godelw clean` command will remove any outputs created by the 43 `dist` task. To ensure that distribution contents are not tracked in git, add `/dist/` to the `.gitignore` file: 44 45 ``` 46 ➜ echo '/dist/' >> .gitignore 47 ➜ git add .gitignore 48 ➜ git commit -m "Update .gitignore to ignore dist directory" 49 [master 0b66d9a] Update .gitignore to ignore dist directory 50 1 file changed, 1 insertion(+) 51 ➜ git status 52 On branch master 53 nothing to commit, working directory clean 54 ``` 55 56 For this product, the default distribution mechanism is suitable. However, if we were to want to either choose a 57 different type of distribution or customize the parameters of this distribution, we would specify the `dist` 58 configuration for the product explicitly. Update the `dist.yml` to explicitly configure the dist parameters of the 59 product: 60 61 ``` 62 ➜ echo 'products: 63 echgo: 64 build: 65 main-pkg: . 66 version-var: main.version 67 os-archs: 68 - os: darwin 69 arch: amd64 70 - os: linux 71 arch: amd64 72 dist: 73 dist-type: 74 type: os-arch-bin' > godel/config/dist.yml 75 ``` 76 77 Commit this update: 78 79 ``` 80 ➜ git add godel/config/dist.yml 81 ➜ git commit -m "Specify dist configuration" 82 [master 55182ff] Specify dist configuration 83 1 file changed, 3 insertions(+) 84 ``` 85 86 On its own, this functionality may not seem very spectacular. However, these distribution artifacts can be used as 87 inputs to other tasks such as `publish` and `docker`. Furthermore, for more complicated distributions, it can be useful 88 to have the logic for creating distributions centrally managed in the configuration. 89 90 Tutorial end state 91 ------------------ 92 93 * `$GOPATH/src/github.com/nmiyake/echgo` exists and is the working directory 94 * Project contains `godel` and `godelw` 95 * Project contains `main.go` 96 * Project contains `.gitignore` that ignores IDEA files 97 * Project contains `echo/echo.go`, `echo/echo_test.go` and `echo/echoer.go` 98 * `godel/config/dist.yml` is configured to build `echgo` 99 * Project is tagged as 0.0.1 100 * `godel/config/dist.yml` is configured to create distributions for `echgo` 101 102 ([Link](https://github.com/nmiyake/echgo/tree/55182ff79dd28048782fb240920d6f2d90b453da)) 103 104 Tutorial next step 105 ------------------ 106 107 [Publish](https://github.com/palantir/godel/wiki/Publish) 108 109 More 110 ---- 111 112 ### Create dists for specific products 113 114 By default, `./godelw dist` will create distributions for all of the products defined for a project. Product names can 115 be specified as arguments to create distributions for only those products. For example, if the `echgo` project defined 116 multiple products, you could specify that you want to only create the distribution for `echgo` by running the following: 117 118 ``` 119 ➜ ./godelw dist echgo 120 Building echgo for darwin-amd64 at /Volumes/git/go/src/github.com/nmiyake/echgo/build/0.0.1-2-g55182ff/darwin-amd64/echgo 121 Building echgo for linux-amd64 at /Volumes/git/go/src/github.com/nmiyake/echgo/build/0.0.1-2-g55182ff/linux-amd64/echgo 122 Finished building echgo for linux-amd64 (0.373s) 123 Finished building echgo for darwin-amd64 (0.375s) 124 Creating distribution for echgo at /Volumes/git/go/src/github.com/nmiyake/echgo/dist/echgo-0.0.1-2-g55182ff-darwin-amd64.tgz, /Volumes/git/go/src/github.com/nmiyake/echgo/dist/echgo-0.0.1-2-g55182ff-linux-amd64.tgz 125 Finished creating distribution for echgo 126 ``` 127 128 ### Use a dist type that packages all binaries together 129 130 The `os-arch-bin` distribution type creates a separate distribution for each OS/architecture combination. However, in 131 some instances, it may be desirable to have a single distribution that contains the binaries for all of the target 132 platforms. The `bin` type can be used to do this. 133 134 Update the configuration as follows: 135 136 ``` 137 ➜ echo 'products: 138 echgo: 139 build: 140 main-pkg: . 141 version-var: main.version 142 os-archs: 143 - os: darwin 144 arch: amd64 145 - os: linux 146 arch: amd64 147 dist: 148 dist-type: 149 type: bin' > godel/config/dist.yml 150 ``` 151 152 Clean the previous output and run `./godelw dist` to generate a distribution using the new configuration: 153 154 ``` 155 ➜ ./godelw clean 156 ➜ ./godelw dist 157 Building echgo for linux-amd64 at /Volumes/git/go/src/github.com/nmiyake/echgo/build/0.0.1-2-g55182ff.dirty/linux-amd64/echgo 158 Building echgo for darwin-amd64 at /Volumes/git/go/src/github.com/nmiyake/echgo/build/0.0.1-2-g55182ff.dirty/darwin-amd64/echgo 159 Finished building echgo for linux-amd64 (0.366s) 160 Finished building echgo for darwin-amd64 (0.371s) 161 Creating distribution for echgo at /Volumes/git/go/src/github.com/nmiyake/echgo/dist/echgo-0.0.1-2-g55182ff.dirty.tgz 162 Finished creating distribution for echgo 163 ``` 164 165 Examine the contents of the `dist` directory: 166 167 ``` 168 ➜ tree dist 169 dist 170 ├── echgo-0.0.1-2-g55182ff.dirty 171 │ └── bin 172 │ ├── darwin-amd64 173 │ │ └── echgo 174 │ └── linux-amd64 175 │ └── echgo 176 └── echgo-0.0.1-2-g55182ff.dirty.tgz 177 178 4 directories, 3 files 179 ``` 180 181 The distribution consists of a product directory that contains a `bin` directory that has a directory for each target 182 OS/architecture that contains the executable that was built for that target. The `tgz` file is an archive that contains 183 the top-level directory. 184 185 Revert these changes by running the following: 186 187 ``` 188 ➜ git checkout -- godel/config/dist.yml 189 ``` 190 191 ### Specify `input-dir` to copy the contents of a local directory into the distribution 192 193 Distributions may want to include static resources such as documentation, scripts or other resources as part of their 194 distribution. This can be done by having the resources in a directory in the project and specifying that directory as an 195 input directory for the distribution. 196 197 Run the following command to create a `resources` directory that contains a README to include with the binaries: 198 199 ``` 200 ➜ mkdir -p resources 201 ➜ echo 'echgo is a program that echoes its arguments.' > resources/README.md 202 ``` 203 204 Run the following to update the dist configuration to copy the contents of `resources` into its distribution directory: 205 206 ``` 207 ➜ echo 'products: 208 echgo: 209 build: 210 main-pkg: . 211 version-var: main.version 212 os-archs: 213 - os: darwin 214 arch: amd64 215 - os: linux 216 arch: amd64 217 dist: 218 input-dir: resources 219 dist-type: 220 type: bin' > godel/config/dist.yml 221 ``` 222 223 The `input-dir: resources` line configures the task to copy all of the contents of the `resources` directory into the 224 distribution directory (the value of the `input-dir` parameter is the path the to the input directory relative to the 225 base directory of the project). 226 227 Run the following to clean the `dist` directory and run the `dist` task to generate the distribution outputs: 228 229 ``` 230 ➜ ./godelw clean 231 ➜ ./godelw dist 232 Building echgo for linux-amd64 at /Volumes/git/go/src/github.com/nmiyake/echgo/build/0.0.1-2-g55182ff.dirty/linux-amd64/echgo 233 Building echgo for darwin-amd64 at /Volumes/git/go/src/github.com/nmiyake/echgo/build/0.0.1-2-g55182ff.dirty/darwin-amd64/echgo 234 Finished building echgo for darwin-amd64 (0.352s) 235 Finished building echgo for linux-amd64 (0.355s) 236 Creating distribution for echgo at /Volumes/git/go/src/github.com/nmiyake/echgo/dist/echgo-0.0.1-2-g55182ff.dirty.tgz 237 Finished creating distribution for echgo 238 ``` 239 240 Verify that the distribution directory contains `README.md`: 241 242 ``` 243 ➜ tree dist 244 dist 245 ├── echgo-0.0.1-2-g55182ff.dirty 246 │ ├── README.md 247 │ └── bin 248 │ ├── darwin-amd64 249 │ │ └── echgo 250 │ └── linux-amd64 251 │ └── echgo 252 └── echgo-0.0.1-2-g55182ff.dirty.tgz 253 254 4 directories, 4 files 255 ``` 256 257 The input directory can contain any content (including directories or nested directories). 258 259 Revert these changes by running the following: 260 261 ``` 262 ➜ rm -rf resources 263 ➜ git checkout -- godel/config/dist.yml 264 ``` 265 266 ### Specify a script to run arbitrary actions during the distribution step 267 268 Distributions may need to perform various actions as part of their distribution process that go beyond requiring static 269 files. For example, a distribution step may require downloading a file, moving files or directories to specific 270 locations, computing checksums and writing them to a file, etc. In order to support such scenarios, the `dist` block 271 allows a distribution script to be specified. The distribution script is run after the basic `dist` actions have run but 272 before the distribution output directory has been archived. 273 274 Run the following to update the dist configuration: 275 276 ``` 277 ➜ echo 'products: 278 echgo: 279 build: 280 main-pkg: . 281 version-var: main.version 282 os-archs: 283 - os: darwin 284 arch: amd64 285 - os: linux 286 arch: amd64 287 dist: 288 script: | 289 echo "Distribution created at $(date)" > $DIST_DIR/timestamp.txt 290 mv $DIST_DIR/bin $DIST_DIR/binaries 291 dist-type: 292 type: bin' > godel/config/dist.yml 293 ``` 294 295 The specified script writes a file called "timestamp.txt" that contains the output of running `date` and also moves the 296 renames the `bin` directory to be `binaries` instead. `$DIST_DIR` is an environment variable that is set before the 297 script is run that contains the absolute path to the directory created for the distribution. Refer to the 298 [dist config documentation](https://godoc.org/github.com/palantir/godel/apps/distgo/config#Dist) for a full description 299 of the environment variables that are available to the script. 300 301 Remove any previous distribution output and run the `dist` command: 302 303 ``` 304 ➜ ./godelw clean 305 ➜ ./godelw dist 306 Building echgo for linux-amd64 at /Volumes/git/go/src/github.com/nmiyake/echgo/build/0.0.1-2-g55182ff.dirty/linux-amd64/echgo 307 Building echgo for darwin-amd64 at /Volumes/git/go/src/github.com/nmiyake/echgo/build/0.0.1-2-g55182ff.dirty/darwin-amd64/echgo 308 Finished building echgo for darwin-amd64 (0.374s) 309 Finished building echgo for linux-amd64 (0.375s) 310 Creating distribution for echgo at /Volumes/git/go/src/github.com/nmiyake/echgo/dist/echgo-0.0.1-2-g55182ff.dirty.tgz 311 Finished creating distribution for echgo 312 ``` 313 314 Verify that `timestamp.txt` was created and that the distribution directory contains a `binaries` directory rather than 315 a `bin` directory: 316 317 ``` 318 ➜ tree dist 319 dist 320 ├── echgo-0.0.1-2-g55182ff.dirty 321 │ ├── binaries 322 │ │ ├── darwin-amd64 323 │ │ │ └── echgo 324 │ │ └── linux-amd64 325 │ │ └── echgo 326 │ └── timestamp.txt 327 └── echgo-0.0.1-2-g55182ff.dirty.tgz 328 329 4 directories, 4 files 330 ``` 331 332 You can also verify that the contents of `timestamp.txt` is correct: 333 334 ``` 335 ➜ cat dist/echgo-"$(./godelw project-version)"/timestamp.txt 336 Distribution created at Mon Oct 16 15:40:44 PDT 2017 337 ``` 338 339 Revert these changes by running the following: 340 341 ``` 342 ➜ git checkout -- godel/config/dist.yml 343 ```