github.com/oNaiPs/go-generate-fast@v0.3.0/README.md (about)

     1  # go-generate-fast
     2  
     3  [![build](https://github.com/oNaiPs/go-generate-fast/actions/workflows/build-test.yml/badge.svg)](https://github.com/oNaiPs/go-generate-fast/actions?query=branch%main)
     4  [![Go Report
     5  Card](https://goreportcard.com/badge/github.com/oNaiPs/go-generate-fast)](https://goreportcard.com/report/github.com/oNaiPs/go-generate-fast)
     6  
     7  🚀 Shave off minutes and turn them into seconds for your go generation step 🚀.
     8  
     9  `go-generate-fast` serves as a drop-in replacement for [go
    10  generate](https://pkg.go.dev/cmd/go#hdr-Generate_Go_files_by_processing_source).
    11  
    12  Smart enough to understand if your generated files have changed or not,
    13  `go-generate-fast` can circumvent running unaltered scripts, offering a
    14  significant speed boost by harnessing smart caching mechanisms.
    15  
    16  <https://github.com/oNaiPs/go-generate-fast/assets/374130/396a0160-90f8-46d0-a05c-783d127a384e>
    17  
    18  ## Features
    19  
    20  - **Effortless Integration**: Seamlessly integrate it with your workflow through
    21    [comment directives](#usage).
    22  - **Tool-awareness**: Executes tools only when necessary, based on changes
    23    identified in input files.
    24  - **Comprehensive Tool Compatibility**: Works with a variety of `go:generate`
    25    tools, including
    26    [stringer](https://godoc.org/golang.org/x/tools/cmd/stringer),
    27    [mockgen](https://github.com/golang/mock/tree/master/mockgen),
    28    [esc](https://github.com/mjibson/esc), and [more](#supported-tools).
    29  - **Support for Custom Scripts**: Manually specify inputs and outputs if needed.
    30  
    31  ## Install
    32  
    33  ```bash
    34  go install github.com/oNaiPs/go-generate-fast
    35  ```
    36  
    37  ## Usage
    38  
    39  Replace the traditional `go generate` command with `go-generate-fast` in your
    40  scripts to leverage its benefits.
    41  
    42  Typical command invocation is as follows:
    43  
    44  ```bash
    45  go-generate-fast [file.go... | packages]
    46  ```
    47  
    48  ## Supported Tools
    49  
    50  `go-generate-fast` automatically detects the input/output files for the
    51  following tools:
    52  
    53  - [stringer](https://godoc.org/golang.org/x/tools/cmd/stringer): Automated
    54    generation of methods satisfying the `fmt.Stringer` interface.
    55  - [protobuf](https://developers.google.com/protocol-buffers): Go code generation
    56    for protobuf files
    57  - [gqlgen](https://gqlgen.com/): Go code generation for GraphQL APIs
    58  - [mockgen](https://github.com/uber-go/mock): Mock class generation for
    59    interfaces
    60  - [moq](https://github.com/matryer/moq): Interface mocking tool for go generate
    61  - [esc](https://github.com/mjibson/esc): Embedding static files in Go binaries
    62  - [go-bindata](https://github.com/go-bindata/go-bindata): Turn data file into go
    63    code.
    64  - [genny](https://github.com/cheekybits/genny): Elegant generics for Go.
    65  - [controller-gen](https://book.kubebuilder.io/reference/controller-gen) Generates utility code and Kubernetes YAML.
    66  
    67  Above commands can be called in binary form, or with go run. E.g.:
    68  
    69  ```go
    70  //go:generate stringer
    71  
    72  OR
    73  
    74  //go:generate go run golang.org/x/tools/cmd/stringer[@latest]
    75  ```
    76  
    77  ### Custom Input/Output Files
    78  
    79  If you are using a custom or currently unsupported script/tool, you can manually
    80  add files as demonstrated below:
    81  
    82  ```go
    83  //go:generate_input doc/gen_docs.go commands/**/*.go
    84  //go:generate_output doc/man/*.1 doc/md/*.md
    85  //go:generate go run doc/gen_docs.go
    86  
    87  //go:generate_input images/*.png
    88  //go:generate_output images/*.jpeg
    89  //go:generate bash convert_images.sh
    90  ```
    91  
    92  Just before your `go:generate` command, you can add any `go:generate_input` or
    93  `go:generate_output` directives accurately. The input files influence the
    94  tool/script (re)execution, while output files contain the results. If one or
    95  more input files change, the command reruns and stores the output files in the
    96  [cache directory](#configuration).
    97  
    98  ## Configuration
    99  
   100  Various environment variables are available for configuration:
   101  
   102  - `GO_GENERATE_FAST_DIR`: Sets the base directory for configurations and
   103    caching. Default locations differ by OS:
   104    - Linux: `$HOME/.config/go-generate-fast`
   105    - Darwin: `$HOME/Library/Application Support/go-generate-fast`
   106    - Windows: `%AppData%\go-generate-fast`
   107  
   108  - `GO_GENERATE_FAST_CACHE_DIR`: Defines the cache files location. Default is
   109    `$GO_GENERATE_FAST_DIR/cache/`.
   110  - `GO_GENERATE_FAST_DEBUG`: Enables debugging logs.
   111  - `GO_GENERATE_FAST_DISABLE`: Completely ignores caching.
   112  - `GO_GENERATE_FAST_READ_ONLY`: Uses the existing cache but prevents any new
   113    cache entries.
   114  - `GO_GENERATE_FAST_FORCE_USE_CACHE`: Forceably uses cache. If it does not exist, the command fails.
   115  - `GO_GENERATE_FAST_RECACHE`: Sets the cache to overwrite existing entries. The
   116    new results will be cached.
   117  
   118  ## How it Works
   119  
   120  `go-generate-fast` makes regeneration faster by reusing previously outputs when
   121  the same input files are used again. This approach is identified via the
   122  creation of a unique hash that combines inputs,outputs and other metadata. The
   123  underlying concept is similar to the C/C++ compiler cache
   124  [ccache](https://ccache.dev/).
   125  
   126  ## Contributing
   127  
   128  We highly appreciate community contributions! Please create an issue or submit a
   129  pull request for any suggestions or issues.
   130  
   131  ## License
   132  
   133  `go-generate-fast` is licensed under the [MIT License](LICENSE).