github.com/jonsyu1/godel@v0.0.0-20171017211503-64567a0cf169/docs/Add-gödel.md (about) 1 Summary 2 ------- 3 To add gödel to a project, obtain the gödel distribution and copy the `godelw` file and `godel` directory to the project 4 directory. 5 6 Tutorial start state 7 -------------------- 8 9 * `$GOPATH/src/github.com/nmiyake/echgo` exists and is the working directory 10 11 ([Link](https://github.com/nmiyake/echgo/tree/54a23e62a4f9983d60939fdc8ed8dd59f81ddf7c)) 12 13 Add gödel to a project 14 ---------------------- 15 16 Add gödel to the project by downloading the distribution and copying the `godelw` script and `godel` directory into it. 17 This tutorial uses version 0.26.0, but the following steps are applicable for any version. 18 19 Download the distribution into a temporary directory and expand it: 20 21 ``` 22 ➜ export GODEL_VERSION=0.26.0 23 ➜ mkdir -p download 24 ➜ curl -L "https://palantir.bintray.com/releases/com/palantir/godel/godel/$GODEL_VERSION/godel-$GODEL_VERSION.tgz" -o download/godel-"$GODEL_VERSION".tgz 25 % Total % Received % Xferd Average Speed Time Time Time Current 26 Dload Upload Total Spent Left Speed 27 0 0 0 0 0 0 0 0 --:--:-- --:--:-- --:--:-- 0 28 100 10.7M 100 10.7M 0 0 3127k 0 0:00:03 0:00:03 --:--:-- 4433k 29 ➜ tar -xf download/godel-"$GODEL_VERSION".tgz -C download 30 ``` 31 32 Copy the contents of the `wrapper` directory (which contains `godelw` and `godel`) to the project directory: 33 34 ``` 35 ➜ cp -r download/godel-"$GODEL_VERSION"/wrapper/* . 36 ``` 37 38 Run `./godelw version` to verify that gödel was installed correctly. This command will download the distribution if the 39 distribution has not previously been installed locally: 40 41 ``` 42 ➜ ./godelw version 43 Downloading https://palantir.bintray.com/releases/com/palantir/godel/godel/0.26.0/godel-0.26.0.tgz to /Users/nmiyake/.godel/downloads/godel-0.26.0.tgz... 44 /Users/nmiyake/.godel/downloads/godel-0.26 100%[========================================================================================>] 10.74M 4.38MB/s in 2.5s 45 godel version 0.26.0 46 ``` 47 48 Technically, this is sufficient and we have a working gödel install. However, distributions that are downloaded do not 49 have a checksum set in `godel/config/godel.properties`: 50 51 ``` 52 ➜ cat godel/config/godel.properties 53 distributionURL=https://palantir.bintray.com/releases/com/palantir/godel/godel/0.26.0/godel-0.26.0.tgz 54 distributionSHA256= 55 ``` 56 57 For completeness, set the checksum: 58 59 ``` 60 ➜ echo 'distributionURL=https://palantir.bintray.com/releases/com/palantir/godel/godel/0.26.0/godel-0.26.0.tgz 61 distributionSHA256=c8d086da372e01ab671c57b16ab988fc2cca471906bdefa0bd1711d87883b32e' > godel/config/godel.properties 62 ``` 63 64 Now that gödel has been added to the project, remove the temporary directory and unset the version variable: 65 66 ``` 67 ➜ rm -rf download 68 ➜ unset GODEL_VERSION 69 ``` 70 71 Finally, commit the changes to the repository: 72 73 ``` 74 ➜ git add godel godelw 75 ➜ git commit -m "Add godel to project" 76 [master 6a73370] Add godel to project 77 10 files changed, 246 insertions(+) 78 create mode 100644 godel/config/check.yml 79 create mode 100644 godel/config/dist.yml 80 create mode 100644 godel/config/exclude.yml 81 create mode 100644 godel/config/format.yml 82 create mode 100644 godel/config/generate.yml 83 create mode 100644 godel/config/godel.properties 84 create mode 100644 godel/config/imports.yml 85 create mode 100644 godel/config/license.yml 86 create mode 100644 godel/config/test.yml 87 create mode 100755 godelw 88 ``` 89 90 gödel has now been added to the project and is ready to use. 91 92 Tutorial end state 93 -------------------- 94 95 * `$GOPATH/src/github.com/nmiyake/echgo` exists and is the working directory 96 * Project contains `godel` and `godelw` 97 98 ([Link](https://github.com/nmiyake/echgo/tree/6a73370d5b9c8c32ce1a5218938c922f1218db30)) 99 100 Tutorial next step 101 ------------------ 102 103 [Add Git hooks to enforce formatting](https://github.com/palantir/godel/wiki/Add-git-hooks) 104 105 More 106 ---- 107 108 ### Copying gödel from an existing project 109 110 If you have local projects that already use gödel, you can add gödel to a another project by copying the `godelw` and 111 `godel/config/godel.properties` files from the project that already has gödel. 112 113 For example, assume that `$GOPATH/src/github.com/nmiyake/echgo` exists in the current state of the tutorial and we want 114 to create another project at `$GOPATH/src/github.com/nmiyake/sample` that also uses gödel. This can be done as follows: 115 116 ``` 117 ➜ mkdir -p $GOPATH/src/github.com/nmiyake/sample && cd $_ 118 ➜ cp $GOPATH/src/github.com/nmiyake/echgo/godelw . 119 ➜ mkdir -p godel/config 120 ➜ cp $GOPATH/src/github.com/nmiyake/echgo/godel/config/godel.properties godel/config/ 121 ➜ ./godelw update 122 ``` 123 124 Verify that invoking `./godelw` works and that the `godel/config` directory has been populated with the default 125 configuration files: 126 127 ``` 128 ➜ ./godelw version 129 godel version 0.26.0 130 ➜ ls godel/config 131 check.yml exclude.yml generate.yml imports.yml test.yml 132 dist.yml format.yml godel.properties license.yml 133 ``` 134 135 Restore the workspace to the original state by setting the working directory back to the `echgo` project and removing 136 the sample project: 137 138 ``` 139 ➜ cd $GOPATH/src/github.com/nmiyake/echgo 140 ➜ rm -rf $GOPATH/src/github.com/nmiyake/sample 141 ``` 142 143 The steps above take the approach of copying the `godelw` file and `godel/config/godel.properties` file and running 144 `update` to ensure that all of the configuration is in its default state -- if the entire `godel/config` directory was 145 copied from the other project, then the current project would copy the other project's configuration as well, which is 146 most likely not the correct thing to do. 147 148 The `update` task ensures that the version of gödelw in the project matches the one specified by 149 `godel/config/godel.properties`. If the distribution is already downloaded locally in the local global gödel directory 150 (`~/.godel` by default) and matches the checksum specified in `godel.properties`, the required files are copied from the 151 local cache. If the distribution does not exist in the local cache or a checksum is not specified in `godel.properties`, 152 then the distribution is downloaded from the distribution URL. 153 154 ### Manually install gödel by moving it to the expected location 155 156 In the main tutorial above, we downloaded the gödel distribution using `curl`. However, when we ran `./godelw version`, 157 that task also downloaded the distribution. In most scenarios this is probably fine, but the download is not technically 158 required. The second download can be avoided by moving the downloaded distribution to the proper location in cache. 159 160 The `godelw` script expects the gödel distribution directory to exist at `$GODEL_HOME/dists/godel-$VERSION` (if 161 `GODEL_HOME` is undefined, then `~/.godel` is used). If the distribution directory is not present at that location, the 162 script downloads the distribution from the URL specified in `godel/config/godel.properties` and expands it. 163 164 If you have already downloaded the gödel distribution and do not want the `godelw` script to download it again, you can 165 manually expand the distribution directory to the expected location. 166 167 Repeat the initial steps to download the distribution: 168 169 ``` 170 ➜ export GODEL_VERSION=0.26.0 171 ➜ mkdir -p download 172 ➜ curl -L "https://palantir.bintray.com/releases/com/palantir/godel/godel/$GODEL_VERSION/godel-$GODEL_VERSION.tgz" -o download/godel-"$GODEL_VERSION".tgz 173 % Total % Received % Xferd Average Speed Time Time Time Current 174 Dload Upload Total Spent Left Speed 175 0 0 0 0 0 0 0 0 --:--:-- --:--:-- --:--:-- 0 176 100 10.7M 100 10.7M 0 0 12.3M 0 --:--:-- --:--:-- --:--:-- 18.5M 177 ``` 178 179 Since we have already downloaded and expanded the distribution, run the following to remove the existing state: 180 181 ``` 182 ➜ rm -rf ~/.godel/dists/godel-"$GODEL_VERSION" ~/.godel/downloads/godel-"$GODEL_VERSION".tgz 183 ``` 184 185 Now, expand the distribution to its expected destination location: 186 187 ``` 188 ➜ mkdir -p ~/.godel/dists 189 ➜ tar -xf download/godel-"$GODEL_VERSION".tgz -C ~/.godel/dists 190 ``` 191 192 Run `./godelw version` and verify that the distribution is not re-downloaded: 193 194 ``` 195 ➜ ./godelw version 196 godel version 0.26.0 197 ``` 198 199 The above is sufficient to ensure that executing `./godelw` for the given version will not re-download the distribution. 200 If you want to ensure that the `update` command does not re-download the distribution unnecessarily, then move the 201 distribution `.tgz` file to its expected location in the `~/.godel/downloads` directory: 202 203 ``` 204 ➜ mv download/godel-"$GODEL_VERSION".tgz ~/.godel/downloads/godel-"$GODEL_VERSION".tgz 205 ``` 206 207 Run the following to clean up our state: 208 209 ``` 210 ➜ rm -rf download 211 ➜ unset GODEL_VERSION 212 ``` 213 214 ### Specify the checksum in `godel/config/godel.properties` 215 216 If the `godelw` script cannot locate the `godel` binary, it downloads it from the URL specified in 217 `godel/godel.properties`. If a checksum is specified in `godel/config/godel.properties`, it is used to verify the 218 integrity and validity of the distribution downloaded from the URL. The checksum is also used by the `update` task -- if 219 the `update` task for a given version can find a download of the distribution in the downloads directory with a matching 220 checksum, it will be used to update the version of gödel (otherwise, the `update` task will always download the 221 distribution from the specified distribution URL). 222 223 The checksum is the SHA-256 checksum of the `.tgz` archive of the product. The checksum can be obtained from the 224 Bintray page for the distribution: 225 226  227 228 If a user has obtained a trusted distribution locally, it is also possible to manually compute the checksum. 229 230 Download the distribution by running the following: 231 232 ``` 233 ➜ export GODEL_VERSION=0.26.0 234 ➜ mkdir -p download 235 ➜ curl -L "https://palantir.bintray.com/releases/com/palantir/godel/godel/$GODEL_VERSION/godel-$GODEL_VERSION.tgz" -o download/godel-"$GODEL_VERSION".tgz 236 % Total % Received % Xferd Average Speed Time Time Time Current 237 Dload Upload Total Spent Left Speed 238 0 0 0 0 0 0 0 0 --:--:-- --:--:-- --:--:-- 0 239 100 10.7M 100 10.7M 0 0 9623k 0 0:00:01 0:00:01 --:--:-- 20.9M 240 ``` 241 242 The checksum can be computed using `openssl` or `shasum` as follows: 243 244 ``` 245 ➜ openssl dgst -sha256 download/godel-"$GODEL_VERSION".tgz 246 SHA256(download/godel-0.26.0.tgz)= c8d086da372e01ab671c57b16ab988fc2cca471906bdefa0bd1711d87883b32e 247 ➜ shasum -a 256 download/godel-"$GODEL_VERSION".tgz 248 c8d086da372e01ab671c57b16ab988fc2cca471906bdefa0bd1711d87883b32e download/godel-0.26.0.tgz 249 ``` 250 251 Once the digest value is obtained, it should be specified as the value of the `distributionSHA256=` key in 252 `godel/config/godel.properties`: 253 254 ``` 255 ➜ echo 'distributionURL=https://palantir.bintray.com/releases/com/palantir/godel/godel/0.26.0/godel-0.26.0.tgz 256 distributionSHA256=c8d086da372e01ab671c57b16ab988fc2cca471906bdefa0bd1711d87883b32e' > godel/config/godel.properties 257 ➜ cat godel/config/godel.properties 258 distributionURL=https://palantir.bintray.com/releases/com/palantir/godel/godel/0.26.0/godel-0.26.0.tgz 259 distributionSHA256=c8d086da372e01ab671c57b16ab988fc2cca471906bdefa0bd1711d87883b32e 260 ``` 261 262 Run the following to clean up our state: 263 264 ``` 265 ➜ rm -rf download 266 ➜ unset GODEL_VERSION 267 ```