diff --git a/BUILDING.md b/BUILDING.md index 86d64decf1..64bfbf5b88 100644 --- a/BUILDING.md +++ b/BUILDING.md @@ -62,6 +62,11 @@ force a clean build by adding the `-c` flag in that case. To install the libraries and executables in `out/debug/` and `out/release/`, add the `-i` flag. The script offers more features described by executing `build.sh -h`. +For more specialized options, please also consider the following pages: + - `-d`: [`matdbg`](https://google.github.io/filament/dup/matdbg.html) + - `-t`: [`fgviewer`](https://google.github.io/filament/dup/fgviewer.html) + - `-b` and `-y`: [ASAN/UBSAN builds](https://google.github.io/filament/notes/asan_ubsan.html) + ### Filament-specific CMake Options The following CMake options are boolean options specific to Filament: diff --git a/CMakeLists.txt b/CMakeLists.txt index c21fcb0410..ebac70e970 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -753,12 +753,61 @@ function(combine_static_libs TARGET OUTPUT DEPS) endfunction() # ================================================================================================== -# Configuration for CMAKE_CROSSCOMPILING. +# Configuration importing/exporting prebuilt "/tools" executables # ================================================================================================== + +# In certain cases, we want the ability to separate the build type/flags (release, debug) of tools +# (matc, resgen, etc...) from filament. Cross compilation is one such case (e.g. building material +# with matc running on host while building filament for Android) [1]. Another example is when client +# wants to enable ASAN for filament but not the tool [2]. +# +# Here are the varibles that are used to determine behavior is such flows: +# - CMAKE_CROSSCOMPILING : Set by cmake to indicate the build's target platform is different +# from the host platform. +# - IMPORT_EXECUTABLES_DIR : This is the directory containing the /ImportExecutables-type.cmake +# which are then included in other CMakeLists.txt to enable finding targets that have been +# prebuilt. This is set by the client in their `cmake` invocation. +# - IMPORT_EXECUTABLES : Path to a file to for 1) exporting the prebuilt targets or 2) +# importing a previously exported targets. (Used internally and should not be set by client). +# - FILAMENT_EXPORT_PREBUILT_EXECUTABLES_DIR : A path set by the client to indicate that +# they wish to export the tools as prebuilts, and the corresponding targets will be recorded +# in a cmake file (i.e IMPORT_EXECUTABLES). IMPORT_EXECUTABLES will be set relative to the the +# given path. This will set FILAMENT_EXPORT_PREBUILT_EXECUTABLES=ON. +# - FILAMENT_IMPORT_PREBUILT_EXECUTABLES_DIR : A path set by the client to indicate that they wish +# to import the tools as prebuilts from a .cmake file. The location (IMPORT_EXECUTABLES) of the +# file is relative to the path given. This will set FILAMENT_IMPORT_PREBUILT_EXECUTABLES=ON. +# - IMPORT_PREBUILT_EXECUTABLES and EXPORT_PREBUILT_EXECUTABLES are internal booleans set to +# ON based on the prescence of FILAMENT_IMPORT_PREBUILT_EXECUTABLES_DIR and +# FILAMENT_EXPORT_PREBUILT_EXECUTABLES_DIR. +# +# In conclusion, for cases +# - [1] (crosscompiling), the client must set IMPORT_EXECUTABLES_DIR for both when they are building +# the tools and when they are building the target-platform filament. +# - [2] (all other instances), the client must set FILAMENT_EXPORT_PREBUILT_EXECUTABLES_DIR in +# the prebuilt exporting step, and set FILAMENT_IMPORT_PREBUILT_EXECUTABLES_DIR in the importing +# step. + +# TODO: Fold the cross compilation case into the more general FILAMENT_IMPORT/EXPORT variables. + +if (FILAMENT_EXPORT_PREBUILT_EXECUTABLES_DIR) + set(FILAMENT_EXPORT_PREBUILT_EXECUTABLES ON) + set(IMPORT_EXECUTABLES_DIR ${FILAMENT_EXPORT_PREBUILT_EXECUTABLES_DIR}) +endif() + +if (FILAMENT_IMPORT_PREBUILT_EXECUTABLES_DIR) + set(FILAMENT_IMPORT_PREBUILT_EXECUTABLES ON) + set(IMPORT_EXECUTABLES_DIR ${FILAMENT_IMPORT_PREBUILT_EXECUTABLES_DIR}) +endif() + if (WEBGL) set(IMPORT_EXECUTABLES ${FILAMENT}/${IMPORT_EXECUTABLES_DIR}/ImportExecutables-Release.cmake) else() - set(IMPORT_EXECUTABLES ${FILAMENT}/${IMPORT_EXECUTABLES_DIR}/ImportExecutables-${CMAKE_BUILD_TYPE}.cmake) + if (FILAMENT_EXPORT_PREBUILT_EXECUTABLES OR FILAMENT_IMPORT_PREBUILT_EXECUTABLES) + set(IMPORT_EXECUTABLES_BUILD_TYPE Prebuilt) + else() + set(IMPORT_EXECUTABLES_BUILD_TYPE ${CMAKE_BUILD_TYPE}) + endif() + set(IMPORT_EXECUTABLES ${FILAMENT}/${IMPORT_EXECUTABLES_DIR}/ImportExecutables-${IMPORT_EXECUTABLES_BUILD_TYPE}.cmake) endif() # ================================================================================================== @@ -917,6 +966,6 @@ if (IS_HOST_PLATFORM) endif() # Generate exported executables for cross-compiled builds (Android, WebGL, and iOS) -if (NOT CMAKE_CROSSCOMPILING) +if ((NOT CMAKE_CROSSCOMPILING AND NOT FILAMENT_IMPORT_PREBUILT_EXECUTABLES) OR FILAMENT_EXPORT_PREBUILT_EXECUTABLES) export(TARGETS matc cmgen filamesh mipgen resgen uberz glslminifier FILE ${IMPORT_EXECUTABLES}) endif() diff --git a/build.sh b/build.sh index c3cd3c9379..03cd17440e 100755 --- a/build.sh +++ b/build.sh @@ -77,6 +77,10 @@ function print_help { echo " meant for building the samples." echo " -P" echo " Enable perfetto traces on Android. Disabled by default on the Release build, enabled otherwise." + echo " -y build_type" + echo " Build the filament dependent tools (matc, resgen) separately from the project. This will set" + echo " the tools as prebuilts that filament target will then use to build. The built_type option" + echo " (debug|release) is meant to indicate the type of build of the resulting prebuilts." echo "" echo "Build types:" echo " release" @@ -217,6 +221,11 @@ OSMESA_OPTION="" IOS_BUILD_SIMULATOR=false BUILD_UNIVERSAL_LIBRARIES=false +ISSUE_SPLIT_BUILD=false +SPLIT_BUILD_TYPE="" +PREBUILT_TOOLS_DIR="" +IMPORT_EXECUTABLES_DIR_OPTION="-DIMPORT_EXECUTABLES_DIR=out" + BUILD_GENERATOR=Ninja BUILD_COMMAND=ninja BUILD_CUSTOM_TARGETS= @@ -242,6 +251,37 @@ function build_clean_aggressive { git clean -qfX android } +function build_tools_for_split_build { + local build_type_arg=$1 + local lc_build_type=$(echo "${build_type_arg}" | tr '[:upper:]' '[:lower:]') + PREBUILT_TOOLS_DIR="out/prebuilt-tools-${lc_build_type}" + + echo "Building tools for split build (${lc_build_type}) in ${PREBUILT_TOOLS_DIR}..." + mkdir -p "${PREBUILT_TOOLS_DIR}" + + pushd "${PREBUILT_TOOLS_DIR}" > /dev/null + + local lc_name=$(echo "${UNAME}" | tr '[:upper:]' '[:lower:]') + local architectures="" + if [[ "${lc_name}" == "darwin" ]]; then + if [[ "${BUILD_UNIVERSAL_LIBRARIES}" == "true" ]]; then + architectures="-DCMAKE_OSX_ARCHITECTURES=arm64;x86_64" + fi + fi + + cmake \ + -G "${BUILD_GENERATOR}" \ + -DFILAMENT_EXPORT_PREBUILT_EXECUTABLES_DIR=${PREBUILT_TOOLS_DIR} \ + -DCMAKE_BUILD_TYPE="${build_type_arg}" \ + ${WEBGPU_OPTION} \ + ${architectures} \ + ../.. + + ${BUILD_COMMAND} ${WEB_HOST_TOOLS} + + popd > /dev/null +} + function build_desktop_target { local lc_target=$(echo "$1" | tr '[:upper:]' '[:lower:]') local build_targets=$2 @@ -265,7 +305,7 @@ function build_desktop_target { if [[ ! -d "CMakeFiles" ]] || [[ "${ISSUE_CMAKE_ALWAYS}" == "true" ]]; then cmake \ -G "${BUILD_GENERATOR}" \ - -DIMPORT_EXECUTABLES_DIR=out \ + ${IMPORT_EXECUTABLES_DIR_OPTION} \ -DCMAKE_BUILD_TYPE="$1" \ -DCMAKE_INSTALL_PREFIX="../${lc_target}/filament" \ ${EGL_ON_LINUX_OPTION} \ @@ -331,7 +371,7 @@ function build_webgl_with_target { source "${EMSDK}/emsdk_env.sh" cmake \ -G "${BUILD_GENERATOR}" \ - -DIMPORT_EXECUTABLES_DIR=out \ + ${IMPORT_EXECUTABLES_DIR_OPTION} \ -DCMAKE_TOOLCHAIN_FILE="${EMSDK}/upstream/emscripten/cmake/Modules/Platform/Emscripten.cmake" \ -DCMAKE_BUILD_TYPE="$1" \ -DCMAKE_INSTALL_PREFIX="../webgl-${lc_target}/filament" \ @@ -404,7 +444,7 @@ function build_android_target { if [[ ! -d "CMakeFiles" ]] || [[ "${ISSUE_CMAKE_ALWAYS}" == "true" ]]; then cmake \ -G "${BUILD_GENERATOR}" \ - -DIMPORT_EXECUTABLES_DIR=out \ + ${IMPORT_EXECUTABLES_DIR_OPTION} \ -DCMAKE_BUILD_TYPE="$1" \ -DFILAMENT_NDK_VERSION="${FILAMENT_NDK_VERSION}" \ -DCMAKE_INSTALL_PREFIX="../android-${lc_target}/filament" \ @@ -638,7 +678,7 @@ function build_ios_target { if [[ ! -d "CMakeFiles" ]] || [[ "${ISSUE_CMAKE_ALWAYS}" == "true" ]]; then cmake \ -G "${BUILD_GENERATOR}" \ - -DIMPORT_EXECUTABLES_DIR=out \ + ${IMPORT_EXECUTABLES_DIR_OPTION} \ -DCMAKE_BUILD_TYPE="$1" \ -DCMAKE_INSTALL_PREFIX="../ios-${lc_target}/filament" \ -DIOS_ARCH="${arch}" \ @@ -810,7 +850,7 @@ function check_debug_release_build { pushd "$(dirname "$0")" > /dev/null -while getopts ":hacCfgimp:q:uvWslwedtk:bVx:S:X:P" opt; do +while getopts ":hacCfgimp:q:uvWslwedtk:bVx:S:X:Py:" opt; do case ${opt} in h) print_help @@ -979,6 +1019,20 @@ while getopts ":hacCfgimp:q:uvWslwedtk:bVx:S:X:P" opt; do ;; X) OSMESA_OPTION="-DFILAMENT_OSMESA_PATH=${OPTARG}" ;; + y) + ISSUE_SPLIT_BUILD=true + SPLIT_BUILD_TYPE=${OPTARG} + case $(echo "${SPLIT_BUILD_TYPE}" | tr '[:upper:]' '[:lower:]') in + debug|release) + ;; + *) + echo "Unknown build type for -y: ${SPLIT_BUILD_TYPE}" + echo "Build type must be one of [debug|release]" + echo "" + exit 1 + ;; + esac + ;; \?) echo "Invalid option: -${OPTARG}" >&2 echo "" @@ -1013,6 +1067,13 @@ done validate_build_command +if [[ "${ISSUE_SPLIT_BUILD}" == "true" ]]; then + # Capitalize first letter of SPLIT_BUILD_TYPE + SPLIT_BUILD_TYPE_CAPITALIZED="$(echo ${SPLIT_BUILD_TYPE:0:1} | tr '[:lower:]' '[:upper:]')${SPLIT_BUILD_TYPE:1}" + build_tools_for_split_build "${SPLIT_BUILD_TYPE_CAPITALIZED}" + IMPORT_EXECUTABLES_DIR_OPTION="-DFILAMENT_IMPORT_PREBUILT_EXECUTABLES_DIR=${PREBUILT_TOOLS_DIR}" +fi + if [[ "${ISSUE_CLEAN}" == "true" ]]; then build_clean fi diff --git a/docs_src/build/duplicates.json b/docs_src/build/duplicates.json index 9e232d5f14..24d2b1815b 100644 --- a/docs_src/build/duplicates.json +++ b/docs_src/build/duplicates.json @@ -46,6 +46,9 @@ "libs/matdbg/README.md": { "dest": "dup/matdbg.md" }, + "libs/fgviewer/README.md": { + "dest": "dup/fgviewer.md" + }, "tools/normal-blending/README.md": { "dest": "dup/normal_blending.md" }, diff --git a/docs_src/src_mdbook/src/SUMMARY.md b/docs_src/src_mdbook/src/SUMMARY.md index f6f5faa58f..be62199051 100644 --- a/docs_src/src_mdbook/src/SUMMARY.md +++ b/docs_src/src_mdbook/src/SUMMARY.md @@ -32,6 +32,7 @@ - [Libraries](./notes/libs.md) - [bluegl](./dup/bluegl.md) - [bluevk](./dup/bluevk.md) + - [fgviewer](./dup/fgviewer.md) - [filamat](./dup/filamat.md) - [gltfio](./dup/gltfio.md) - [iblprefilter](./dup/iblprefilter.md) diff --git a/docs_src/src_mdbook/src/notes/asan_ubsan.md b/docs_src/src_mdbook/src/notes/asan_ubsan.md index 230795c8f4..ee65cafcc4 100644 --- a/docs_src/src_mdbook/src/notes/asan_ubsan.md +++ b/docs_src/src_mdbook/src/notes/asan_ubsan.md @@ -2,11 +2,17 @@ ## Enabling -When building though build.sh, pass the `-b` flag. This sets the cmake variable +When building though `build.sh`, pass the `-b` flag. This sets the cmake variable `FILAMENT_ENABLE_ASAN_UBSAN=ON` which eventually passes `"-fsanitize=address -fsanitize=undefined"` to all compile and link operations. -If building through CMake directly, or an IDE like CLion that doesn't use build.sh, instead pass +It might be desirable to pair the `-b` with `-y release`. The `-y` flag indicates that targets +in `/tools` will be built separately from the filament target, and the filament build depends on +the `/tools` targets as prebuilt binaries. This separation reduces ASAN/UBSAN build time +considerably. This option assumes that the user is trying to catch sanitization issues for +filament and not the tools that are used to build filament. + +If building through CMake directly, or an IDE like CLion that doesn't use `build.sh`, instead pass `-DFILAMENT_ENABLE_ASAN_UBSAN=ON` to cmake in order to get the same result. ## Getting memory leak detection on Mac diff --git a/filament/CMakeLists.txt b/filament/CMakeLists.txt index 7441b7e8e0..23f0382707 100644 --- a/filament/CMakeLists.txt +++ b/filament/CMakeLists.txt @@ -363,7 +363,7 @@ add_definitions( # Generate all .filamat: default material, skyboxes, and post-process # ================================================================================================== -if (CMAKE_CROSSCOMPILING) +if (CMAKE_CROSSCOMPILING OR FILAMENT_IMPORT_PREBUILT_EXECUTABLES) include(${IMPORT_EXECUTABLES}) endif() diff --git a/libs/fgviewer/CMakeLists.txt b/libs/fgviewer/CMakeLists.txt index 9f2ccc4c4b..33bad8b290 100644 --- a/libs/fgviewer/CMakeLists.txt +++ b/libs/fgviewer/CMakeLists.txt @@ -4,7 +4,7 @@ project(fgviewer C ASM) set(TARGET fgviewer) set(PUBLIC_HDR_DIR include) -if (CMAKE_CROSSCOMPILING) +if (CMAKE_CROSSCOMPILING OR FILAMENT_IMPORT_PREBUILT_EXECUTABLES) include(${IMPORT_EXECUTABLES}) endif() diff --git a/libs/filagui/CMakeLists.txt b/libs/filagui/CMakeLists.txt index dac013ce7f..87c4799ea7 100644 --- a/libs/filagui/CMakeLists.txt +++ b/libs/filagui/CMakeLists.txt @@ -26,7 +26,7 @@ set(SRCS # Compile material files (mat) into headers (inc) # ================================================================================================== -if (CMAKE_CROSSCOMPILING) +if (CMAKE_CROSSCOMPILING OR FILAMENT_IMPORT_PREBUILT_EXECUTABLES) include(${IMPORT_EXECUTABLES}) endif() diff --git a/libs/filamentapp/CMakeLists.txt b/libs/filamentapp/CMakeLists.txt index 2af83c3f18..257f511ea1 100644 --- a/libs/filamentapp/CMakeLists.txt +++ b/libs/filamentapp/CMakeLists.txt @@ -83,7 +83,7 @@ endif() # Compile resources # ================================================================================================== -if (CMAKE_CROSSCOMPILING) +if (CMAKE_CROSSCOMPILING OR FILAMENT_IMPORT_PREBUILT_EXECUTABLES) include(${IMPORT_EXECUTABLES}) endif() diff --git a/libs/gltfio/CMakeLists.txt b/libs/gltfio/CMakeLists.txt index 226a99bacf..9219dec3bb 100644 --- a/libs/gltfio/CMakeLists.txt +++ b/libs/gltfio/CMakeLists.txt @@ -68,7 +68,7 @@ set(SRCS set(RESOURCE_DIR ${CMAKE_CURRENT_BINARY_DIR}) -if (CMAKE_CROSSCOMPILING) +if (CMAKE_CROSSCOMPILING OR FILAMENT_IMPORT_PREBUILT_EXECUTABLES) include(${IMPORT_EXECUTABLES}) endif() diff --git a/libs/iblprefilter/CMakeLists.txt b/libs/iblprefilter/CMakeLists.txt index f90334d471..8ba2fdfaa8 100644 --- a/libs/iblprefilter/CMakeLists.txt +++ b/libs/iblprefilter/CMakeLists.txt @@ -36,7 +36,7 @@ list(APPEND SRCS ${RESGEN_SOURCE}) # Generate all .filamat: default material, skyboxes, and post-process # ================================================================================================== -if (CMAKE_CROSSCOMPILING) +if (CMAKE_CROSSCOMPILING OR FILAMENT_IMPORT_PREBUILT_EXECUTABLES) include(${IMPORT_EXECUTABLES}) endif() diff --git a/libs/matdbg/CMakeLists.txt b/libs/matdbg/CMakeLists.txt index 566aec3fd3..f2f8c97d5f 100644 --- a/libs/matdbg/CMakeLists.txt +++ b/libs/matdbg/CMakeLists.txt @@ -4,7 +4,7 @@ project(matdbg C ASM) set(TARGET matdbg) set(PUBLIC_HDR_DIR include) -if (CMAKE_CROSSCOMPILING) +if (CMAKE_CROSSCOMPILING OR FILAMENT_IMPORT_PREBUILT_EXECUTABLES) include(${IMPORT_EXECUTABLES}) endif() diff --git a/samples/CMakeLists.txt b/samples/CMakeLists.txt index f673898ed3..de8222d45e 100644 --- a/samples/CMakeLists.txt +++ b/samples/CMakeLists.txt @@ -48,7 +48,7 @@ if (NOT FILAMENT_SUPPORTS_WEBGPU) set(MATERIAL_SRCS ${MATERIAL_SRCS} materials/pointSprites.mat) endif () -if (CMAKE_CROSSCOMPILING) +if (CMAKE_CROSSCOMPILING OR FILAMENT_IMPORT_PREBUILT_EXECUTABLES) include(${IMPORT_EXECUTABLES}) endif() diff --git a/shaders/CMakeLists.txt b/shaders/CMakeLists.txt index 7109c239c2..e5ced371aa 100644 --- a/shaders/CMakeLists.txt +++ b/shaders/CMakeLists.txt @@ -3,7 +3,7 @@ project(shaders C ASM) set(TARGET shaders) -if (CMAKE_CROSSCOMPILING) +if (CMAKE_CROSSCOMPILING OR FILAMENT_IMPORT_PREBUILT_EXECUTABLES) include(${IMPORT_EXECUTABLES}) endif()