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  ![SHA checksum](images/tutorial/sha_checksum.png)
   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  ```