BraneTechnologies Documentation

Creating Your First Brane SDK Project #

Let’s create a basic project structure that follows Brane SDK conventions.

Basic Project Layout #

A typical Brane SDK project follows this hierarchical structure:

MyProject/
├── build.gradle         # Root build file
├── settings.gradle      # Project settings
├── gradle.properties    # Gradle and AWS credentials
├── gradlew              # Gradle wrapper script
├── gradlew.bat          # Gradle wrapper for Windows
└── modules/
    └── hello-world/     # Sample application module
        ├── build.gradle # Module configuration
        └── src/
            └── main/
                ├── c/   # C source files
                └── cpp/ # C++ source files

This organization allows for clean separation of concerns while enabling unified building across the entire project.

Configuration Files #

Three key configuration files control your Brane SDK project:

1. Root build.gradle

The root build.gradle file configures access to the Brane plugin repository and establishes project-wide settings. Here’s a comprehensive example with annotations:

// Configure build script repositories and dependencies
buildscript {
    repositories {
        // Brane plugin repository (requires AWS credentials)
        maven {
            url "s3://com.brane.repository.maven/release/"
            credentials(AwsCredentials) {
                // AWS credentials can be provided as environment variables or in gradle.properties
                accessKey = System.getenv('AWS_ACCESS_KEY_ID') ?: findProperty('aws_access_key_id')
                secretKey = System.getenv('AWS_SECRET_ACCESS_KEY') ?: findProperty('aws_secret_access_key')
            }
        }
        // Public repositories for additional dependencies
        mavenCentral()
        jcenter()
    }
    
    // Required dependencies for the build process
    dependencies {
        // Brane-Builder plugin - core of the SDK
        classpath 'com.brane.plugins:brane-builder:2.0.1'
        // Apache Velocity for template processing
        classpath 'org.apache.velocity:velocity:1.7'
        // Add any additional build-time dependencies here
    }
}

// Common configurations that apply to all projects
allprojects {
    repositories {
        mavenCentral()
    }
}

2. Root settings.gradle

The settings.gradle file defines your project’s name and the modules to include in the build. This file controls which parts of your project are compiled:

// Set the root project name - this will be displayed in IDEs
rootProject.name = 'DevToolkit'

// Include application modules to be built
// Format: 'Parent:Category:Platform:ModuleName'
include 'DevToolkit:demo:arria10:BitcoinMiner'      // FPGA Bitcoin mining example
include 'DevToolkit:demo:coolidge:CLDeviceTester'   // Kalray Coolidge platform example
include 'DevToolkit:examples:generic:HelloWorld'    // Cross-platform example

The include paths follow a hierarchical structure that helps organize modules logically. This structure is especially useful for large projects with many modules targeting different platforms.

3. Module-specific build.gradle

Each application module needs its own build.gradle file specifying target platforms, dependencies, and compilation options. Here’s an annotated example:

// Apply the appropriate Brane plugins based on target platform
plugins {
    id 'com.brane.coolidge.cpp'  // Kalray Coolidge platform plugin
}

// Configure the application build settings
application {
    // Define target architectures for this module
    targetMachines = [
        machines.linux.x86_64,                         // Standard x86_64 Linux host
        coolidgeMachines.clusterOS.architecture("MPPA_v2")  // Kalray Coolidge Accelerator
    ]
    
    // Optional: Configure C/C++ compiler options
    cppCompiler {
        // Enable specific optimizations
        optimizationLevel = 3  // -O3 optimization
        
        // Define preprocessor macros
        define('DEBUG_LEVEL', '2')
        define('ENABLE_FEATURE_X')
    }
}

AWS Credentials for Brane Plugin Repository #

The Brane SDK plugin repository is hosted on AWS S3 and requires authentication. You have two options for providing AWS credentials:

1. Environment Variables:
   • Set AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY in your environment
2. Gradle Properties:
   • Create a gradle.properties file in your project root or in ~/.gradle/ with: propertiesCopyaws_access_key_id=YOUR_ACCESS_KEY aws_secret_access_key=YOUR_SECRET_KEY

For security reasons, the gradle.properties file should not be committed to version control if it contains sensitive information.

Verifying Your Setup #

After configuring your environment and project structure, verify that everything is working correctly:

1. Navigate to your project directory in a terminal
2. Check for project recognition in IntelliJ (if using):
   • Open the project in IntelliJ IDEA
   • Verify that Gradle sync completes successfully
   • Confirm that modules are recognized in the Project view

If any issues occur, the Brane SDK provides detailed error messages to help diagnose and resolve configuration problems.