initial

Signed-off-by: Mikhail Kot <to@myrrc.dev>

Author: myrrc

vortex-ffi/CMakeLists.txt

@@ -2,6 +2,8 @@
 # SPDX-FileCopyrightText: Copyright the Vortex contributors
 cmake_minimum_required(VERSION 3.10)
 
+include(FetchContent)
+
 project(VortexFFI
     VERSION 0.0.1
     LANGUAGES C)
@@ -10,6 +12,7 @@ set(CMAKE_C_STANDARD 17)
 set(CMAKE_C_FLAGS "${CMAKE_C_FLAGS} -Wall -Werror -Wextra -Wpedantic")
 
 option(BUILD_TESTS "Build tests" OFF)
+option(BUILD_EXAMPLES "Build examples" OFF)
 
 set(SANITIZER "" CACHE STRING "Build with sanitizers")
 set(TARGET_TRIPLE "" CACHE STRING "Rust target triple for FFI library")
@@ -95,6 +98,15 @@ set_target_properties(vortex_ffi_shared PROPERTIES
     INTERFACE_LINK_OPTIONS "LINKER:-rpath,${LIBRARY_DIR}"
 )
 
+if (BUILD_TESTS OR BUILD_EXAMPLES)
+    FetchContent_Declare(
+      Nanoarrow
+      GIT_REPOSITORY https://github.com/apache/arrow-nanoarrow
+      GIT_TAG        apache-arrow-nanoarrow-0.8.0
+    )
+    FetchContent_MakeAvailable(Nanoarrow)
+endif()
+
 if (BUILD_TESTS)
     enable_language(CXX)
     set(CMAKE_CXX_STANDARD 20)
@@ -103,3 +115,7 @@ if (BUILD_TESTS)
     enable_testing()
     add_subdirectory(test)
 endif()
+
+if (BUILD_EXAMPLES)
+    add_subdirectory(examples)
+endif()

vortex-ffi/README.md

@@ -1,28 +1,30 @@
 # Foreign Function Interface
 
-Vortex is a file format that can be used by any execution engine. Nearly every programming language supports
-the C ABI (Application Binary Interface), so by providing an FFI interface to work with Vortex objects we can
-make it easy to support a variety of languages.
+Vortex is a file format that can be used by any execution engine. Nearly every
+programming language supports the C ABI (Application Binary Interface), so by
+providing an FFI interface to work with Vortex objects we can make it easy to
+support a variety of languages.
 
-Check out the [`examples`](./examples/) directory to see an example of how to use the API to build
-a real native application.
+Check out the [`examples`](./examples/) directory to see an example of how to
+use scanning API from C to read vortex files.
+Full FFI API is documented in `docs/api/c` and in `cinclude/vortex.h` header.
 
-## Design
+## Usage from a CMake project
 
-The FFI is designed to be very simple and follows a very object-oriented approach:
+1. Build .so/.dylib/.dll
 
-- **Constructors** are simple C functions that return opaque pointers
-- **Methods** are functions that receive an opaque pointer as the first argument, followed by subsequent arguments.
-  Methods may return a value or void.
-- **Destructors** free native resources (allocations, file handles, network sockets) and must be explicitly called by
-  the foreign language to avoid leaking resources.
-
-Constructors will generally allocate rust memory, and destructors free that memory.
+```sh
+cargo build --release -p vortex-ffi
+```
 
-## Documentation
+2. Add shared or static library
 
-The FFI API is documented in `docs/api/c` with explicit inclusion of types, enums, and functions, etc. Note that an
-item cannot be referenced in the documentation if it does not have a documentation comment.
+```cmake
+# in your CMakeLists.txt
+include_directory(vortex/vortex-ffi)
+target_link_libraries(my_target, vortex_ffi_shared)
+# or target_link_libraries(my_target, vortex_ffi)
+```
 
 ## Updating Headers
 
@@ -32,10 +34,10 @@ To rebuild the header file:
 cargo +nightly build -p vortex-ffi
 ```
 
-The header generation uses cbindgen's macro expansion feature which requires nightly.
-Stable builds use the checked-in header file at `cinclude/vortex.h`.
+Header generation uses cbindgen's macro expansion feature which requires nightly.
+Stable builds use header file at `cinclude/vortex.h`.
 
-### Testing C part
+## Testing C part
 
 Build the test library
 
@@ -52,7 +54,7 @@ ctest --test-dir build -j $(nproc)
 
 You would need C++ compiler toolchain to run the tests since they use Catch2.
 
-### Testing Rust part with sanitizers
+## Testing Rust part with sanitizers
 
 AddressSanitizer:
 
@@ -93,7 +95,7 @@ with sanitizers.
 leaks.
 - If you want stack trace symbolization, install `llvm-symbolizer`.
 
-### Testing Rust and C with sanitizers
+## Testing Rust and C with sanitizers
 
 1. Build FFI library with external sanitizer runtime:
 
@@ -114,3 +116,11 @@ cmake -Bbuild -DWITH_ASAN=1 -DTARGET_TRIPLE=<target triple>
 ```sh
 ./build/test/vortex_ffi_test 2>& 1 | rustfilt -i-
 ```
+
+## Running C example
+
+```sh
+cmake -Bbuild -DBUILD_EXAMPLES=1
+cmake --build build
+./build/examples/vortex_scan
+```

vortex-ffi/examples/CMakeLists.txt

@@ -0,0 +1,5 @@
+# SPDX-License-Identifier: CC-BY-4.0
+# SPDX-FileCopyrightText: Copyright the Vortex contributors
+cmake_policy(SET CMP0079 NEW)
+add_executable(vortex_scan scan.c)
+target_link_libraries(vortex_scan PRIVATE vortex_ffi_shared)