github.com/apache/beam/sdks/v2@v2.48.2/go/BUILD.md (about)

     1  <!--
     2      Licensed to the Apache Software Foundation (ASF) under one
     3      or more contributor license agreements.  See the NOTICE file
     4      distributed with this work for additional information
     5      regarding copyright ownership.  The ASF licenses this file
     6      to you under the Apache License, Version 2.0 (the
     7      "License"); you may not use this file except in compliance
     8      with the License.  You may obtain a copy of the License at
     9  
    10        http://www.apache.org/licenses/LICENSE-2.0
    11  
    12      Unless required by applicable law or agreed to in writing,
    13      software distributed under the License is distributed on an
    14      "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
    15      KIND, either express or implied.  See the License for the
    16      specific language governing permissions and limitations
    17      under the License.
    18  -->
    19  
    20  # Go build
    21  
    22  This document describes the [Go](https://golang.org) code layout and build integration
    23  with Gradle.
    24  
    25  Goals:
    26  
    27   1. Go code can be built and tested using Gradle w/o special requirements.
    28   1. Go tools such as `go build`, `go test` and `go generate` work as usual.
    29   1. Go code can be pulled with `go get` from `github.com/apache/beam` for users.
    30   1. Go programs can used in docker container images.
    31  
    32  In short, the goals are to make both worlds work well.
    33  
    34  ## Go Modules
    35  
    36  Beam publishes a single Go Module for SDK developement and usage, in the `sdks` directory.
    37  This puts all Go code necessary for user pipeline development and for execution
    38  under the same module.
    39  This includes container bootloader code in the Java and Python SDK directories.
    40  
    41  Pipeline authors will require a dependency on `github.com/apache/beam/sdks/v2` in their
    42  `go.mod` files to use beam.
    43  
    44  ### Gradle integration
    45  
    46  To integrate with Gradle, we use a gradle plugin called GoGradle.
    47  However, we disable GoGradle vendoring in favour of using Go Modules
    48  for dependency management.
    49  GoGradle handles invoking the go toolchain or gradle and jenkins,
    50  using the same dependencies as SDK contributors and users.
    51  For the rare Go binary, such as the container boot loaders, it should be
    52  possible to build the same binary with both Gradle and the usual Go tool.
    53  
    54  The container build adds a small twist to the build integration, because
    55  container images use linux/amd64 but the development setup might not. We
    56  therefore additionally cross-compile Go binaries for inclusion into container
    57  images where needed, generally placed in `target/linux_amd64`.
    58  
    59  ### Go development setup
    60  
    61  To develop the SDK, it should be sufficient to clone the repository, make
    62  changes and execute tests from within the module directory (`<repo>/sdks/...`).
    63  
    64  Go users can just `go get` the code directly. For example:
    65  ```
    66  go get github.com/apache/beam/sdks/v2/go/pkg/beam
    67  ```
    68  Developers must invoke Go for cross-compilation manually, if desired.
    69  
    70  If you make changes to .proto files, you will need to rebuild the generated code.
    71  Consult `pkg/beam/model/PROTOBUF.md`.
    72  
    73  If you make changes to .tmpl files, then add the specialize tool to your path.
    74  You can install specialize using:
    75  ```
    76  go get github.com/apache/beam/sdks/v2/go/cmd/specialize
    77  ```
    78  Add it to your path:
    79  ```
    80  export PATH=$PATH:$GOROOT/bin:$GOPATH/bin
    81  ```