> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/temporalio/temporal/llms.txt
> Use this file to discover all available pages before exploring further.

# Building from Source

> Learn how to build Temporal Server and related tools from source

This guide covers building Temporal Server binaries and related tools from source code.

## Initial Build

For your first build, use the default `make` command to install all build dependencies and compile the binaries:

```bash theme={null}
make
```

This target:

* Installs required build tools (protoc plugins, linters, etc.)
* Compiles all proto definitions
* Builds all binaries
* Runs the complete test suite

## Build Binaries Only

After the initial setup, you can build binaries without running tests:

```bash theme={null}
make bins
```

This builds the following binaries:

* `temporal-server` - Main server binary
* `temporal-cassandra-tool` - Cassandra schema management tool
* `temporal-sql-tool` - SQL database schema management tool
* `temporal-elasticsearch-tool` - Elasticsearch schema management tool
* `tdbg` - Temporal debugging tool

## Build Individual Binaries

You can build specific binaries individually:

### Temporal Server

```bash theme={null}
make temporal-server
```

The server is built with `CGO_ENABLED=0` by default. To enable CGO:

```bash theme={null}
CGO_ENABLED=1 make temporal-server
```

### Temporal Server (Debug Build)

```bash theme={null}
make temporal-server-debug
```

This builds the server with the `TEMPORAL_DEBUG` tag, which extends functional test timeouts for debugging sessions.

### Database Tools

**Cassandra Tool:**

```bash theme={null}
make temporal-cassandra-tool
```

**SQL Tool (MySQL/PostgreSQL):**

```bash theme={null}
make temporal-sql-tool
```

**Elasticsearch Tool:**

```bash theme={null}
make temporal-elasticsearch-tool
```

### Debugging Tool

```bash theme={null}
make tdbg
```

## Cross-Platform Builds

You can build for different platforms by setting `GOOS` and `GOARCH`:

```bash theme={null}
# Build for Linux AMD64
GOOS=linux GOARCH=amd64 make bins

# Build for macOS ARM64
GOOS=darwin GOARCH=arm64 make bins

# Build for Windows
GOOS=windows GOARCH=amd64 make bins
```

## Build Tags

Temporal Server uses several build tags:

* `disable_grpc_modules` - Excludes gRPC dependencies from cloud.google.com/go/storage, reducing binary size by \~16MB
* `test_dep` - Enables test hooks implementation for testing
* `TEMPORAL_DEBUG` - Extends timeouts for debugging
* `integration` - Includes integration test dependencies

Build tags are automatically applied by the Makefile. To apply them manually:

```bash theme={null}
go build -tags disable_grpc_modules,test_dep -o temporal-server ./cmd/server
```

## Proto Compilation

If you modify `.proto` files, regenerate the Go code:

```bash theme={null}
make proto
```

This command:

1. Lints proto definitions
2. Compiles proto files to Go code
3. Generates service clients and server interceptors
4. Generates search attribute helpers

## Code Generation

After modifying files with `//go:generate` directives, run:

```bash theme={null}
make go-generate
```

This regenerates:

* Mock implementations (using mockgen)
* String methods (using stringer)
* RPC wrappers

## Clean Build

To remove all build artifacts and start fresh:

```bash theme={null}
make clean
```

This removes:

* All binary files
* Build tools in `.bin/`
* Test output in `.testoutput/`
* Go test cache

## Build Verification

After building, verify the binaries:

```bash theme={null}
# Check server version
./temporal-server --version

# Check all binaries exist
ls -lh temporal-*
```

## Updating Dependencies

### API Dependencies

To update to the latest api and api-go:

```bash theme={null}
make update-go-api
```

### Minor Version Updates

Update all dependencies to their latest minor versions:

```bash theme={null}
make update-dependencies
```

### Major Version Updates

List available major version updates:

```bash theme={null}
make update-dependencies-major
```

## Working with Local API Changes

If you need to modify the gRPC/protobuf definitions alongside server changes:

<Steps>
  <Step title="Clone Related Repositories">
    ```bash theme={null}
    git clone https://github.com/temporalio/api.git
    git clone https://github.com/temporalio/api-go.git
    git clone https://github.com/temporalio/sdk-go.git
    ```
  </Step>

  <Step title="Make Changes to api Repository">
    Commit your changes to a branch in the `api` repository.
  </Step>

  <Step title="Update api-go">
    ```bash theme={null}
    cd api-go
    git submodule update --init --recursive
    git submodule set-url proto/api ../api
    git submodule set-branch --branch mystuff proto/api
    git submodule update --remote proto/api
    make proto
    ```
  </Step>

  <Step title="Point Server to Local Copies">
    Add to `go.mod` in the temporal repository:

    ```go theme={null}
    replace (
        go.temporal.io/api => ../api-go
        go.temporal.io/sdk => ../sdk-go
    )
    ```

    Then rebuild:

    ```bash theme={null}
    make proto && make bins
    ```
  </Step>
</Steps>

## Common Build Issues

### Protoc Not Found

If you see "protoc: command not found":

```bash theme={null}
# macOS
brew install protobuf

# Ubuntu
sudo apt install protobuf-compiler
```

### Out of Date Generated Code

If you see errors about generated code:

```bash theme={null}
make proto
make go-generate
```

### Build Cache Issues

```bash theme={null}
go clean -cache -modcache -testcache
make clean
make bins
```