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  ```