github.com/kyma-project/kyma-environment-broker@v0.0.1/scripts/README.md (about)

     1  # Generic makefile
     2  ## Overview
     3  
     4  `generic_make_go.mk` is a generic make file used to build, format and test Golang components.
     5  To use this makefile you need to have installed: [Docker](https://www.docker.com/get-started),
     6  [GNU Makefile](https://www.gnu.org/software/make/manual/make.html), version >=3.80 .
     7  
     8  ## Usage
     9  Syntax:
    10  ```bash
    11  make 'rule'
    12  ```
    13  
    14  Default makefile rule is `verify`, so when `make` is launched, the `verify` rule will be executed.
    15  `verify` rule will run tests, check formatting, check imports and run errcheck.
    16  It can be used instead of old `/before-commit.sh`.
    17  
    18  On CI all rules are run inside docker, because in CI environment we don't have `go` tools.
    19  
    20  ## Rules
    21  Rules without ending `-local` are run inside docker container.
    22  
    23  | RULE                              | BEHAVIOUR                                                      |
    24  |-----------------------------------|----------------------------------------------------------------|
    25  | check-fmt, check-fmt-local        | check `Go` files formatting                                    |
    26  | fmt, fmt-local                    | format `Go` files                                              |
    27  | check-imports, check-imports-local| check `Go` files imports                                       |
    28  | imports, imports-local            | format `Go` imports                                            |
    29  | gqlgen, gqlgen-local              | generate GraphQL schema                                        |
    30  | check-gqlgen, check-gqlgen-local  | check if graphql schema is up to date, run after `gqlgen` rule |
    31  | errcheck, errcheck-local          | run [errcheck](https://github.com/kisielk/errcheck)            |
    32  | test, test-local                  | run all unit tests                                             |
    33  | verify                            |  run `test`,`check-fmt`, `check-imports` and `errcheck`        |
    34  | resolve, resolve-local            | run `dep resolve --vendor-only -v                              |
    35  | ensure, ensure-local              | run `	dep ensure -v`                                           |
    36  | dep-status, dep-status-local      | run 	`dep status -v`                                          |
    37  | build, build-local                | build Go binary                                                |
    38  | vet, vet-local                    | run `go vet`                                                   |
    39  | build-image                       | build Docker image, used in CI environment                     |
    40  | push-image                        | push image to Image registry, used in CI environment           |
    41  
    42  ## How to use `generic_make_go.mk` in your application makefile
    43  Makefile must contains following vars and statement:
    44  ```makefile
    45  APP_NAME = App name
    46  APP_PATH = App path in repository
    47  BUILDPACK = BUILDPACK_IMAGE
    48  SCRIPTS_DIR = Path to generic makefile #e.g. $(realpath $(shell pwd)/../..)/scripts
    49  include $(SCRIPTS_DIR)/generic_make_go.mk
    50  ```
    51  available images are listed in [config.yaml](https://github.com/kyma-project/test-infra/blob/main/templates/config.yaml).
    52  
    53  ## How it works
    54  By example:
    55  When CI run`make release` the following steps are executed:
    56  - rule `release` depends on rules `resolve dep-status verify build-image push-image`
    57  - rule`resolve` does not appear in the Makefile. but it's generated.
    58  Notice this line of code:
    59  ```makefile
    60  MOUNT_TARGETS = build resolve ensure dep-status check-imports imports check-fmt fmt errcheck vet generate pull-licenses gqlgen
    61  $(foreach t,$(MOUNT_TARGETS),$(eval $(call buildpack-mount,$(t))))
    62  ```
    63  for resolve, and others targets defined in `MOUNT_TARGETS`, function `buildpack-mount` is callled, which dynamically defines new rule:
    64  ```makefile
    65  resolve:
    66      @echo make resolve
    67      @docker run $(DOCKER_INTERACTIVE) \
    68          -v $(COMPONENT_DIR):$(WORKSPACE_COMPONENT_DIR):delegated \
    69          $(DOCKER_CREATE_OPTS) make resolve-local
    70  ```
    71    as you can see, rule `resolve-local` is executed inside container.
    72  - if `resolve` pass, then the next rule will be executed.
    73  - if exit code of any rules is different than 0, makefile will abort execution and fail.
    74  
    75  Target types:
    76  - `MOUNT_TARGET` - mount component directory as volume to docker container
    77  - `COPY_TAGRT` - copy components files to docker container.
    78  
    79  ## How to adjust makefile
    80  ### How to disable current rule in local makefile
    81  In new Makefile add the following line: `{rule}: ;`.
    82  There will be warnings printed on console, but the rule will be disabled.
    83  
    84  ### How to add new local rule, which doesn't need `BUILDPACK`:
    85  Define rule in local makefile.
    86  Add this rule to one of the  global rule:
    87  ```makefile
    88  verify:: own-rule
    89  ```
    90  
    91  ### How to add new rule in local makefile, which needs buildpack:
    92  Define rule in local makefile and call function which will create the rule:
    93  ```makefile
    94  my-rule-local:
    95      do sth
    96  
    97  $(eval $(call BUILDPACK_FUNCTION,my-rule)) # function which will create the new rule
    98  ```
    99  
   100  Available BUILDPACK_FUNCTIONS:
   101  - buildpack-mount
   102  - buildpkac-cp-ro
   103  
   104  ### How to add new rule in generic makefile:
   105  Definie new local rule in `generic_make_go.mk` file:
   106  ```makefile
   107  your-rule-local:
   108      @echo do sth
   109  ```
   110  
   111  Append rule name to the `MOUNT_TARGETS` or `COPY_TARGETS` variables.