binding.yml

# Binding manifest — see https://github.com/EvergineTeam/Evergine.Bindings
# Schema: https://github.com/EvergineTeam/Evergine.Bindings/blob/main/binding.schema.json
toolbox: 1.29.0

package:
  id: Evergine.Bindings.ThorVG
  project: Evergine.Bindings.ThorVG/Evergine.Bindings.ThorVG.csproj
  target-framework: net10.0
  runtime-identifier: linux-x64

upstream:
  kind: git-tree
  language: cpp
  project: https://github.com/thorvg/thorvg
  version-from: git-release

  release:
    # Tagged releases, not main. This binding ships native libraries it compiles itself, and
    # the header and those libraries have to come from one revision of ThorVG; a branch would
    # move the header underneath libraries built from something else. `current` is rewritten
    # by binding-fetch-upstream when it brings in a newer release, which makes this the one
    # place the version lives.
    track: stable
    current: v1.1.0

  # One source: thorvg_capi.h is self-contained, including only <stdint.h> and <stdbool.h>.
  # The C++ API in inc/thorvg.h is deliberately not vendored — it is not bindable by P/Invoke.
  sources:
    - repo: thorvg/thorvg
      remote-path: src/bindings/capi/thorvg_capi.h
      path: ThorvgGen/Headers/thorvg_capi.h
      format: c-header

generator:
  project: ThorvgGen/ThorvgGen.csproj
  name: ThorvgGen
  output:
    - Evergine.Bindings.ThorVG/Generated

# NOTE — ThorvgGen/Headers/libc-stubs/ is hand-written and sits beside the vendored header.
# It must survive a fetch, which it does: the source above names a single file, so nothing
# else under Headers/ is touched.
#
# The stubs stand in for <stdint.h> and <stdbool.h>, the only two headers thorvg_capi.h
# includes. libclang ships no libc and finds no include paths at all on a Linux runner, so
# without them the parse dies there while succeeding on Windows, where the Windows SDK happens
# to be on the search path. stdbool.h is deliberately EMPTY: CppAst drives libclang in C++
# mode, where bool is a keyword, and the C spelling `#define bool _Bool` breaks the parse
# rather than helping it. Do not "complete" it.
#
# NOTE — this package ships native libraries under Evergine.Bindings.ThorVG/runtimes, and
# ThorVG publishes none: every release carries a single source tarball. thorvg-meson.yml
# builds all four RIDs from the resolved tag, and the CD runs it before the header is
# committed. A header bump is only valid together with that rebuild — P/Invoke binds late, so
# a mismatched package compiles, passes CI, publishes, and then throws in the consumer's
# application. Do not bump the header by hand.
#
# NOTE — `-Dbindings=capi` is off by default in ThorVG's meson options, and without it the
# library builds perfectly and exports not one tvg_* symbol. That is why thorvg-meson.yml
# checks the output for tvg_engine_init instead of trusting a green build. If the natives ever
# come back with no C API, this is the first thing to look at.
#
# NOTE — the libraries are renamed on staging. ThorVG names its target after the major
# version (thorvg-1.dll, libthorvg-1.so.1, libthorvg-1.1.dylib) and on Unix the plain name is
# a symlink, which does not survive NuGet packaging. The workflow copies the real file as
# thorvg.dll / libthorvg.so / libthorvg.dylib so DllImport("thorvg") keeps resolving when
# ThorVG goes to 2.x.
#
# NOTE — the engines are CPU raster only (-Dengines=cpu). thorvg_capi.h declares the GL and
# WebGPU canvas functions unconditionally, so they are part of the generated surface and
# return TVG_RESULT_NOT_SUPPORTED at run time. Enabling those engines is a build-flag change
# in thorvg-meson.yml and does not alter the managed API.
#
# WebGPU is deliberately off. `dependency('wgpu_native')` in ThorVG's meson is an unconditional
# pkg-config lookup, nothing is vendored, and upstream's own CI satisfies it by downloading a
# hand-written .pc from a GitHub user-attachment zip — an unstable URL, on Linux only. Turning
# it on would also mean shipping wgpu-native's binaries beside ThorVG's. Upstream marks
# WgCanvas "not fully supported yet".
#
# NOTE — iOS ships static archives, not shared libraries: there is no dynamic loader for
# third-party code there. runtimes/ios-arm64 and runtimes/iossimulator-arm64 carry libthorvg.a,
# and buildTransitive/Evergine.Bindings.ThorVG.targets is what makes a consumer's build link
# them. Without that file the archives are inert weight, which is the state KTX.NET is in.
# The archives keep the lib prefix on purpose — iOS resolves them through __Internal inside the
# executable, so the file name does not matter there, unlike browser-wasm where the module name
# comes from the file name.
#
# NOT VERIFIED: no iOS application has been linked against this package. ThorVG bundles its own
# png/jpg/webp decoders under -Dstatic=true, so -force_load could surface duplicate symbols in
# an app that also links libpng, libjpeg or libwebp. It would appear as a link error.
#
# NOTE — the package stays on a single net10.0 framework even though it carries iOS archives.
# An iOS consumer resolves lib/net10.0 (net10.0-ios derives from it) and buildTransitive/ is
# imported whatever the consumer targets. ImGui.Net does the same. Adding a net10.0-ios
# framework would force the CI onto a Windows runner with workload restore and would hand the
# iOS SDK a Content item group to embed — JoltPhysics ships that mistake today, at 72 MB
# against 119 KB for its plain assembly.
#
# NOTE — win-arm64 uses ThorvgGen/cross/win_arm64.txt, written here because ThorVG ships cross
# files for Android and iOS only. cpu_family must be 'aarch64' and not 'arm': ThorVG picks its
# SIMD variant from that value, and 'arm' selects neon-arm, which appends -mfpu=neon — a flag
# cl.exe rejects.
#
# NOTE — Android's cross files upstream are templates carrying the literal tokens NDK, HOST_TAG
# and API, which have to be substituted before meson can read them. There is no cross file for
# 32-bit ARM, hence android-arm64 and android-x64 only.