Fmake Configurations

Configuration Instructions

There are two types of configuration files, which are：

• Project configurations _project.yaml
• Module configurations _build.yaml

The Fmake tool reads the project configuration _project.yaml to get the global configuration and module search path, and then reads the configuration file _build.yaml for each module to get the complete compiled configuration of the solution. The module configurations are further divided into source code module configurations and external library module configurations.

Solution Project Configurations (e.g. flexi.sln)

Entry file _project.yaml：

# Project name, the name of the generated solution(flexi.sln)
name: flexi
# Project module
modules:
  # Module search path that will recursively retrieve all _build.yaml files
  searchPaths:
    # Relative and absolute paths can be configured
    - source
    - include/flexi/extern
    
# Configuration items
spec:
  # Including header files path (global effective for all project modules)
  includePaths:
  # Relative and absolute paths can be configured
  - include
  - extern
  # Global macro definitions
  definitions:
    - USE_MD
  # Debug global macro definitions
  debugDefinitions:
    - XXXX_DEBUG
  # Release global macro definitions
  releaseDefinitions:

  # Global compile options
  compileOptions:
    - MP
    - Zi
  debugCompileOptions:
  releaseCompileOptions:

  # Global link options
  linkOptions:
    - MAP
  debugLinkOptions:
  releaseLinkOptions:

  # windows MT or MD
  runtimeLibrary: MD

  # Release Path
  exportPath:

# Platform-specific configurations
targets:
  - platform: windows
    # Platform-specific configuration, only effective with the current platform, the configuration items are the same as the global configuration
    spec:
      definitions:
      linkOptions:
      ...
  - platform: android
    spec:
  - platform: orbis
    spec:
  - platform: ios
    spec:

Configuration items seem to be numerous, but in actual use, configuration items that are not required can be defaulted. Here is the simplest project configuration.

# Project name, the name of the generated solution(flexi.sln)
name: flexi
# Project modules
modules:
  # Module search path. It will recursively retrieve all the _build.yaml files
  searchPaths:
    # Relative and absolute paths can be configured
    - source
    - include/flexi/extern
# Including header files path (global effective for all project modules)
includePaths:
  # Relative and absolute paths can be configured
  - include
  - extern

Module Configurations (e.g. fx_fmod)

Source Code Module Configurations

The main purpose of the source module configuration is to configure the properties related to the compiled module code. The following parameters can be configured in this configuration file: macro definitions, compile options, link options, paths including header files, etc. Please refer to the following configuration file instructions for details.

Configuration file _build.yaml：

# Type
kind: Module
# Module Name
name: fx_fmod
# Public configurations
spec:
  # Compile the static or dynamic library or executable files [SHARED|STATIC|EXEC]. Executable files will generate exe files under Windows, and apk files under Android, namely, the run file of the corresponding platform.
  targetType: SHARED
  # Compiled target name, same as the module name by default
  targetName:
  # Macro definitions(list)
  definitions:
    - FX_SOUND_EXPORTS
  # Deubg macro definitions(list)
  debugDefinitions:
  # Release macro definitions(list)
  releaseDefinitions:
  # Profile macro definitions(list)
  profileDefinitions:

  # Global compile options
  compileOptions:
  debugCompileOptions:
  releaseCompileOptions:
  profileCompileOptions:

  # Global link options
  linkOptions:
  debugLinkOptions:
  releaseLinkOptions:
  profileLinkOptions:

  # Include paths for header files
  includePaths:
  # Dependent dynamic library paths at runtime
  runtimeLibraryPaths:
  # Dependent static library paths
  compileLibraryPaths:
  # Enable reflection detection and code generation(reflang generation)
  codeGenEnable: false
  # Used to specify the path to the reflection-generated code, dynamically link at compile time (not yet implemented)
  codeGenPaths:
  # Dependent modules (deprecated), please use depends
  dependModules:
  # Dependent third-party library modules(deprecated), please use depends
  dependExterns:
    - fmod_studio
  # Dependent any type of module name (recommended)
  depends:
    - openssl
    - fx_http
    - other
  debugDepends:
  releaseDepends:
  profileDepends:

  # Source code root path, which is the current directory by default. If modified, sourceIncludes and sourceExcludes also need to write relative paths based on this path.
  sourceBasePath:
  # Directories included in the source code(source code files that are not in this module directory )
  sourceIncludes:
  # Directories excluded in the source code(directories or source code files in this module directory that are not involved in the compilation)
  sourceExcludes:
    - path/filename.cpp
    - path/exclue/
  # Support ASM assembly
  asm: false
  # This module supports exporting doxygen documentations 
  docs: true
  # Release library location
  exportPath: 

# Platform-specific configurations. When compiling for the specified platform ${platform} , this module will only participate in the compilation if ${platform} appears in the following configuration, otherwise it will skip.
# E.g. Compile target platform [iOS]. There is no corresponding target configuration in this module configuration, so this module will not participate in the iOS compilation.
targets:
  # Windows-specific configurations
  - platform: windows
    # It has the same fields as the public spec definition. The single-value type has higher priority than the global configuration, and the list type merges the global type.
    spec:
      # Compiled as the static library under this platform, which precedes over the global dynamic library
      targetType: STATIC
      # Macro definition
      definitions:
        - _WIN64
        - _WINDOWS
        - _USRDLL

  # Android platform
  - platform: android
    spec:
      targetType: SHARED
      # Macro definitions
      definitions:
        - XXX_ANDROID
  # Photoshop platform
  - platform: orbis

Reference example：

# Simple module
# Type
kind: Module
# Module Name
name: fx_vm
spec:
  # Compile the static or dynamic library(SHARED or STATIC)
  targetType: SHARED
  # Macro definitions
  definitions:
    - FXVM_EXPORTS
  # Dependent modules
  depends:
    - llvm
targets:
  # WINDOWS
  - platform: windows

---

# Slightly more complex modules
# Type
kind: Module
# Module Name
name: fx_component
spec:
  # Compile static or dynamic libraries(SHARED or STATIC)
  targetType: SHARED
  # Macro definitions
  definitions:
    - PLATFORM_WINDOWS
    - FX_COMPONENT_EXPORTS
    - FX_OBJECT_IMPORTS
    - FX_INPUT_IMPORTS
    - _CRT_NONSTDC_NO_DEPRECATE
    - _CRT_SECURE_NO_WARNINGS
    - USE_CIRCULAR_DEPENDENCY_LOAD_DEFERRING
  codeGenEnable: true
  sourceIncludes:
    - ../../extern/quicklz/quicklz.c
  # Directories excluded in the source code
  sourceExcludes:
    - navigation/recast_nav_mesh_component.cpp
    - navigation/navigation_system.cpp
    - navigation/nav_mesh_bounds_volume.cpp
  # Dependent modules
  depends:
    - physics_nvidia
    - fx_input
    - fx_object
targets:
  # WINDOWS
  - platform: windows
    spec:
      definitions:
        - _WINDOWS
        - _USRDLL
  - platform: android

External Library Module Configurations

The main purpose of the external library configuration is to identify the header file paths, link paths and program library paths of the external library. When the source code module depends on this external library via depends, the corresponding configuration will be made for the source code module according to the current compilation environment.

The configuration list is as follows:

# Declare module type
kind: Extern
#  Declare module name, so that other modules use this name for dependencies, depends
name: libcurl
# Public configuration, effective globally
spec:
  # Include paths for header files. If all platforms use the same header file directory, configure it here.
  includePaths:
    - include
# The configuration will take effect only when the following conditions are met. If no conditions are met, then ignore the following configuration, but the global configuration above will still take effect.
rules:
  # The module can be referenced correctly when the current compilation conditions are met.
  # This rule can use AND OR. For supported variables, please refer to the Global Variable Reference Table section.
  - if: "${FX_PLATFORM} == ${FX_PLATFORM_WINDOWS}"
    # The configuration under rules share the same configuration items as the global configuration of spec.
    spec:
      # Include paths for header files. Dependent modules will automatically configure the header file path.
      includePaths:
      # Only effective with certain compilation types.
      debugIncludePaths:
      releaseIncludePaths:
      profileIncludePaths:

      # Link library directory. Dependent modules will automatically configure this link path.
      libraryDirectories:
      # Only effective with certain compilation types.
      debugLibraryDirectories:
      releaseLibraryDirectories:
      profileLibraryDirectories:

      # Runtime library path, specify the path of the library, dependent modules will automatically link the library
      # Relative paths relative to the path of this file can be configured, and paths relative to ${libraryDirectories} can also be configured.
      # If this library file can not be found in this path or in ${libraryDirectories}, then the file is considered to be a system library and will be searched for in the system library when compiling.
      runtimeLibraryPaths:
      # Only effective with certain compilation types
      debugRuntimeLibraryPaths:
      releaseRuntimeLibraryPaths:
      profileRuntimeLibraryPaths:

      # Static library paths
      compileLibraryPaths:
      debugCompileLibraryPaths:
      releaseCompileLibraryPaths:
      profileCompileLibraryPaths:

Reference example：

kind: Extern
name: fx_model
rules:
  - if: '${FX_PLATFORM} == ${FX_PLATFORM_WINDOWS} && ${FX_ARCH} == ${FX_ARCH_X64} && ${FX_TOOLSET} == FX_TOOLSET_V140'
    spec:
      debugLibraryDirectories:
        - debug_md_vs2015x64
      releaseLibraryDirectories:
        - release_md_vs2015x64
      # Dependent static library paths
      compileLibraryPaths:
        - fx_model.lib
  - if: '${FX_PLATFORM} == ${FX_PLATFORM_WINDOWS} && ${FX_ARCH} == ${FX_ARCH_X64} && ${FX_TOOLSET} == FX_TOOLSET_V142'
    spec:
      debugLibraryDirectories:
        - debug_md_vs2019x64
      releaseLibraryDirectories:
        - release_md_vs2019x64
      # Dependent static library paths
      compileLibraryPaths:
        - fx_model.lib

Global Variable Reference Table

Some variables that can be used in the prerequisites when configuring external library modules. For example, ${FX_PLATFORM} STREQUAL ${FX_PLATFORM_ANDROID} means the current compilation platform is Android and ${FX_ARCH} STREQUAL ${FX_ARCH_ARM64} means the current compilation architecture is ARM 64-bit. And different prerequisites can be combined according to these variables.

Variable	Description
FX_PLATFORM	Current compilation platform
FX_PLATFORM_WINDOWS	WINDOWS platform
FX_PLATFORM_ANDROID	ANDROID platform
FX_PLATFORM_IOS	iOS platform
FX_PLATFORM_ORBIS	PS4 platform
FX_PLATFORM_LINUX	LINUX platform
----	----
FX_ARCH	Current compilation architecture
FX_ARCH_x32	32-bit
FX_ARCH_x64	64-bit
FX_ARCH_ARM	ARM 32-bit
FX_ARCH_ARM64	ARM 64-bit
----	----
FX_TOOLSET	Current compilation tool, optional values [FX_TOOLSET_V140, FX_TOOLSET_V141, FX_TOOLSET_V142, FX_TOOLSET_CLANG, FX_TOOLSET_GCC]

Note: Try to use forward slash / as much as possible for paths in all configuration files. Paths using backslash \ will cause problems when compiling on non-Windows platforms.

VS Code IntelliSense

1. Open the workspace with VS Code and install the plugin redhat.vscode-yaml.

   Run the batch /path/to/engine/build/vscode/vscode_open.bat to open the workspace; or use VS Code to open the file /path/to/engine/build/vscode/flexi.code-workspace. Install the plugin redhat.vscode-yaml.

2. Open _build.yaml and _peojct.yaml in the workspace.

   At this point, VS Code will identify the field property configuration of Fmake and give an intelliSense.

Adding Global IntelliSense:

You can add global intelliSense to VS Code as follows:

1. Press Ctrl+Shift+P to open the Command panel.
2. Enter Open User Settings (JSON) to open the User Global Settings file.
3. In the Settings file, add the setting of yaml.schemas and the mapping of Json Schema in the form of key:value. Fill in the key with the absolute path or network path URL of the Schema. Here is an example:

{
  // ...
        "yaml.schemas": {
            "/path/to/fmake-module-schema.json": "_build.yaml",
            "/path/to/fmake-project-schema.json": "_project.yaml"
        },
  // ...
}

Q&A

Q1: How to update the code and development on SVN regularly?

A: After updating the SVN code and resources normally, execute project\source\generate_sln.bat or generate_sln_vs2019.bat and then open flexi.sln.

If the compilation fails (prompting missing code files, link failure, etc.), please execute project\source\generate_sln.bat or generate_sln_vs2019.bat first to solve the problem.

Q2: What to do if code files are added, deleted, or moved?

A: Just re-run the bat (windows_project\source\generate_sln.bat) that generates the solution.

Q3: How to modify YAML if a folder/code file is only applied to a certain platform?

A: Taking the fx_render module as an example, the PS platform has added some directories and files which are exclusive to this platform as shown below. It only needs to be configured under the sourceIncludes of the corresponding platform according to the specifications as follows.

# Type
kind: Module
# Module Name
name: fx_render
spec:
  # ...
targets:
  # WINDOWS
  - platform: windows
    spec:
      definitions: [_WIN64, _WINDOWS, _USRDLL]
      includePaths:
        - ../../extern/shaderc/include
        - ../../extern/dxc/include
        - ../../extern/opengles
      sourceIncludes:
        - dll_main.cpp
      # Source exclude directory
      sourceExcludes:
        - backends/vulkan/volk.c
        - backends/vulkan/volk.h

Q4: How to modify YAML if a folder/code file needs to be excluded on a certain platform?

A: Taking the fx_render module as an example, the Android platform excludes some directories and files as shown below. Follow the specs below to configure it under sourceExcludes of the corresponding platform.

# Type
kind: Module
# Module Name
name: fx_render
spec:
  # ...
targets:
  # WINDOWS
  - platform: windows
    spec:
      definitions: [_WIN64, _WINDOWS, _USRDLL]
      includePaths:
        - ../../extern/shaderc/include
        - ../../extern/dxc/include
        - ../../extern/opengles
      sourceIncludes:
        - dll_main.cpp
      # Source exclude directory
      sourceExcludes:
        - backends/vulkan/volk.c
        - backends/vulkan/volk.h

Q5: How to configure YAML if a project depends on other modules?

A: Taking the fx_render module as an example, modules that all platforms depend on can be configured in the global configuration.

# Type
kind: Module
# Module Name
name: fx_render
spec:
  # Compile static or dynamic libraries
  targetType: SHARED
  # Source extra include directories
  sourceIncludes:
    - ../../include/flexi/utils/city.cc
    - ../../include/flexi/utils/city.h
    - ../../extern/basis/zstd/zstddeclib.c
    - ../../extern/basis/transcoder/basisu_transcoder.cpp
    - ../../extern/enkiTS/TaskScheduler.cpp
    - ../../extern/enkiTS/TaskScheduler_c.cpp
    - ../../extern/spirv_cross
  # Dependent module
  depends:
    - fx_common_utils
    - dxsdk
    - xess
    - tbb
    - freetype
    - harfbuzz
  # Generate documentation
  docs: true
  # Generate raw text
  i18n: true
targets:
  # WINDOWS
  - platform: windows

If it is a module that only this platform depends on, configure it in the corresponding platform, as shown below, only the Android platform depends on shaderc and log.

# Type
kind: Module
# Module Name
name: fx_render
spec:
  # Compile static or dynamic libraries
  targetType: SHARED
  # ...
  # Dependent module
  depends:
    - fx_common_utils
    - dxsdk
    - xess
    - tbb
    - freetype
    - harfbuzz
  # Generate documentation
  docs: true
  # Generate raw text
  i18n: true
targets:
  # WINDOWS
  - platform: windows
    spec:
      # ...
  # ANDROID
  - platform: android
    spec:
      # Source exclude directory
      sourceExcludes:
        - dlss/
        - texture_streaming/streaming_texture_manager.cpp
        - software_occlusion_culling/
        - openvr/
        - openxr/
        - backends/null
        - backends/vulkan/volk.c
        - backends/vulkan/volk.h
      depends:
        - shaderc
        - log

Q6: How to configure YAML if a project depends on a lib/dll of a third-party library?

A: Taking freetype as an example, debugRuntimeLibraryPaths and releaseRuntimeLibraryPaths are used to configure the dll of the third-party library, while debugCompileLibraryPaths and releaseCompileLibraryPaths are used to configure the third-party lib.

kind: Extern
name: freetype
# Public configuration
spec:
  # Include header file path
  includePaths:
    - include
rules:
  # windows 64-bit MD
  - if: '${FX_PLATFORM} == ${FX_PLATFORM_WINDOWS} && ${FX_ARCH} == ${FX_ARCH_X64}'
    spec:
      # Include header file path
      includePaths:
      # Runtime depends on dynamic library path
      runtimeLibraryPaths:
      # Depend on static library path
      debugCompileLibraryPaths:
        - lib/freetype_vs2015_x64_md_d.lib
      releaseCompileLibraryPaths:
        - lib/freetype_vs2015_x64_md.lib

Q7: How to configure reflang command lines in the Fmake configuration files? (How the Engine reflection code is generated)

A: Taking the fx_render module as an example, just configure codeGenEnable: true in the module.

# Type
kind: Module
# Module Name
name: fx_render
spec:
  # Compile static or dynamic libraries
  targetType: SHARED
  # Source extra include directories
  sourceIncludes:
    - ../../include/flexi/utils/city.cc
    - ../../include/flexi/utils/city.h
    - ../../extern/basis/zstd/zstddeclib.c
    - ../../extern/basis/transcoder/basisu_transcoder.cpp
    - ../../extern/enkiTS/TaskScheduler.cpp
    - ../../extern/enkiTS/TaskScheduler_c.cpp
    - ../../extern/spirv_cross
  # Enable reflection detection
  codeGenEnable: true
  # Dependent module
  depends:
    - fx_common_utils
    - dxsdk
    - xess
    - tbb
    - freetype
    - harfbuzz
  
  # Generate documentation
  docs: true
  # Generate raw text
  i18n: true