Multi-Targeting

Multi-Targeting the Solver API

Your solver criterion can be built against multiple versions of the Solver API at once.

Note: this is only useful if you need your criterion to run in multiple versions of HyperX >=2026.1

Multi-targeting allows your criterion to take advantage of new capabilities from later releases of Solver and HyperX, while maintaining backwards compatibility with earlier releases of HyperX.

Consider the following scenario:

Solver versions 1.5.0 and 2.0.0 may each have introduced properties like the following. These properties were NOT shipped in version 1.0.0.

interface IAnalyzable
{
    // <remarks>Added in 2.0.0</remarks>
    string InTheFutureText { get; }
 
    // <remarks>Added in 1.5.0</remarks>
    string InThePresentText { get; }

If you want your criteria to use that signature, you have several options:

1. Compile against Solver version 2.0. Benefits: clear, straightforward. Drawbacks: your criterion will no longer run in Solver 1.0 or 1.5.
2. Compile against Solver version 1.0, and use reflection to access the new properties and types. Benefits: criterion will run in Solver 1.0, 1.5, and 2.0. Drawbacks, not straightforward, not compile time safe, and slow at runtime.
3. Compile against all Solver versions. Benefits: criterion will run in 2.0, 1.5, and 1.0 and types are checked at compile time. Drawbacks: adds complexity to the build process.

This document focuses on option (3).

To compile against all Solver versions, Criteria specify which versions they should be compiled against:

<!-- Sample.Solver.Criteria.csproj -->
<ItemGroup>
    <PackageReference Include="HyperX.Solver.Api" Version="2.0.0" ExtraVersions="1.5.0;1.0.0" />
</ItemGroup>

Where the exact ExtraVersions must exist in a nuget source. Nuget sources are typically configured with a nuget.config file.

The HyperX.Solver.Api nuget package includes build targets that will compile the project several times, once for the main version and once for each extra version. The output path for each extra version is computed as follows: $(OutputPath)\solver$(ExtraVersion)\. This is not user-modifiable. For example:

$(OutputPath)\
    solver2.0.0\
    solver1.5.0\
    solver1.0.0\
    hxpkg.yaml

Where hxpkg.yaml identifies each of these main files and which APIs they correspond to.

• If mains is specified, main is optional. If present, main is treated as a fall-back if no more specific APIs match.

mains:
- api: 2.0.0
  path: .\solver2.0.0\Solver.Criteria.Buckling.dll
- api: 1.5.0
  path: .\solver1.5.0\Solver.Criteria.Buckling.dll
- api: 1.0.0
  path: .\solver1.0.0\Solver.Criteria.Buckling.dll

When HyperX loads a criterion from a package, it picks the best match.

The best match is nearest version less than or equal to than the current HyperX solver runtime.

To use the new signatures in criterion code, guard them with preprocessor conditions. For example:

string analyzableText;
 
#if SOLVER_2_0_OR_GREATER
        analyzableText = analyzable.InTheFutureText;
#elif SOLVER_1_5_OR_GREATER
        analyzableText = analyzable.InThePresentText;
#else
        analyzableText = "Solver API version older than 1.5.0";
#endif