Sharpmake Documentation

Samples in Sharpmake are managed via a data-driven approach using the SamplesDef.json file. This file defines how samples are executed in CI pipelines (GitHub/GitLab) and via the RunSample.ps1 script.

Each sample entry in SamplesDef.json is an object that specifies its metadata, target environments, and the sequence of commands required to run it. Commands are executed using the PowerShell Invoke-Expression cmdlet, meaning they share the same execution context; variables set in one command are available to subsequent commands.

{
    "Name": "HelloWorld",
    "CIs": [ "github", "gitlab" ],
    "OSs": [ "windows-2019", "windows-2022" ],
    "Frameworks": [ "net6.0" ],
    "Configurations": [ "debug", "release" ],
    "TestFolder": "samples/HelloWorld",
    "Commands":
    [
        "./RunSharpmake.ps1 -workingDirectory {testFolder} -sharpmakeFile \"HelloWorld.sharpmake.cs\" -framework {framework}",
        "./Compile.ps1 -slnOrPrjFile \"helloworld_vs2019_win32.sln\" -configuration {configuration} -platform \"Win32\" -WorkingDirectory \"{testFolder}/projects\" -VsVersion {os} -compiler MsBuild",
        "&'./{testFolder}/projects/output/win32/{configuration}/helloWorld.exe'",
        "./Compile.ps1 -slnOrPrjFile \"helloworld_vs2019_win64.sln\" -configuration {configuration} -platform \"x64\" -WorkingDirectory \"{testFolder}/projects\" -VsVersion {os} -compiler MsBuild",
        "&'./{testFolder}/projects/output/win64/{configuration}/helloWorld.exe'"
    ]
}

When defining targets in Sharpmake, you can use one of two approaches depending on your needs:

1. Different Target Types: Use distinct ITarget types for different projects (e.g., a library's internal target vs. a consumer's target). This makes the library's .sharpmake.cs file independent and reusable, and allows the library to expose a minimal set of targets. This requires explicit conversion methods (e.g., GetSomeLibTarget()) when adding dependencies.

2. Same Target Type: Use the same ITarget type across all projects. This is simpler to implement and reduces code complexity, which is a common pattern used to minimize different target types in large codebases.

Warning: Avoid using the same target type for different meanings. A Target type should be a compile-time tool, not a run-time object. Do not implement methods that return the same target type as a way to perform a conversion; instead, use explicit conversion methods to ensure type safety during dependency resolution.

// Approach 1: Different Target Types (Better for reusable libraries)
namespace SomeLib
{
    class Target : ITarget { ... }
    class SomeLib : Project 
    { 
        SomeLib() : Project(typeof(Target)) { ... }
    }
}
namespace MyNamespace
{
    class Target : ITarget
    {
        SomeLib.Target GetSomeLibTarget() { return ...; }
    }
    [Generate]
    class MyProject : Project
    {
        [Configure]
        void Configure(Configuration conf, Target target)
        {
            conf.AddPublicDependency<SomeLib.SomeLib>(target.GetSomeLibTarget());
        }
    }
}

// Approach 2: Same Target Type (Simpler for internal projects)
namespace MyNamespace
{
    class SomeLib : Project 
    { 
        SomeLib() : Project(typeof(Target)) { ... }
    }
    class Target : ITarget { ... }
    [Generate]
    class MyProject : Project
    {
        [Configure]
        void Configure(Configuration conf, Target target)
        {
            conf.AddPublicDependency<SomeLib>(target);
        }
    }
}

Sharpmake is designed to be extended for additional features or platform support (e.g., game consoles). The recommended way to extend Sharpmake is to create a separate project structure called SharpmakeExtended that wraps the core repository.

Recommended Folder Layout

SharpmakeExtended:
 - 📁 Sharpmake
 - 📁 Sharpmake.Platforms
 - 📁 Sharpmake.Extensions
    - Directory.build.props
    - SharpmakeExtended.sln

Implementation Details

1. Sharpmake (Core): This folder contains the files from the main Sharpmake Git repository. You can include it as a Git submodule in your SharpmakeExtended project.

2. Sharpmake.Platforms / Sharpmake.Extensions: Use these folders to house your custom platform logic. Each platform should have its own folder and .csproj file:

   📁 Sharpmake.Platforms
    - 📁 Sharpmake.Platform_A
         - *.cs
         - Sharpmake.Platform_A.csproj

   The Sharpmake.Application.csproj in the core repository automatically detects and adds .csproj files from these folders to its dependency list. This ensures they are built, copied to the output folder, and ready for debugging automatically.

3. Directory.build.props: Use this file in your extension projects to inherit the core build configuration (like target frameworks). Import the core file and then apply your overrides:

   <Project>
     <Import Project="Sharpmake/Directory.Build.props" />
     <!-- Add customization/override here -->
   </Project>

4. SharpmakeExtended.sln: Create a custom solution file to manage both the core projects and your extensions in a single IDE instance.

<Project>
  <!-- Rely on Sharpmake build setup -->
  <Import Project="Sharpmake/Directory.Build.props" />

  <!-- Add customization/override here -->
  <!-- ... -->
</Project>