Skip to content

AGENTS.md

Latest commit

 

History

History
112 lines (80 loc) · 5.92 KB

AGENTS.md

File metadata and controls

112 lines (80 loc) · 5.92 KB

AGENTS.md

Project Overview

DiffScope Synthesis Platform is the synthesis backend for DiffScope. The project consists of a Go command-line and service layer, a C++ native shared library, and SWIG-generated Go/C++ bindings.

  • cmd/dssp/: Entry point for the dssp executable.
  • internal/: Internal Go implementation, including the CLI, HTTP service, application metadata, and execution provider wrappers.
  • native/include/: Public C ABI headers for the native library.
  • native/src/: Internal C++ implementation of the native library.
  • native/swig/: SWIG interface definitions.
  • scripts/vcpkg-manifest/: The project's vcpkg manifest.
  • scripts/vcpkg/: The vcpkg overlay used by the project, managed as a Git submodule.

Default Behavior When Modifying Code

  • Unless the user explicitly asks to build, run tests, or execute the program, do not proactively build, test, or run the program after making code changes.
  • By default, perform only the necessary static checks, such as reading the relevant files, inspecting the diff, and running gofmt as needed when modifying Go files.
  • Do not treat cmake --build, cmake --install, go test, ctest, or running dssp as default finishing steps for code modification tasks.
  • If the user explicitly requests verification, prefer the smallest build or test command that matches the scope of the changes, and state which commands were actually run in the response.

Native Library Interface Conventions

native/include/native.h defines the public C ABI for the native shared library. When adding or modifying public interfaces, keep them callable from both C and C++, and continue to use extern "C" guards.

Public interface names follow the existing style:

  • Use the DSSP_ prefix for all public symbols.
  • Use DSSP_ followed by PascalCase for public functions, such as DSSP_GetDefaultDevice and DSSP_GetDeviceID.
  • Use DSSP_ followed by PascalCase for public types, such as DSSP_Device and DSSP_ExecutionProvider.
  • Use DSSP_<Type>_<Value> for enum values, such as DSSP_ExecutionProvider_DirectML.
  • Use snake_case for function parameters, such as execution_provider.
  • Keep the interface as a C-style ABI: use C-compatible types, opaque handles, and standard integer types. Do not expose C++ types in public headers.
  • Preserve common domain-specific abbreviations, such as ID, CPU, CUDA, DirectML, and CoreML.

Public interfaces are exposed to Go through native/swig/native.i. When modifying a public header, confirm that the corresponding declaration is still included in the SWIG interface.

Internal Native C++ Conventions

Internal C++ code in native/src/ follows the existing implementation style:

  • Use snake_case for file names, such as execution_provider_info.cpp.
  • Use PascalCase for type names, such as DeviceInfo and ExecutionProviderInfo.
  • Use lowerCamelCase for function names, such as getDefaultDevice and getExecutionProviders.
  • Use lowerCamelCase for local variables, parameters, and struct fields, such as executionProvider and defaultDevice.
  • Place types, functions, and static data used only within an implementation file in an anonymous namespace.
  • Use tabs for indentation and preserve the existing brace layout.
  • Isolate platform-specific code with conditional compilation, such as _WIN32 and __APPLE__.
  • Keep the public interface naming style for exported C ABI functions, even when they are implemented in .cpp files.
  • Let invalid input fail fast. Do not silently accept null handles, replace required null pointers with fallback values, ignore out-of-range writes, or return fallback values for out-of-range reads. Use bounds-checked container access such as std::vector::at().

Generated Files

The following files are generated by SWIG during the CMake build process. Do not edit them manually:

  • native/native.go
  • native/native_wrap.cxx

To change binding behavior, modify native/include/native.h, native/swig/native.i, or native/CMakeLists.txt.

Build Process

The project is built through the root CMake project. CMake:

  1. Builds the dssp_native C++ shared library.
  2. Uses SWIG to generate Go/C++ bindings from native/swig/native.i.
  3. Enables CGO to build ./cmd/dssp and outputs the dssp executable.

Basic dependencies:

  • CMake
  • Go
  • SWIG
  • vcpkg
  • Ninja (used by the repository's VS Code configuration)
  • On Windows, both MSVC and MinGW are required: the native library is built by CMake/MSVC, while the Go CGO build sets CC=gcc and CXX=g++.

When preparing dependencies for the first time, initialize the overlay submodule and install the manifest dependencies in the local vcpkg directory. Windows example:

git submodule update --init --recursive
cd vcpkg
.\bootstrap-vcpkg.bat
.\vcpkg.exe install --x-manifest-root=..\scripts\vcpkg-manifest --x-install-root=.\installed --triplet=x64-windows
cd ..

See scripts/vcpkg/README.md for detailed vcpkg overlay setup instructions.

Windows build example using Ninja:

cmake -S . -B build -G Ninja `
  -DCMAKE_TOOLCHAIN_FILE="$PWD\vcpkg\scripts\buildsystems\vcpkg.cmake" `
  -DCMAKE_INSTALL_PREFIX="$PWD\build\installed"
cmake --build build

To install the build artifacts:

cmake --install build

APPLICATION_INSTALL defaults to ON. The root CMake project also supports overriding the application name and version injected into the Go executable through APPLICATION_NAME and APPLICATION_SEMVER.

Go Code Conventions

  • Write Go code in standard Go style, and run gofmt as needed after making changes.
  • Packages under internal/ are for use within this project only.
  • The Go layer calls the C ABI through the generated native package. Do not bypass the existing wrappers by adding CGO glue code directly in business logic.
  • Create a thin wrapper layer around native library functionality before exposing it to the CLI and HTTP service. Do not call the native package directly from CLI code or HTTP handlers.