> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ditto.live/llms.txt
> Use this file to discover all available pages before exploring further.

# Go - Public Preview

> You can integrate the Ditto SDK into Go projects to develop for Linux and macOS platforms.

<Callout icon="triangle-person-digging" color="#7C3AED" iconType="regular">
  The Go SDK is currently in **Public Preview** with version `5.0.0-go-preview.3`. If you encounter any issues or need assistance, please contact [Ditto Support](https://support.ditto.com).
</Callout>

The **Public Preview** of the Ditto Go SDK can be used for exploratory development and prototypes. Refer to the documentation for supported features. Future versions of the Ditto Go SDK may not be compatible with the current preview API.

## Adding the Ditto Go SDK to a Go Application

The Ditto Go SDK is available via a public GitHub repository: [https://github.com/getditto/ditto-go-sdk/](https://github.com/getditto/ditto-go-sdk/).

In the directory containing your application's `go.mod` file, run these commands to add the Ditto Go SDK and its dependencies:

```shell theme={null}
go get github.com/getditto/ditto-go-sdk/v5@latest
go mod tidy
```

Then, in any Go source file that uses the Ditto SDK, add this import for the `ditto` package:

```go theme={null}
import "github.com/getditto/ditto-go-sdk/v5/ditto"
```

```go Go theme={null}
const endpoint = "REPLACE_ME_WITH_YOUR_URL"
const id       = "REPLACE_ME_WITH_YOUR_DATABASE_ID"
const token    = "REPLACE_ME_WITH_YOUR_DEVELOPMENT_TOKEN"

config := ditto.DefaultDittoConfig().
    WithDatabaseID(id).
    WithConnect(&ditto.DittoConfigConnectServer{URL: endpoint})

dit, err := ditto.Open(config)
if err != nil {
    log.Fatalf("error: failed to open Ditto: %v", err)
}
defer dit.Close()

// Set up authentication expiration handler (required for server connections)
dit.Auth().SetExpirationHandler(
    func(d *ditto.Ditto, timeUntilExpiration time.Duration) {
        _, err := d.Auth().Login(token, ditto.DevelopmentAuthenticationProvider())
        if err != nil {
            log.Errorf("Authentication failed: %v", err)
        } else {
            log.Printf("Authentication succeeded")
        }
    })

if err := dit.Sync().Start(); err != nil {
    log.Errorf("error: failed to start sync: %v", err)
}
```

API documentation for the Go SDK can be found at [https://software.ditto.live/go/Ditto/5.0.0-go-preview.3/docs/github.com/getditto/ditto-go-sdk/v5/ditto/index.html](https://software.ditto.live/go/Ditto/5.0.0-go-preview.3/docs/github.com/getditto/ditto-go-sdk/v5/ditto/index.html).

## Installing the Ditto Go SDK Native Library

A native library provides Ditto Edge Sync Platform functionality, and must be linked into any application that uses the Ditto Go SDK.

### Downloading and Unpacking the Ditto Library

Download `Ditto.tar.gz` and unpack an archive containing the `libdittoffi.so` (Linux) or `libdittoffi.dylib` (macOS) shared library:

<CodeGroup>
  ```shell Linux-x86_64 theme={null}
  curl -O https://software.ditto.live/go/Ditto/5.0.0-go-preview.3/dist/libdittoffi-linux-x86_64.tar.gz && tar xvfz libdittoffi-linux-x86_64.tar.gz
  ```

  ```shell Linux-aarch64 theme={null}
  curl -O https://software.ditto.live/go/Ditto/5.0.0-go-preview.3/dist/libdittoffi-linux-aarch64.tar.gz && tar xvfz libdittoffi-linux-aarch64.tar.gz
  ```

  ```shell macOS-aarch64 theme={null}
  curl -O https://software.ditto.live/go/Ditto/5.0.0-go-preview.3/dist/libdittoffi-macos-aarch64.tar.gz && tar xvfz libdittoffi-macos-aarch64.tar.gz
  ```
</CodeGroup>

### Linking to the Ditto Shared Library at Build Time

When you build your application that uses the Ditto Go SDK, the linker needs to be able to find the native library.

#### Linux

The shared `libdittoffi.so` library will automatically be linked to by the Go SDK if it is in one of these locations:

* `/usr/local/lib`
* `/usr/lib`

Copy the unpacked `libdittoffi.so` to one of these locations for automatic linking.

If your `libdittoffi.so` is located somewhere else, you can pass that path to `go build` via the `-ldflags` option when you build your application.

```shell theme={null}
go build -ldflags='-extldflags "-L/path/to/my/lib/directory"'
```

#### macOS

The shared `libdittoffi.dylib` library will automatically be linked to by the Go SDK if it is in one of these locations:

* `/usr/local/lib`
* `/usr/lib`

Copy the unpacked `libdittoffi.dylib` to one of these locations for automatic linking.

If your `libdittoffi.dylib` is located somewhere else, you can pass that path to `go build` via the `-ldflags` option when you build your application.

```shell theme={null}
go build -ldflags='-extldflags "-L/path/to/my/lib/directory"'
```

### Linking to the Ditto Shared Library at Run Time

When an app that uses the Ditto Go SDK is run, the system must be able to find and load the native library.

#### Linux

Ubuntu/Debian will search in these directories at runtime by default:

* `/lib`
* `/lib64`
* `/usr/lib`
* `/usr/lib64`
* `/usr/local/lib`

If you don't deploy the `libdittoffi.so` library in one of those directories, set the `LD_LIBRARY_PATH` environment variable to the appropriate directory when running your application. For example:

```shell theme={null}
LD_LIBRARY_PATH=/path/to/my/lib/directory ./myapp
```

or

```shell theme={null}
export LD_LIBRARY_PATH=/path/to/my/lib/directory
./myapp
```

#### macOS

The macOS dynamic linker (dyld) checks environment variables during launch to determine where to find dynamic libraries. You can set `DYLD_LIBRARY_PATH` or `DYLD_FALLBACK_LIBRARY_PATH` to a colon-separated list of directories that contain shared libraries.

Alternatively, you can use the macOS `install_name_tool` utility to embed shared-library locations in the executable.

See the man pages for `dyld` and `install_name_tool` for details.

##### Using DYLD\_LIBRARY\_PATH

Set the `DYLD_LIBRARY_PATH` environment variable to the appropriate directory when running your application. For example:

```shell theme={null}
DYLD_LIBRARY_PATH=/path/to/my/lib/directory ./myapp
```

or

```shell theme={null}
export DYLD_LIBRARY_PATH=/path/to/my/lib/directory
./myapp
```

##### Using DYLD\_FALLBACK\_LIBRARY\_PATH

`DYLD_FALLBACK_LIBRARY_PATH` will be used by the loader if the library is not found in `DYLD_LIBRARY_PATH`.

In older versions of macOS, if this variable was unset the default value was `/usr/local/lib:/usr/lib`. However, in versions of macOS after Fall 2023, there is no longer a default value.

##### Using install\_name\_tool

The `install_name_tool` utility (included with macOS) can be used to add or change the rpaths recorded in an executable program. The rpaths will be searched, making setting of `DYLD_LIBRARY_PATH` unnecessary.

For example, if you want to search for shared libraries in the same directory containing the executable, do this:

```shell theme={null}
install_name_tool -add_rpath @executable_path ./myapp
```

If you want to use a particular directory, like `/usr/local/lib`, do this:

```shell theme={null}
install_name_tool -add_rpath /usr/local/lib ./myapp
```