Fmake配置

配置说明

配置文件分为两种，分别为：

• 工程配置 _project.yaml
• 模块配置 _build.yaml

Fmake工具通过读取工程配置 _project.yaml，得到全局配置和模块检索路径，进而读取各个模块的配置文件_build.yaml，最终得到完整的解决方案编译配置。 其中模块配置又分为源码模块和外部库模块。

解决方案工程配置（比如：flexi.sln）

入口文件 _project.yaml：

# 工程名称,生成的解决方案名称（flexi.sln）
name: flexi
# 工程模块
modules:
  # 模块搜索路径，会递归检索所有的_build.yaml文件
  searchPaths:
    # 可配置相对路径和绝对路径
    - source
    - include/flexi/extern

# 配置项
spec:
  # 包含头文件路径(全局，所有工程模块生效)
  includePaths:
  # 可配置相对路径和绝对路径
  - include
  - extern
  # 全局宏定义
  definitions:
    - USE_MD
  # Debug全局宏定义
  debugDefinitions:
    - XXXX_DEBUG
  # Release全局宏定义
  releaseDefinitions:

  # 全局编译选项
  compileOptions:
    - MP
    - Zi
  debugCompileOptions:
  releaseCompileOptions:

  # 全局链接选项
  linkOptions:
    - MAP
  debugLinkOptions:
  releaseLinkOptions:

  # windows MT或MD
  runtimeLibrary: MD

  # 发布路径
  exportPath:

# 各个平台差异配置
targets:
  - platform: windows
    # 平台特殊配置，仅在当前平台生效，配置项同全局配置
    spec:
      definitions:
      linkOptions:
      ...
  - platform: android
    spec:
  - platform: orbis
    spec:
  - platform: ios
    spec:

配置项看起来很多，但实际使用中，不需要配置项的可以缺省，下面是一个最简单的工程配置。

# 工程名称,生成的解决方案名称（flexi.sln）
name: flexi
# 工程模块
modules:
  # 模块搜索路径，会递归检索所有的_build.yaml文件
  searchPaths:
    # 可配置相对路径和绝对路径
    - source
    - include/flexi/extern
# 包含头文件路径(全局，所有工程模块生效)
includePaths:
  # 可配置相对路径和绝对路径
  - include
  - extern

模块配置（比如：fx_fmod）

源码模块配置

源码模块配置主要的作用是用来配置编译模块代码相关属性的，在这个配置文件里可以配置如下参数：宏定义、编译选项、链接选项、包含头文件路径等，详情请见下面配置文件说明。

配置文件_build.yaml：

# 类型
kind: Module
# 模块名称
name: fx_fmod
# 公共配置
spec:
  # 编译静态库或者动态库或可执行文件 [SHARED|STATIC|EXEC]，可执行文件在windows下会产生exe， Android下会产生apk，即对应平台的运行文件
  targetType: SHARED
  # 编译的目标名称，默认同模块名一致
  targetName:
  # 宏定义（列表）
  definitions:
    - FX_SOUND_EXPORTS
  # Deubg宏定义（列表）
  debugDefinitions:
  # Release宏定义（列表）
  releaseDefinitions:
  # Profile宏定义（列表）
  profileDefinitions:

  # 全局编译选项
  compileOptions:
  debugCompileOptions:
  releaseCompileOptions:
  profileCompileOptions:

  # 全局链接选项
  linkOptions:
  debugLinkOptions:
  releaseLinkOptions:
  profileLinkOptions:

  # 包含头文件路径
  includePaths:
  # 运行时依赖动态库路径
  runtimeLibraryPaths:
  # 依赖静态库路径
  compileLibraryPaths:
  # 开启反射检测和代码生成(reflang生成)
  codeGenEnable: false
  # 用于指定反射生成代码的路径，编译时动态链接(未实现)
  codeGenPaths:
  # 依赖模块(废弃), 请使用depends
  dependModules:
  # 依赖第三方库模块(废弃), 请使用depends
  dependExterns:
    - fmod_studio
  # 依赖任意类型的模块名(推荐)
  depends:
    - openssl
    - fx_http
    - other
  debugDepends:
  releaseDepends:
  profileDepends:

  # 源码根路径，默认当前目录，如果修改，sourceIncludes和sourceExcludes也需要根据此路径写相对路径
  sourceBasePath:
  # 源码包含目录(不在本模块目录下的源码文件)
  sourceIncludes:
  # 源码排除目录(本模块目录下不参与编译的 目录 或 源码文件)
  sourceExcludes:
    - path/filename.cpp
    - path/exclue/
  # 支持ASM汇编
  asm: false
  # 本模块支持导出doxygen文档 
  docs: true
  # 发布库位置
  exportPath: 

# 平台特需配置, 在编译指定平台 ${platform}时，仅在${platform}出现在以下配置中，本模块才会参与编译，否则跳过
# 如：编译目标平台[iOS], 此模块配置中没有对应的目标配置，则此模块不参与iOS的编译。
targets:
  # WINDOWS特需配置
  - platform: windows
    # 与公共的spec定义具有相同字段，单值类型优先级高于全局配置，列表类型则对全局类型进行合并
    spec:
      # 该平台下编译为静态库，优先于全局的动态库
      targetType: STATIC
      # 宏定义
      definitions:
        - _WIN64
        - _WINDOWS
        - _USRDLL

  # 安卓平台
  - platform: android
    spec:
      targetType: SHARED
      # 宏定义
      definitions:
        - XXX_ANDROID
  # PS平台
  - platform: orbis

参考示例：

# 简单的模块
# 类型
kind: Module
# 模块名称
name: fx_vm
spec:
  # 编译静态库或者动态库 （SHARED或STATIC）
  targetType: SHARED
  # 宏定义
  definitions:
    - FXVM_EXPORTS
  # 依赖模块
  depends:
    - llvm
targets:
  # WINDOWS
  - platform: windows

---

# 稍微复杂一些的模块
# 类型
kind: Module
# 模块名称
name: fx_component
spec:
  # 编译静态库或者动态库（SHARED或STATIC）
  targetType: SHARED
  # 宏定义
  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
  # 源码排除目录
  sourceExcludes:
    - navigation/recast_nav_mesh_component.cpp
    - navigation/navigation_system.cpp
    - navigation/nav_mesh_bounds_volume.cpp
  # 依赖模块
  depends:
    - physics_nvidia
    - fx_input
    - fx_object
targets:
  # WINDOWS
  - platform: windows
    spec:
      definitions:
        - _WINDOWS
        - _USRDLL
  - platform: android

外部库模块配置

外部库配置主要的作用是标识外部库的头文件路径、链接路径和程序库的路径，源码模块通过 depends 依赖此外部库时，会根据当前编译环境为源码模块进行相应的配置。

配置清单如下：

# 声明模块类型
kind: Extern
# 声明模块名，别的模块使用该名称进行依赖，depends
name: libcurl
# 公共配置，全局生效
spec:
  # 包含头文件路径，如果所有平台使用同一份头文件目录时，可以在此配置
  includePaths:
    - include
# 限定条件，仅符合下才会生效，如果未发现符合的条件，则忽略以下配置，但上面的全局配置仍会生效
rules:
  # 符合当前编译条件时，该模块可以被正确引用
  # 该规则可以使用 AND OR，支持的变量请参考<全局变量参照表>
  - if: "${FX_PLATFORM} == ${FX_PLATFORM_WINDOWS}"
    # 限定条件下的配置，和全局配置的spec拥有相同的配置项
    spec:
      # 包含头文件路径, 依赖的模块会自动配置该头文件路径
      includePaths:
      # 仅特定编译类型下生效的
      debugIncludePaths:
      releaseIncludePaths:
      profileIncludePaths:

      # 链接库目录，依赖的模块会自动配置该链接路径
      libraryDirectories:
      # 仅特定编译类型下生效的
      debugLibraryDirectories:
      releaseLibraryDirectories:
      profileLibraryDirectories:

      # 运行时库路径，指定库的路径，依赖的模块会自动链接该库
      # 可配置相对于本文件路径的相对路径，也可以配置相对于${libraryDirectories}的路径
      # 如果在本路径和${libraryDirectories}均找不到该库文件，则认为该文件是系统库，编译时会在系统库中寻找
      runtimeLibraryPaths:
      # 仅特定编译类型下生效的
      debugRuntimeLibraryPaths:
      releaseRuntimeLibraryPaths:
      profileRuntimeLibraryPaths:

      # 静态库的路径
      compileLibraryPaths:
      debugCompileLibraryPaths:
      releaseCompileLibraryPaths:
      profileCompileLibraryPaths:

参考示例：

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
      # 依赖静态库路径
      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
      # 依赖静态库路径
      compileLibraryPaths:
        - fx_model.lib

全局变量参照表

配置外部库模块时的先决条件中可以使用的一些变量，例如：${FX_PLATFORM} STREQUAL ${FX_PLATFORM_ANDROID} 可表示当前编译平台是Android平台，${FX_ARCH} STREQUAL ${FX_ARCH_ARM64} 表示当前编译架构是 ARM 64 ，可根据这些变量组合出不同的先决条件。

变量	说明
FX_PLATFORM	当前编译平台
FX_PLATFORM_WINDOWS	WINDOWS平台
FX_PLATFORM_ANDROID	ANDROID平台
FX_PLATFORM_IOS	iOS平台
FX_PLATFORM_ORBIS	PS4平台
FX_PLATFORM_LINUX	LINUX平台
----	----
FX_ARCH	当前编译架构
FX_ARCH_x32	32位
FX_ARCH_x64	64位
FX_ARCH_ARM	ARM 32位
FX_ARCH_ARM64	ARM 64位
----	----
FX_TOOLSET	当前编译工具，可选值[FX_TOOLSET_V140, FX_TOOLSET_V141, FX_TOOLSET_V142, FX_TOOLSET_CLANG, FX_TOOLSET_GCC]

注意: 所有配置文件中的路径尽量用正斜杠 / , \的路径在编译非Windows平台时会存在问题。

VS Code智能提示

1. 使用VS Code打开工作区，并安装redhat.vscode-yaml插件。

   运行/path/to/engine/build/vscode/vscode_open.bat批处理打开工作区；或使用VS Code打开/path/to/engine/build/vscode/flexi.code-workspace文件。安装插件redhat.vscode-yaml。

2. 在工作区打开_build.yaml和_peojct.yaml。

   此时，VS Code将会识别到Fmake的字段属性配置，并给与提示。

增加全局提示：

可以对VS Code增加全局提示，操作步骤如下：

1. 使用Ctrl+Shift+P打开命令面板。
2. 输入Open User Settings (JSON)，打开用户全局设置文件。
3. 在设置文件中，加入yaml.schemas的设置，以key:value的形式增加Json Schema的映射，key填写Schema的绝对路径或网络路径URL，示例如下。

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

Q&A

Q1：日常如何更新SVN上的代码和开发？

A: 正常更新SVN代码和资源后，执行一次project\source\generate_sln.bat或generate_sln_vs2019.bat后再打开flexi.sln。

若发现编译失败的问题（提示缺少代码文件、link失败等），先执行 project\source\generate_sln.bat或generate_sln_vs2019.bat解决问题。

Q2：如果添加，删除，移动了代码文件，该怎么处理？

A: 重新运行生成解决方案的bat（windows_project\source\generate_sln.bat）即可。

Q3：如果某文件夹/代码文件只用于某平台，如何修改YAML？

A: 以fx_render模块为例，ps平台加入了一些目录和文件只用于ps平台如下图所示，只需要按照下图中的规范在对应平台的sourceIncludes下配置即可。

# 类型
kind: Module
# 模块名称
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
      # 源码排除目录
      sourceExcludes:
        - backends/vulkan/volk.c
        - backends/vulkan/volk.h

Q4：如果某文件夹/代码文件需要在某平台排除，如何修改YAML？

A: 以fx_render模块为例，安卓平台排除了一些目录和文件如下图所示，只需要按照下图中的规范在对应平台的sourceExcludes下配置即可。

# 类型
kind: Module
# 模块名称
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
      # 源码排除目录
      sourceExcludes:
        - backends/vulkan/volk.c
        - backends/vulkan/volk.h

Q5：如果某工程依赖其他模块，如何配置YAML？

A: 以fx_render模块为例，所有平台都依赖的模块可以配置在全局配置里。

# 类型
kind: Module
# 模块名称
name: fx_render
spec:
  # 编译静态库或者动态库
  targetType: SHARED
  # 源码额外包含目录
  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
  # 依赖模块
  depends:
    - fx_common_utils
    - dxsdk
    - xess
    - tbb
    - freetype
    - harfbuzz
  # 生成文档
  docs: true
  # 生成原始文本
  i18n: true
targets:
  # WINDOWS
  - platform: windows

如果是只有该平台才依赖的模块则在对应平台里配置，如下图只有安卓平台才依赖shaderc和log。

# 类型
kind: Module
# 模块名称
name: fx_render
spec:
  # 编译静态库或者动态库
  targetType: SHARED
  # ...
  # 依赖模块
  depends:
    - fx_common_utils
    - dxsdk
    - xess
    - tbb
    - freetype
    - harfbuzz
  # 生成文档
  docs: true
  # 生成原始文本
  i18n: true
targets:
  # WINDOWS
  - platform: windows
    spec:
      # ...
  # ANDROID
  - platform: android
    spec:
      # 源码排除目录
      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：如果某工程依赖第三方库的lib/dll，如何配置YAML？

A: 以freetype为例，debugRuntimeLibraryPaths和releaseRuntimeLibraryPaths是用来配置第三方库的dll的，debugCompileLibraryPaths和releaseCompileLibraryPaths是用来配置第三方的lib的。

kind: Extern
name: freetype
# 公共配置
spec:
  # 包含头文件路径
  includePaths:
    - include
rules:
  # windows 64位 MD
  - if: '${FX_PLATFORM} == ${FX_PLATFORM_WINDOWS} && ${FX_ARCH} == ${FX_ARCH_X64}'
    spec:
      # 包含头文件路径
      includePaths:
      # 运行时依赖动态库路径
      runtimeLibraryPaths:
      # 依赖静态库路径
      debugCompileLibraryPaths:
        - lib/freetype_vs2015_x64_md_d.lib
      releaseCompileLibraryPaths:
        - lib/freetype_vs2015_x64_md.lib

Q7：reflang命令行在Fmake配置文件中怎么配置？（引擎反射代码如何生成）

A: 以fx_render模块为例，在模块中配置codeGenEnable: true即可。

# 类型
kind: Module
# 模块名称
name: fx_render
spec:
  # 编译静态库或者动态库
  targetType: SHARED
  # 源码额外包含目录
  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
  # 开启反射检测
  codeGenEnable: true
  # 依赖模块
  depends:
    - fx_common_utils
    - dxsdk
    - xess
    - tbb
    - freetype
    - harfbuzz
  
  # 生成文档
  docs: true
  # 生成原始文本
  i18n: true