github.com/jdhenke/godel@v0.0.0-20161213181855-abeb3861bf0d/README.md (about) 1 gödel 2 ===== 3 4 [](https://bintray.com/palantir/releases/godel/_latestVersion) 5 [](https://circleci.com/gh/palantir/godel) 6 7 gödel is a Go build tool that provides tasks for configuring, formatting, checking, testing, building and publishing Go 8 projects in a declarative, consistent and reproducible manner across different platforms and environments. gödel can be 9 used in both local development environments and for verifying the correctness of project in CI environments. gödel uses 10 declarative configuration to define the parameters for a project and provides an executable that orchestrates build 11 tasks using standard Go commands. It centralizes project configuration and eliminates the need for custom build scripts 12 that conflate configuration with logic. gödel is designed to be portable, fast and lightweight -- adding it to a project 13 consists of copying a single file and directory into the project and adds less than 50kb of version-controlled material. 14 15 Features 16 -------- 17 * Add to a project by copying the `godelw` script and the `godel` configuration directory into a project 18 * `./godelw git-hooks` installs Git commit hook that formats files on commit 19 * `./godelw idea` creates and configures an IntelliJ IDEA project for the project 20 * Supports configuring directories and files that should be excluded by the tool (vendor directory is excluded by default) 21 * `./godelw format` formats all code in a project 22 * `./godelw check` runs a variety of code linting checks on all the code in a project 23 * `./godelw license` applies a specified license header to all Go files in a project 24 * Supports configuring custom license headers for specific directories or files 25 * `./godelw test` runs the tests in the project 26 * Configuration can be used to define test sets (such as integration tests) and run specific test sets 27 * Supports outputting the test results in a JUnit XML format 28 * `./godelw build` builds executables for `main` packages in the project 29 * Supports cross-platform compilation 30 * Supports configuration of `ldflag` for version and other variables 31 * Installs packages by default to speed up repeated builds 32 * `./godelw dist` creates distribution files for products 33 * Supports creating `tgz` and `rpm` distributions 34 * Supports customizing creation of distribution using scripts 35 * `./godelw publish` publishes artifacts to Bintray or Artifactory 36 * `palantir/godel/pkg/products` package provides a mechanism to easily write integration tests for gödel projects 37 * Provides a function that builds the product executable or distribution and provides a path to invoke it 38 * `./godelw update` updates gödel to the version specified in `godel/config/godel.properties` 39 * `./godelw github-wiki` mirrors a documents directory to a GitHub Wiki repository 40 * `./godelw verify` runs the `format`, `import`, `license`, `check` and `test` tasks 41 * Can be used locally as a single command to apply changes and run checks 42 * Can be used in CI to verify that a project is in the proper state without applying changes 43 44 This list is not exhaustive -- run `./godelw --help` for a list of all of the available commands. 45 46 Documentation 47 ------------- 48 Documentation for this project is in the `docs` directory and the [GitHub Wiki](https://github.com/palantir/godel/wiki) 49 (the GitHub Wiki mirrors the contents of the `docs` directory). 50 51 Development 52 ----------- 53 The code for the tasks provided by gödel is in the `cmd` directory. gödel tasks fall into 2 categories: those whose 54 functionality are implemented directly in gödel packages and those whose functionality is implemented by a sub-program 55 that exposes its tasks as library functions that are directly callable. 56 57 The `app.go` file in the top-level `godel` package registers the top-level tasks available in the CLI. It registers the 58 tasks whose functionality is implemented directly in gödel directly. The tasks provided by sub-programs are defined in 59 `cmd/clicmds/cfgcli.go`. 60 61 After making changes to the code, run `./godelw verify` to format the code, apply the proper license headers, update 62 dependency information, run code linting checks and all unit tests. 63 64 gödel also defines integration tests in the `test/integration` directory. The tests in this file create a distribution 65 of gödel and run tests against it. Run `./godelw test --tags=integration` to run the integration tests (the integration 66 tests are not run by `./godelw verify` or `./godelw test` by default). 67 68 ### Sub-applications in the apps directory 69 The functionality for some gödel tasks are provided by sub-applications. `distgo`, `gonform`, `gunit` and `okgo` are 70 such sub-applications and are located in the `apps` directory. These sub-applications can be compiled and run as self- 71 contained CLI applications, but also expose functionality as libraries. 72 73 Changes that are made in these sub-applications directly impact gödel, and many of the gödel integration tests test the 74 functionality provided by these sub-applications. The sub-applications also have their own set of tests. Each of the 75 sub-applications in the `apps` directory have their own test suite that is the name of the sub-application and can be 76 invoked using its tag -- for example, to run the tests for `distgo`, run `./godelw test --tags=distgo`. 77 78 Refer to the README files in the sub-applications for more information on application-specific development. 79 80 ### Sub-applications outside of the repository 81 Some tasks such as `imports` and `license` use sub-applications that are defined outside of the repository (in this 82 case, `gocd` and `golicense`, respectively) and vendor the sub-applications to use their functionality. Changing these 83 tasks is akin to changing a vendored library -- locate the original repository for the library, make changes there and 84 then update the vendored library in gödel. 85 86 License 87 ------- 88 This project is made available under the [Apache 2.0 License](http://www.apache.org/licenses/LICENSE-2.0).