This is an automated email from the ASF dual-hosted git repository.
junrushao pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/tvm-ffi.git
The following commit(s) were added to refs/heads/main by this push:
new af25838 doc: split installation section (#144)
af25838 is described below
commit af258380b8d3e1a9c48558a28e0dec8c7969fb35
Author: Junru Shao <[email protected]>
AuthorDate: Thu Oct 16 07:52:24 2025 -0700
doc: split installation section (#144)
This PR splits "Installation" section into two parts:
- Install from PyPI: putting this on homepage
- Build from source: totally rewrote this guide and move it to "guides"
To build this doc:
```bash
uv run --isolated --python 3.13 --group docs sphinx-autobuild docs
docs/_build/html --ignore docs/reference/cpp/generated
```
---
CMakeLists.txt | 15 +++++-
docs/get_started/install.md | 81 ---------------------------------
docs/get_started/quick_start.md | 2 +-
docs/guides/build_from_source.md | 98 ++++++++++++++++++++++++++++++++++++++++
docs/index.rst | 15 +++++-
5 files changed, 126 insertions(+), 85 deletions(-)
diff --git a/CMakeLists.txt b/CMakeLists.txt
index 8928863..df3acf5 100644
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -296,7 +296,14 @@ endif ()
install(DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}/include/tvm/ffi/ DESTINATION
include/tvm/ffi/)
install(DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}/3rdparty/dlpack/include/
DESTINATION include/)
install(TARGETS tvm_ffi_shared DESTINATION lib)
-install(TARGETS tvm_ffi_testing DESTINATION lib)
+# if tvm_ffi_testing is built, we also install it
+if (TARGET tvm_ffi_testing)
+ install(
+ TARGETS tvm_ffi_testing
+ DESTINATION lib
+ OPTIONAL
+ )
+endif ()
# ship additional dSYM files for debugging symbols on if available
if (APPLE)
install(
@@ -309,5 +316,9 @@ endif ()
if (NOT TVM_FFI_BUILD_PYTHON_MODULE)
# when building wheel, we do not ship static as we already ships source and
dll
- install(TARGETS tvm_ffi_static DESTINATION lib)
+ install(
+ TARGETS tvm_ffi_static
+ DESTINATION lib
+ OPTIONAL
+ )
endif ()
diff --git a/docs/get_started/install.md b/docs/get_started/install.md
deleted file mode 100644
index 5e97143..0000000
--- a/docs/get_started/install.md
+++ /dev/null
@@ -1,81 +0,0 @@
-<!--- Licensed to the Apache Software Foundation (ASF) under one -->
-<!--- or more contributor license agreements. See the NOTICE file -->
-<!--- distributed with this work for additional information -->
-<!--- regarding copyright ownership. The ASF licenses this file -->
-<!--- to you under the Apache License, Version 2.0 (the -->
-<!--- "License"); you may not use this file except in compliance -->
-<!--- with the License. You may obtain a copy of the License at -->
-
-<!--- http://www.apache.org/licenses/LICENSE-2.0 -->
-
-<!--- Unless required by applicable law or agreed to in writing, -->
-<!--- software distributed under the License is distributed on an -->
-<!--- "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY -->
-<!--- KIND, either express or implied. See the License for the -->
-<!--- specific language governing permissions and limitations -->
-<!--- under the License. -->
-# Installation
-
-TVM FFI is built and tested on Windows, macOS, and various
-Linux distributions. You can install tvm-ffi using one of the
-methods below
-
-## Quick Start
-
-The easiest way to try it out is to install from PyPI.
-
-```bash
-pip install apache-tvm-ffi
-```
-
-After installation, you can run the following command to confirm that
-the installation was successful
-
-```bash
-tvm-ffi-config -h
-```
-
-This configuration tool is also useful in various ways to help you build
-libraries with tvm-ffi.
-
-## Install From Source
-
-You can also build and install tvm-ffi from source.
-
-### Dependencies
-
-- CMake (>= 3.24.0)
-- Git
-- A recent C++ compiler supporting C++17, at minimum:
- - GCC 7.1
- - Clang 5.0
- - Apple Clang 9.3
- - Visual Studio 2019 (v16.7)
-- Python (>= 3.9)
-
-Developers can clone the source repository from GitHub.
-
-```bash
-git clone --recursive https://github.com/apache/tvm-ffi
-```
-
-```{note}
-It's important to use the ``--recursive`` flag when cloning the repository,
which will
-automatically clone the submodules. If you forget to use this flag, you can
manually clone the submodules
-by running ``git submodule update --init --recursive`` in the root directory.
-```
-
-Then you can install directly in development mode
-
-```bash
-cd tvm-ffi
-pip install -ve .
-```
-
-The additional `-e` flag will install the Python files in `editable` mode,
-which allows direct editing of the Python files to be immediately reflected in
the package
-and is useful for development.
-
-## What to Do Next
-
-Now that you have installed TVM FFI, we recommend reading the [Quick
Start](./quick_start.md) tutorial.
diff --git a/docs/get_started/quick_start.md b/docs/get_started/quick_start.md
index 26a7b86..800bb8b 100644
--- a/docs/get_started/quick_start.md
+++ b/docs/get_started/quick_start.md
@@ -29,7 +29,7 @@ Let us first get started by build and run the example. The
example will show us:
Before starting, ensure you have:
-- TVM FFI installed following [installation](./install.md)
+- TVM FFI installed
- C++ compiler with C++17 support
- CMake 3.18 or later
- (Optional) Ninja build system (the quick-start uses Ninja for fast
incremental builds)
diff --git a/docs/guides/build_from_source.md b/docs/guides/build_from_source.md
new file mode 100644
index 0000000..ab46e50
--- /dev/null
+++ b/docs/guides/build_from_source.md
@@ -0,0 +1,98 @@
+<!--- Licensed to the Apache Software Foundation (ASF) under one -->
+<!--- or more contributor license agreements. See the NOTICE file -->
+<!--- distributed with this work for additional information -->
+<!--- regarding copyright ownership. The ASF licenses this file -->
+<!--- to you under the Apache License, Version 2.0 (the -->
+<!--- "License"); you may not use this file except in compliance -->
+<!--- with the License. You may obtain a copy of the License at -->
+
+<!--- http://www.apache.org/licenses/LICENSE-2.0 -->
+
+<!--- Unless required by applicable law or agreed to in writing, -->
+<!--- software distributed under the License is distributed on an -->
+<!--- "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY -->
+<!--- KIND, either express or implied. See the License for the -->
+<!--- specific language governing permissions and limitations -->
+<!--- under the License. -->
+# Build from Source
+
+This guide covers two common workflows:
+
+- Python package building, which automatically includes building the core C++
library;
+- C++-only package Building without Python.
+
+```{admonition} Prerequisite
+:class: tip
+
+- Python: 3.9 or newer
+- Compiler: C++17-capable toolchain
+ - Linux: GCC or Clang with C++17 support
+ - macOS: Apple Clang (via Xcode Command Line Tools)
+ - Windows: MSVC (Visual Studio 2019 or 2022, x64)
+- Build tools: CMake 3.18+; Ninja
+```
+
+## Build the Python Package
+
+Download the source via:
+
+```bash
+git clone --recursive https://github.com/apache/tvm-ffi
+cd tvm-ffi
+```
+
+```{note}
+Always clone with ``--recursive`` to pull submodules. If you already cloned
without it, run:
+
+ git submodule update --init --recursive
+
+```
+
+Follow the instruction below to build the Python package with
scikit-build-core, which drives CMake to compile the C++ core and Cython
extension.
+
+```bash
+pip install --reinstall --verbose -e . \
+ --config-settings cmake.define.TVM_FFI_ATTACH_DEBUG_SYMBOLS=ON
+```
+
+The ``--reinstall`` flag forces a rebuild, and ``-e/--editable`` install means
future Python-only changes are reflected immediately without having to rebuild.
+
+```{warning}
+However, changes to C++/Cython always require re-running the install command.
+```
+
+Verify the install:
+
+```bash
+python -c "import tvm_ffi; print(tvm_ffi.__version__)"
+tvm-ffi-config -h
+```
+
+```{tip}
+Use ``tvm-ffi-config`` to query include and link flags when consuming TVM FFI
from external C/C++ projects:
+ tvm-ffi-config --includedir
+ tvm-ffi-config --dlpack-includedir
+ tvm-ffi-config --libfiles # or --libs/--ldflags on Unix
+```
+
+## Build the C/C++ Library Only
+
+TVM FFI can be used as a standalone C/C++ library without Python. The
instruction below should work for Linux, macOS and Windows.
+
+```bash
+cmake . -B build_cpp -DCMAKE_BUILD_TYPE=RelWithDebInfo
+cmake --build build_cpp --parallel --config RelWithDebInfo --target
tvm_ffi_shared
+cmake --install build_cpp --config RelWithDebInfo --prefix ./dist
+```
+
+After installation, you should see:
+
+- Headers are installed under ``dist/include/``;
+- Libraries are installed under ``dist/lib/``.
+
+## Troubleshooting
+
+- Rebuilding after C++/Cython changes: re-run ``pip install --reinstall -e
.``. Editable installs only auto-reflect pure Python changes.
+- Submodules missing: run ``git submodule update --init --recursive`` from the
repo root.
+- Library not found at import time: ensure your dynamic loader can find the
shared library. If built from source, add the ``lib`` directory to
``LD_LIBRARY_PATH`` (Linux), ``DYLD_LIBRARY_PATH`` (macOS), or ``PATH``
(Windows).
+- Wrong generator/build type: Ninja/Unix Makefiles use
``-DCMAKE_BUILD_TYPE=...``; Visual Studio requires ``--config ...`` at
build/ctest time.
diff --git a/docs/index.rst b/docs/index.rst
index 195498b..82a6351 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -22,11 +22,23 @@ Welcome to the documentation for TVM FFI. You can get
started by reading the get
or reading through the guides and concepts sections.
+Installation
+------------
+
+To install via pip, run:
+
+.. code-block:: bash
+
+ pip install apache-tvm-ffi
+
+
+Table of Contents
+-----------------
+
.. toctree::
:maxdepth: 1
:caption: Get Started
- get_started/install.md
get_started/quick_start.md
.. toctree::
@@ -37,6 +49,7 @@ or reading through the guides and concepts sections.
guides/cpp_guide.md
guides/python_guide.md
guides/compiler_integration.md
+ guides/build_from_source.md
.. toctree::
