# SDK Setup

The **Strategy SDK** is what you use to build **CryptoStruct** strategies.
This page covers the contents of the distribution, the toolchain you need,
and how to install it on Windows or Linux.

---

## SDK contents

The distribution includes the libraries, command-line tools, documentation,
and example projects.

{.compact}

| Component                       | Description                                                                             |
|---------------------------------|-----------------------------------------------------------------------------------------|
| `lib/strategy-api.jar`          | Core library containing all required interfaces and data types for strategy development |
| `lib/strategy-test.jar`         | Testing framework and utilities for writing unit tests                                  |
| `bin/backtest.jar`              | Executable tool for local strategy testing with recorded market data                    |
| `bin/scripttest.jar`            | Executable tool for running strategy test scripts                                       |
| `doc/trading-system-manual.pdf` | Complete system documentation                                                           |
| `doc/apidocs/index.html`        | API documentation for the strategy API library                                          |
| `example-strategies`            | Maven-based project demonstrating multiple strategies and feature usage                 |
| `simplespreader-strategy`       | Maven-based example strategy with test data and configuration                           |
| `template-strategy`             | Project template with Maven directory structure and empty strategy implementation       |
| `install.cmd`/`install.sh`      | Installation scripts for deploying SDK libraries to local Maven repository              |
| `CHANGES.md`                    | SDK version history and release notes                                                   |

---

## Requirements

Mandatory:

- JDK 25 or a compatible Java Development Kit
- The CryptoStruct Strategy SDK distribution

Recommended:

- A build system (Maven, Gradle, or Ant) for dependency management and
  reproducible builds
- An IDE (IntelliJ IDEA, Eclipse, or equivalent)
- Version control (Git, SVN, Perforce; not covered here)

> [!NOTE]
> The example strategies in the SDK use Maven. The instructions below use
> OpenJDK 25, Maven, and IntelliJ IDEA. Adapt as needed for your toolchain.

---

## Installation

### Windows

1. **Download the components**
    - Maven: [http://maven.apache.org/download.cgi](http://maven.apache.org/download.cgi)
      (binary zip archive)
    - Java 25 JDK: [https://jdk.java.net/archive/](https://jdk.java.net/archive/)
    - IntelliJ IDEA: [https://www.jetbrains.com/idea/download/](https://www.jetbrains.com/idea/download/)
      (Community Edition)

2. **Unpack Maven** to a directory such as
   `D:\Users\JohnDoe\Documents\apache-maven-3.8.6`.

3. **Unpack the JDK** to a directory such as
   `D:\Users\JohnDoe\Documents\jdk-25`.

4. **Configure environment variables**
    - `JAVA_HOME`: `D:\Users\JohnDoe\Documents\jdk-25`
    - `MAVEN_HOME`: `D:\Users\JohnDoe\Documents\apache-maven-3.8.6`

5. **Update PATH**
   ```
   PATH=<existing entries>;%JAVA_HOME%\bin;%MAVEN_HOME%\bin;
   ```

6. **Verify the install**
   Open a command prompt and run:
   ```bash
   javac --version
   mvn --version
   ```
   Each should print version information.

7. **Install the Strategy SDK**
   Run `install.cmd` from the SDK distribution. It installs the
   strategy-api and strategy-test libraries into the local Maven
   repository.

8. **Verify the build**
   Build the example strategy:
    - Change into the `simplespreader-strategy` directory
    - Run `mvn clean install`
    - Confirm that `simplespreader-strategy.jar` lands in `target/`

9. **Set up IntelliJ**
    - Install IntelliJ IDEA
    - Open `simplespreader-strategy/pom.xml` as a new project
    - Adapt `pom.xml` for your project

### Linux

The commands below assume Ubuntu 20.04. Adapt the package manager calls for
your distribution.

1. **Download IntelliJ IDEA**
   From [https://www.jetbrains.com/idea/download/](https://www.jetbrains.com/idea/download/)
   (Community Edition).

2. **Install OpenJDK 25**
   ```bash
   sudo apt-get install openjdk-25-jdk
   ```

3. **Install Maven**
   ```bash
   sudo apt-get install maven
   ```

4. **Install the Strategy SDK**
   Run `install.sh` from the SDK distribution. It installs the
   strategy-api and strategy-test libraries into the local Maven
   repository.

5. **Verify the build**
   Build the example strategy:
    - Change into the `simplespreader-strategy` directory
    - Run `mvn clean install`
    - Confirm that `simplespreader-strategy.jar` lands in `target/`

6. **Set up IntelliJ**
    - Install IntelliJ IDEA
    - Open `simplespreader-strategy/pom.xml` as a new project
    - Adapt `pom.xml` for your project

---

## Updating the SDK

You don't need to redo the full setup when updating. Three steps:

1. **Install the new SDK libraries**
   Run the install script (`install.cmd` on Windows, `install.sh` on Linux)
   from the new distribution. Versions coexist in the local Maven
   repository; new installs do not overwrite previous ones.

2. **Update the project version**

   If your `pom.xml` has an `sdk.version` property:

   ```xml
   <properties>
       <sdk.version>4.28.0</sdk.version>
   </properties>
   ```

   Update it to the new release:

   ```xml
   <properties>
       <sdk.version>4.29.0</sdk.version>
   </properties>
   ```

3. **Reload the project** in your IDE so the new dependency is picked up.

4. **Adapt the code** as needed. The SDK `CHANGES.md` lists API changes
   and new features in each release.

> [!TIP]
> If your project doesn't use the `sdk.version` property, switch to
> property-based versioning as shown below. It makes upgrades a one-line
> change.

---

## Version information in the manifest

The **Strategy Server** reads the strategy and SDK versions from the JAR
manifest. Adding both to the manifest makes deployments traceable.
Configure the Maven JAR plugin in your `pom.xml`.

### Basic configuration

```xml

<build>
  <plugins>
    <plugin>
      <groupId>org.apache.maven.plugins</groupId>
      <artifactId>maven-jar-plugin</artifactId>
      <configuration>
        <archive>
          <addMavenDescriptor>false</addMavenDescriptor>
          <manifestEntries>
            <strategyVersion>version-of-your-strategy</strategyVersion>
            <sdkVersion>version-of-used-SDK</sdkVersion>
          </manifestEntries>
        </archive>
      </configuration>
    </plugin>
  </plugins>
</build>
```

### Recommended: property-based versioning

To keep versions consistent across the build, define them once as Maven
properties:

```xml

<properties>
  <sdk.version>4.28.0</sdk.version>
</properties>

<dependencies>
<dependency>
  <groupId>com.cryptostruct</groupId>
  <artifactId>strategy-api</artifactId>
  <version>${sdk.version}</version>
</dependency>
</dependencies>

<build>
<plugins>
  <plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-jar-plugin</artifactId>
    <configuration>
      <archive>
        <addMavenDescriptor>false</addMavenDescriptor>
        <manifestEntries>
          <strategyVersion>${project.version}</strategyVersion>
          <sdkVersion>${sdk.version}</sdkVersion>
        </manifestEntries>
      </archive>
    </configuration>
  </plugin>
</plugins>
</build>
```

This pattern means:

- The SDK version is defined once and propagates to dependencies and the
  manifest.
- The strategy version comes from the Maven project version.
- Upgrades are a single-line change.

> [!NOTE]
> All example projects in the SDK use this pattern. They are the reference
> implementations to copy from.

If you use a build system other than Maven, adapt the manifest customisation
to your tool.