github.com/apprenda/kismatic@v1.12.0/docs/development/BUILDING.md (about)

     1  # Kismatic
     2  
     3  ## Pre-requisites
     4  - make
     5  - Docker
     6  
     7  ## Build using make
     8  
     9  ### Checking out the code
    10  
    11  If you're looking to contribute to Kismatic, the easiest way to get started is by using git.
    12  
    13  Assuming you have `git` and `go` installed on your machine, run
    14  
    15  ```bash
    16  ORG=your_github_account_name_here mkdir -p $(go env GOPATH)/src/github.com/$ORG && cd $(go env GOPATH)/src/github.com/$ORG && git clone https://github.com/$ORG/kismatic.git
    17  ```
    18  
    19  ### Building the distribution
    20  
    21  Next, assuming you have `docker` and `make` installed, run
    22  
    23  ```bash
    24  make dist
    25  ```
    26  
    27  This will build a distribution for the host running the command. I.E. if you run this from a mac, you'll receive an `out-darwin` package in the working directory. Likewise, building from a linux machine will produce an `out-linux` package in the working directory.
    28  
    29  If you do not wish to use `docker`, you can append `-host` to the command, and `make` will attempt to build locally. This is strongly discouraged, unless you really know what you're doing.
    30  
    31  I.E. 
    32  
    33  ```bash
    34  make dist-host
    35  ```
    36  
    37  ### Unit testing
    38  
    39  We appreciate any contributions to be made to include unit tests for changes being made.
    40  
    41  To run golang unit tests, simply run
    42  
    43  ```bash
    44  make test
    45  ```
    46  
    47  Again, you can append `-host` if you know what you're doing, and do not wish to run tests using docker.
    48  
    49  ### Integration testing
    50  
    51  Kismatic uses [Ginkgo](https://github.com/onsi/ginkgo) for BDD integration testing.
    52  We provide a guide for getting started with integration test: [here](docs/development/INTEGRATION_TESTING.md).
    53  
    54  Similar to the unit tests, we also provide `make` recipes for integration testing.
    55  To run the full suite of integration tests, run
    56  
    57  ```bash
    58  make integration-test
    59  ```
    60  
    61  The only caveat here is that since the integration tests are running from within a docker container, you need to have a linux distribution built.
    62  If you are on a mac, this requires you to `GOOS=linux make dist`. If you already know you plan on running integration tests, you can also use `make all` to build a darwin and linux distribution.
    63  
    64  Once again, you can append `-host` to run the tests outside of the container. Likewise, this requires you to have a distribution built for your host, I.E. a `make dist`
    65  
    66  ### Cutting down on iteration time
    67  
    68  Assuming you already have a `dist` built. You can run a vanilla
    69  
    70  ```bash
    71  make
    72  ```
    73  
    74  to update the most commonly changed components of the build.
    75  
    76  ### Cleaning
    77  
    78  If you want to run a clean build
    79  
    80  ```bash
    81  make clean
    82  ```
    83  
    84  will remove all build artifacts and distributions.
    85  
    86  If you simply want to remove the distribution, without cleaning any of the vendored tools, use
    87  
    88  ```bash
    89  make shallow-clean
    90  ```
    91  
    92  ### Advanced use cases
    93  
    94  If you're very familiar with unix systems, and want a more detailed layout of the build process the makefile is roughly sorted by how user-facing each recipe is.
    95  
    96  Be warned: the recipes near the bottom are intended to only be run on CI, and we do not guarantee any of them will work on your local.