lib,src,test,doc: add node:ffi module

PR-URL: #62072
Co-authored-by: Paolo Insogna <paolo@cowtech.it>
Reviewed-By: Matteo Collina <matteo.collina@gmail.com>
Reviewed-By: Bryan English <bryan@bryanenglish.com>

Author: cjihrig

.github/workflows/test-shared.yml

@@ -196,7 +196,7 @@ jobs:
             --arg ccache "${NIX_SCCACHE:-null}" \
             --arg devTools '[]' \
             --arg benchmarkTools '[]' \
-            ${{ endsWith(matrix.system, '-darwin') && '--arg withAmaro false --arg withLief false --arg withSQLite false --arg extraConfigFlags ''["--without-inspector" "--without-node-options"]'' \' || '\' }}
+            ${{ endsWith(matrix.system, '-darwin') && '--arg withAmaro false --arg withLief false --arg withSQLite false --arg withFFI false --arg extraConfigFlags ''["--without-inspector" "--without-node-options"]'' \' || '\' }}
             --run '
                 make -C "$TAR_DIR" run-ci -j4 V=1 TEST_CI_ARGS="-p actions --measure-flakiness 9 --skip-tests=$CI_SKIP_TESTS"
             ' "$TAR_DIR/shell.nix"

.github/workflows/tools.yml

@@ -26,6 +26,7 @@ on:
           - histogram
           - icu
           - inspector_protocol
+          - libffi
           - libuv
           - llhttp
           - minimatch
@@ -161,6 +162,14 @@ jobs:
               cat temp-output
               tail -n1 temp-output | grep "NEW_VERSION=" >> "$GITHUB_ENV" || true
               rm temp-output
+          - id: libffi
+            subsystem: deps
+            label: dependencies, ffi
+            run: |
+              ./tools/dep_updaters/update-libffi.sh > temp-output
+              cat temp-output
+              tail -n1 temp-output | grep "NEW_VERSION=" >> "$GITHUB_ENV" || true
+              rm temp-output
           - id: libuv
             subsystem: deps
             label: dependencies

Makefile

@@ -318,7 +318,7 @@ v8: ## Build deps/v8.
 		tools/make-v8.sh $(V8_ARCH).$(BUILDTYPE_LOWER) $(V8_BUILD_OPTIONS)
 
 .PHONY: jstest
-jstest: build-addons build-js-native-api-tests build-node-api-tests build-sqlite-tests ## Run addon tests and JS tests.
+jstest: build-addons build-js-native-api-tests build-node-api-tests build-sqlite-tests build-ffi-tests ## Run addon tests and JS tests.
 	$(PYTHON) tools/test.py $(PARALLEL_ARGS) --mode=$(BUILDTYPE_LOWER) \
 		$(TEST_CI_ARGS) \
 		--skip-tests=$(CI_SKIP_TESTS) \
@@ -344,6 +344,7 @@ test: all ## Run default tests and build docs.
 	$(MAKE) -s build-js-native-api-tests
 	$(MAKE) -s build-node-api-tests
 	$(MAKE) -s build-sqlite-tests
+	$(MAKE) -s build-ffi-tests
 	$(MAKE) -s cctest
 	$(MAKE) -s jstest
 
@@ -353,6 +354,7 @@ test-only: all  ## Run default tests without building the docs.
 	$(MAKE) build-js-native-api-tests
 	$(MAKE) build-node-api-tests
 	$(MAKE) build-sqlite-tests
+	$(MAKE) build-ffi-tests
 	$(MAKE) cctest
 	$(MAKE) jstest
 	$(MAKE) tooltest
@@ -364,6 +366,7 @@ test-cov: all ## Run coverage tests.
 	$(MAKE) build-js-native-api-tests
 	$(MAKE) build-node-api-tests
 	$(MAKE) build-sqlite-tests
+	$(MAKE) build-ffi-tests
 	$(MAKE) cctest
 	CI_SKIP_TESTS=$(COV_SKIP_TESTS) $(MAKE) jstest
 
@@ -542,6 +545,29 @@ else
 build-sqlite-tests:
 endif
 
+FFI_BINDING_GYPS := $(wildcard test/ffi/*/binding.gyp)
+
+FFI_BINDING_SOURCES := \
+	$(wildcard test/ffi/*/*.c) \
+	$(wildcard test/ffi/*/*.def)
+
+ifndef NOFFI
+# Depends on $(NODE_EXE) as order-only to avoid ETXTBSY on AIX when make
+# tries to execute node while it is still being linked in parallel.
+test/ffi/.buildstamp: $(ADDONS_PREREQS) \
+	$(FFI_BINDING_GYPS) $(FFI_BINDING_SOURCES) | $(NODE_EXE)
+	@$(call run_build_addons,"$$PWD/test/ffi",$@)
+else
+test/ffi/.buildstamp:
+endif
+
+.PHONY: build-ffi-tests
+ifndef NOFFI
+build-ffi-tests: | test/ffi/.buildstamp ## Build FFI tests.
+else
+build-ffi-tests:
+endif
+
 .PHONY: clear-stalled
 clear-stalled: ## Clear any stalled processes.
 	$(info Clean up any leftover processes but don't error if found.)
@@ -552,7 +578,7 @@ clear-stalled: ## Clear any stalled processes.
 	fi
 
 .PHONY: test-build
-test-build: | all build-addons build-js-native-api-tests build-node-api-tests build-sqlite-tests ## Build all tests.
+test-build: | all build-addons build-js-native-api-tests build-node-api-tests build-sqlite-tests build-ffi-tests ## Build all tests.
 
 .PHONY: test-build-js-native-api
 test-build-js-native-api: all build-js-native-api-tests ## Build JS Native-API tests.
@@ -563,6 +589,8 @@ test-build-node-api: all build-node-api-tests ## Build Node-API tests.
 .PHONY: test-build-sqlite
 test-build-sqlite: all build-sqlite-tests ## Build SQLite tests.
 
+.PHONY: test-build-ffi
+test-build-ffi: all build-ffi-tests ## Build FFI tests.
 
 .PHONY: test-all
 test-all: test-build ## Run default tests with both Debug and Release builds.
@@ -591,7 +619,7 @@ endif
 
 # Related CI job: node-test-commit-arm-fanned
 test-ci-native: LOGLEVEL := info ## Build and test addons without building anything else.
-test-ci-native: | benchmark/napi/.buildstamp test/addons/.buildstamp test/js-native-api/.buildstamp test/node-api/.buildstamp test/sqlite/.buildstamp
+test-ci-native: | benchmark/napi/.buildstamp test/addons/.buildstamp test/js-native-api/.buildstamp test/node-api/.buildstamp test/sqlite/.buildstamp test/ffi/.buildstamp
 	$(PYTHON) tools/test.py $(PARALLEL_ARGS) -p tap --logfile test.tap \
 		--mode=$(BUILDTYPE_LOWER) --flaky-tests=$(FLAKY_TESTS) \
 		$(TEST_CI_ARGS) $(CI_NATIVE_SUITES)
@@ -614,7 +642,7 @@ test-ci-js: | clear-stalled ## Build and test JavaScript with building anything
 .PHONY: test-ci
 # Related CI jobs: most CI tests, excluding node-test-commit-arm-fanned
 test-ci: LOGLEVEL := info ## Build and test everything (CI).
-test-ci: | clear-stalled bench-addons-build build-addons build-js-native-api-tests build-node-api-tests build-sqlite-tests doc-only
+test-ci: | clear-stalled bench-addons-build build-addons build-js-native-api-tests build-node-api-tests build-sqlite-tests build-ffi-tests doc-only
 	out/Release/cctest --gtest_output=xml:out/junit/cctest.xml
 	$(PYTHON) tools/test.py $(PARALLEL_ARGS) -p tap --logfile test.tap \
 		--mode=$(BUILDTYPE_LOWER) --flaky-tests=$(FLAKY_TESTS) \
@@ -632,6 +660,7 @@ test-ci: | clear-stalled bench-addons-build build-addons build-js-native-api-tes
 build-ci: ## Build everything (CI).
 	$(PYTHON) ./configure --verbose $(CONFIG_FLAGS)
 	$(MAKE)
+	$(MAKE) build-ffi-tests
 
 .PHONY: run-ci
 # Run by CI tests, exceptions:
@@ -734,6 +763,16 @@ test-sqlite-clean: ## Remove SQLite testing artifacts.
 	$(RM) -r test/sqlite/*/build
 	$(RM) test/sqlite/.buildstamp
 
+.PHONY: test-ffi
+test-ffi: test-build-ffi ## Run FFI tests.
+	$(PYTHON) tools/test.py $(PARALLEL_ARGS) --mode=$(BUILDTYPE_LOWER) ffi
+
+.PHONY: test-ffi-clean
+.NOTPARALLEL: test-ffi-clean
+test-ffi-clean: ## Remove FFI testing artifacts.
+	$(RM) -r test/ffi/*/build
+	$(RM) test/ffi/.buildstamp
+
 .PHONY: test-addons
 test-addons: test-build test-js-native-api test-node-api ## Run addon tests.
 	$(PYTHON) tools/test.py $(PARALLEL_ARGS) --mode=$(BUILDTYPE_LOWER) addons
@@ -1228,6 +1267,7 @@ ifeq ($(SKIP_SHARED_DEPS), 1)
 	$(RM) -r $(TARNAME)/deps/icu-small
 	$(RM) -r $(TARNAME)/deps/icu-tmp
 	$(RM) -r $(TARNAME)/deps/LIEF
+	$(RM) -r $(TARNAME)/deps/libffi
 	$(RM) -r $(TARNAME)/deps/llhttp
 	$(RM) -r $(TARNAME)/deps/merve
 	$(RM) -r $(TARNAME)/deps/nbytes
@@ -1502,6 +1542,7 @@ LINT_CPP_FILES = $(filter-out $(LINT_CPP_EXCLUDE), $(wildcard \
 	test/embedding/*.cc \
 	test/embedding/*.h \
 	test/sqlite/*/*.c \
+	test/ffi/*/*.c \
 	test/fixtures/*.c \
 	test/js-native-api/*/*.cc \
 	test/node-api/*/*.cc \
@@ -1526,6 +1567,7 @@ FORMAT_CPP_FILES += $(wildcard \
 	test/node-api/*/*.c \
 	test/node-api/*/*.h \
 	test/sqlite/*/*.c \
+	test/ffi/*/*.c \
 	)
 
 # Code blocks don't have newline at the end,

configure.py

@@ -686,6 +686,28 @@
     dest='shared_sqlite_libpath',
     help='a directory to search for the shared sqlite DLL')
 
+shared_optgroup.add_argument('--shared-ffi',
+    action='store_true',
+    dest='shared_ffi',
+    default=None,
+    help='link to a shared libffi DLL instead of static linking')
+
+shared_optgroup.add_argument('--shared-ffi-includes',
+    action='store',
+    dest='shared_ffi_includes',
+    help='directory containing libffi header files')
+
+shared_optgroup.add_argument('--shared-ffi-libname',
+    action='store',
+    dest='shared_ffi_libname',
+    default='ffi',
+    help='alternative libffi name to link to [default: %(default)s]')
+
+shared_optgroup.add_argument('--shared-ffi-libpath',
+    action='store',
+    dest='shared_ffi_libpath',
+    help='a directory to search for the shared libffi DLL')
+
 shared_optgroup.add_argument('--shared-temporal_capi',
     action='store_true',
     dest='shared_temporal_capi',
@@ -1017,6 +1039,12 @@
     default=None,
     help='build without SQLite (disables SQLite and Web Storage API)')
 
+parser.add_argument('--without-ffi',
+    action='store_true',
+    dest='without_ffi',
+    default=None,
+    help='build without FFI (Foreign Function Interface) support')
+
 parser.add_argument('--experimental-quic',
     action='store_true',
     dest='experimental_quic',
@@ -2233,6 +2261,43 @@ def without_sqlite_error(option):
 
   configure_library('sqlite', o, pkgname='sqlite3')
 
+def bundled_ffi_supported(os_name, target_arch):
+  supported = {
+    'freebsd': {'arm', 'arm64', 'x64'},
+    'linux': {'arm', 'arm64', 'x64'},
+    'mac': {'arm64', 'x64'},
+    'win': {'arm64', 'x64'},
+  }
+
+  if target_arch == 'x86':
+    target_arch = 'ia32'
+
+  return target_arch in supported.get(os_name, set())
+
+def configure_ffi(o):
+  use_ffi = not options.without_ffi
+
+  if use_ffi and not options.shared_ffi:
+    target_arch = o['variables']['target_arch']
+    if not bundled_ffi_supported(flavor, target_arch):
+      warn(f'FFI is disabled for {flavor}/{target_arch}: the bundled libffi '
+           'integration is not available on this platform. Use --shared-ffi '
+           'to provide a system libffi or --without-ffi to silence this '
+           'warning.')
+      use_ffi = False
+
+  o['variables']['node_use_ffi'] = b(use_ffi)
+
+  if options.without_ffi:
+    if options.shared_ffi:
+      error('--without-ffi is incompatible with --shared-ffi')
+    return
+
+  if not use_ffi:
+    return
+
+  configure_library('ffi', o, pkgname='libffi')
+
 def configure_quic(o):
   o['variables']['node_use_quic'] = b(options.experimental_quic and
                                       not options.without_ssl)
@@ -2686,6 +2751,7 @@ def make_bin_override():
 configure_library('ngtcp2', output, pkgname='libngtcp2')
 configure_lief(output);
 configure_sqlite(output);
+configure_ffi(output);
 configure_library('temporal_capi', output)
 configure_library('uvwasi', output)
 configure_library('zstd', output, pkgname='libzstd')