Skip to content

Commit b2896ae

Browse files
authored
Ship a pkg-config file for the runtime in the Linux and macOS wheels (pytorch#23169)
The wheel ships the runtime as shared libraries, with headers and a CMake package. Build systems that read pkg-config instead, such as Meson, look for `executorch.pc`, and the wheel has none. So those projects need a full source build just to get that one file. This adds `lib/pkgconfig/executorch.pc` to the Linux and macOS wheels: - All paths come from the file's own location, so it works wherever pip installed the wheel. - It gives the same compile definitions as the CMake package's runtime. That includes `ET_EVENT_TRACER_ENABLED` when the libraries are built with the event tracer, and `ET_USE_THREADPOOL` plus the thread pool library when the wheel ships the thread pool. - It adds a runtime search path, so a program finds the libraries without `LD_LIBRARY_PATH`. On Linux the path is its own `-Wl,-rpath` argument, so Meson keeps it when it installs the program. - Like the CMake `runtime` component, it does not include the kernels. You name those on the link line. Usage on Linux: ``` export PKG_CONFIG_PATH="$(python -c 'import executorch, pathlib; print(pathlib.Path(executorch.__path__[0]) / "lib" / "pkgconfig")')" c++ -std=c++17 main.cpp $(pkg-config --cflags --libs executorch) \ -Wl,--push-state,--no-as-needed -lexecutorch_kernels_optimized -Wl,--pop-state -o app ``` On macOS, leave out the `--push-state`, `--no-as-needed` and `--pop-state` flags. The macOS linker keeps the kernels library anyway, and it rejects those flags. Windows is left out because the Windows wheel does not ship the runtime library. The C++ usage page gets a pkg-config section with these commands and a Meson example. A new wheel smoke test builds a program with the flags pkg-config prints, runs a model, and compares the result with eager PyTorch. It also checks that the pkg-config file and the CMake package give the same compile definitions, so the two cannot drift apart. It gets pkg-config from the `pkgconf` package on PyPI. Test plan: built the macOS arm64 wheel from this branch and installed it into a clean environment. The C++ SDK checks pass, including the new one. The new check fails when the `.pc` file is removed, and it fails when a compile definition is missing from it. With Meson on macOS and on Linux x86_64, the documented recipe builds, installs and runs a model, and the installed program still finds the libraries. A program that calls `parallel_for` runs on many threads when built from these flags. The Linux and CUDA wheels are covered by the wheel build jobs on this PR.
1 parent 4199643 commit b2896ae

5 files changed

Lines changed: 200 additions & 0 deletions

File tree

‎.ci/scripts/wheel/test_cpp_sdk.py‎

Lines changed: 115 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1494,6 +1494,120 @@ def test_aggregate_variable_excludes_the_quantized_kernels(work_dir: Path) -> No
14941494
)
14951495

14961496

1497+
def _cmake_compile_definitions(work_dir: Path) -> list:
1498+
"""The compile definitions the installed CMake package hands a consumer."""
1499+
config = _installed_package_dir() / "share" / "cmake" / "executorch-config.cmake"
1500+
source_dir = work_dir / "definitions-probe"
1501+
source_dir.mkdir(parents=True, exist_ok=True)
1502+
(source_dir / "CMakeLists.txt").write_text(
1503+
"cmake_minimum_required(VERSION 3.19)\n"
1504+
"project(probe NONE)\n"
1505+
"find_package(executorch REQUIRED)\n"
1506+
'message(STATUS "DEFINITIONS=${EXECUTORCH_COMPILE_DEFINITIONS}")\n'
1507+
)
1508+
result = subprocess.run(
1509+
[
1510+
_tool("cmake"),
1511+
"-S",
1512+
str(source_dir),
1513+
"-B",
1514+
str(work_dir / "definitions-probe-build"),
1515+
f"-DCMAKE_PREFIX_PATH={config.parent}",
1516+
],
1517+
capture_output=True,
1518+
text=True,
1519+
check=False,
1520+
)
1521+
assert result.returncode == 0, (
1522+
"could not read the compile definitions from the installed CMake package:\n"
1523+
f"{result.stdout[-2000:]}{result.stderr[-2000:]}"
1524+
)
1525+
line = next(
1526+
entry for entry in result.stdout.splitlines() if "DEFINITIONS=" in entry
1527+
)
1528+
return [d for d in line.split("DEFINITIONS=", 1)[1].split(";") if d]
1529+
1530+
1531+
def test_pkg_config_builds_a_consumer(work_dir: Path) -> None:
1532+
"""A program built from the flags pkg-config prints finds, links and runs the runtime.
1533+
1534+
Meson, Autotools and plain Makefiles read pkg-config files rather than CMake packages. The
1535+
kernels are named on the command line because the file describes only the runtime, the same
1536+
split as the CMake components. pkg-config itself comes from the pkgconf package on PyPI, so
1537+
the check does not depend on one the build machine happens to have.
1538+
"""
1539+
pc_dir = _installed_package_dir() / "lib" / "pkgconfig"
1540+
assert (pc_dir / "executorch.pc").is_file(), (
1541+
f"the wheel ships no pkg-config file in {pc_dir}, so a build system that reads "
1542+
"pkg-config cannot find the runtime"
1543+
)
1544+
venv_dir = work_dir / "pkgconf-venv"
1545+
subprocess.run([sys.executable, "-m", "venv", str(venv_dir)], check=True)
1546+
subprocess.run(
1547+
[str(venv_dir / "bin" / "pip"), "install", "--quiet", "pkgconf"], check=True
1548+
)
1549+
pkg_config = str(venv_dir / "bin" / "pkg-config")
1550+
1551+
# PKG_CONFIG_LIBDIR alone, so a system executorch.pc cannot be found instead of this one.
1552+
environment = dict(os.environ, PKG_CONFIG_LIBDIR=str(pc_dir))
1553+
environment.pop("PKG_CONFIG_PATH", None)
1554+
result = subprocess.run(
1555+
[pkg_config, "--cflags", "--libs", "executorch"],
1556+
capture_output=True,
1557+
text=True,
1558+
check=False,
1559+
env=environment,
1560+
)
1561+
assert result.returncode == 0, (
1562+
"pkg-config --cflags --libs executorch failed against the installed file:\n"
1563+
f"{result.stdout[-2000:]}{result.stderr[-2000:]}"
1564+
)
1565+
flags = result.stdout.split()
1566+
1567+
# Both routes describe the same libraries, so they must agree on the definitions. A
1568+
# missing one fails silently for the consumer: ET_EVENT_TRACER_ENABLED changes the
1569+
# layout of the tracer scope classes, and without ET_USE_THREADPOOL parallel_for is serial.
1570+
pc_definitions = sorted(f[2:] for f in flags if f.startswith("-D"))
1571+
cmake_definitions = sorted(_cmake_compile_definitions(work_dir))
1572+
assert pc_definitions == cmake_definitions, (
1573+
f"the pkg-config file defines {pc_definitions}, but the CMake package in the same "
1574+
f"wheel defines {cmake_definitions}"
1575+
)
1576+
1577+
source = work_dir / "pkg-config-consumer.cpp"
1578+
source.write_text(_CONSUMER_SOURCE)
1579+
consumer = work_dir / "pkg-config-consumer"
1580+
if sys.platform == "darwin":
1581+
kernels = ["-lexecutorch_kernels_optimized"]
1582+
else:
1583+
kernels = [
1584+
"-Wl,--push-state,--no-as-needed",
1585+
"-lexecutorch_kernels_optimized",
1586+
"-Wl,--pop-state",
1587+
]
1588+
built = subprocess.run(
1589+
[
1590+
_tool("c++"),
1591+
"-std=c++17",
1592+
str(source),
1593+
"-o",
1594+
str(consumer),
1595+
*flags,
1596+
*kernels,
1597+
],
1598+
capture_output=True,
1599+
text=True,
1600+
check=False,
1601+
)
1602+
assert built.returncode == 0, (
1603+
f"a program built with the pkg-config flags did not compile and link:\n"
1604+
f"{built.stdout[-3000:]}{built.stderr[-3000:]}"
1605+
)
1606+
model, reference = _export(work_dir, "plain")
1607+
output = _run_consumer(consumer, model, reference, work_dir)
1608+
print(f"✓ a C++ app built from pkg-config flags runs a model ({output})")
1609+
1610+
14971611
def run_tests(work_dir: Path) -> None:
14981612
test_find_package_honours_a_version_request(work_dir)
14991613
test_profiler_component_is_usable(work_dir)
@@ -1502,6 +1616,7 @@ def run_tests(work_dir: Path) -> None:
15021616
test_documented_example_compiles(work_dir)
15031617
test_runtime_alone_links_but_cannot_compute(work_dir)
15041618
test_kernels_component_runs_a_model(work_dir)
1619+
test_pkg_config_builds_a_consumer(work_dir)
15051620
test_pre_3_28_route_builds_a_consumer_through_variables(work_dir)
15061621
test_quantized_kernels_component_runs_a_model(work_dir)
15071622
test_aggregate_variable_excludes_the_quantized_kernels(work_dir)

‎CMakeLists.txt‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1090,6 +1090,32 @@ if(EXECUTORCH_BUILD_SHARED)
10901090
install(FILES ${CMAKE_CURRENT_BINARY_DIR}/executorch.pc
10911091
DESTINATION ${CMAKE_INSTALL_LIBDIR}/pkgconfig
10921092
)
1093+
# pip decides where the wheel lands, so the wheel's copy of this file locates
1094+
# everything relative to its own location.
1095+
if(EXECUTORCH_BUILD_WHEEL_DO_NOT_USE)
1096+
set(_executorch_pc_definitions "-DC10_USING_CUSTOM_GENERATED_MACROS")
1097+
if(EXECUTORCH_ENABLE_EVENT_TRACER)
1098+
string(APPEND _executorch_pc_definitions " -DET_EVENT_TRACER_ENABLED")
1099+
endif()
1100+
# Matches the CMake package, which adds both to the runtime whenever the
1101+
# thread pool ships. Without the definition, parallel_for runs serially.
1102+
set(_executorch_pc_libs "-lexecutorch")
1103+
if(TARGET extension_threadpool)
1104+
string(APPEND _executorch_pc_definitions " -DET_USE_THREADPOOL")
1105+
string(APPEND _executorch_pc_libs " -lexecutorch_threadpool")
1106+
endif()
1107+
# Separate arguments, because Meson only keeps a dependency's rpath at
1108+
# install when the argument starts with -Wl,-rpath.
1109+
if(APPLE)
1110+
set(_executorch_pc_rpath "-Wl,-rpath,\${libdir}")
1111+
else()
1112+
set(_executorch_pc_rpath "-Wl,--enable-new-dtags -Wl,-rpath,\${libdir}")
1113+
endif()
1114+
configure_file(
1115+
tools/cmake/executorch-wheel.pc.in
1116+
${CMAKE_CURRENT_BINARY_DIR}/executorch-wheel.pc @ONLY
1117+
)
1118+
endif()
10931119
endif()
10941120

10951121
# The macro changes the layout of the tracer scope objects, so a consumer

‎docs/source/using-executorch-cpp.md‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -261,6 +261,49 @@ find_package(executorch REQUIRED COMPONENTS backend_mlx)
261261
message(STATUS "Metal kernels: ${MLX_METALLIB_PATH}")
262262
```
263263

264+
#### Using pkg-config
265+
266+
Build systems such as Meson and Autotools read pkg-config files. The wheel ships one for the
267+
runtime. It covers the engine and the thread pool. Name the kernel libraries yourself, the same
268+
way you add CMake components. Point pkg-config at the file with an absolute path, because the
269+
library search path it gives the linker is built from that path:
270+
271+
```
272+
export PKG_CONFIG_PATH="$(python -c 'import executorch, pathlib; print(pathlib.Path(executorch.__path__[0]) / "lib" / "pkgconfig")')${PKG_CONFIG_PATH:+:$PKG_CONFIG_PATH}"
273+
```
274+
275+
The kernels register themselves when they load, and nothing in your code names them, so the
276+
linker must be told to keep them. On Linux:
277+
278+
```
279+
c++ -std=c++17 main.cpp $(pkg-config --cflags --libs executorch) \
280+
-Wl,--push-state,--no-as-needed -lexecutorch_kernels_optimized -Wl,--pop-state -o app
281+
```
282+
283+
On macOS:
284+
285+
```
286+
c++ -std=c++17 main.cpp $(pkg-config --cflags --libs executorch) -lexecutorch_kernels_optimized -o app
287+
```
288+
289+
In Meson, take the library directory from the dependency. On macOS, replace the three Linux flags
290+
with `'-Wl,-needed-lexecutorch_kernels_optimized'`:
291+
292+
```
293+
executorch = dependency('executorch')
294+
libdir = executorch.get_variable(pkgconfig : 'libdir')
295+
executable('app', 'main.cpp',
296+
dependencies : executorch,
297+
link_args : ['-L' + libdir,
298+
'-Wl,--push-state,--no-as-needed',
299+
'-lexecutorch_kernels_optimized',
300+
'-Wl,--pop-state'],
301+
install : true)
302+
```
303+
304+
Add `-lexecutorch_kernels_quantized` or a backend such as `-lexecutorch_backend_xnnpack` the same
305+
way, because they sit next to the runtime library.
306+
264307
#### When something does not work
265308

266309
- `find_package` could not find executorch: the `-DCMAKE_PREFIX_PATH=...` argument is missing or

‎setup.py‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2944,6 +2944,13 @@ def iter_distribution_names(self):
29442944
"EXECUTORCH_BUILD_KERNELS_OPTIMIZED",
29452945
],
29462946
),
2947+
# For build systems that read pkg-config rather than CMake packages.
2948+
BuiltFile(
2949+
src_dir="%CMAKE_CACHE_DIR%/",
2950+
src_name="executorch-wheel.pc",
2951+
dst="executorch/lib/pkgconfig/executorch.pc",
2952+
dependent_cmake_flags=["EXECUTORCH_BUILD_SHARED"],
2953+
),
29472954
# The CUDA delegate and the process-wide CUDA stream helper, for a
29482955
# wheel built from a CUDA index. Only present when the build asks for
29492956
# CUDA, so packaging requires that rather than looking for files a

‎tools/cmake/executorch-wheel.pc.in‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
prefix=${pcfiledir}/../..
2+
libdir=${prefix}/lib
3+
includedir=${prefix}/include
4+
5+
Name: ExecuTorch
6+
Description: On-device AI framework for PyTorch models
7+
Version: @PROJECT_VERSION@
8+
Cflags: -I${includedir} -I${includedir}/executorch/runtime/core/portable_type/c10 @_executorch_pc_definitions@
9+
Libs: -L${libdir} @_executorch_pc_rpath@ @_executorch_pc_libs@

0 commit comments

Comments
 (0)