Document template CMake files (#96534)
diff --git a/packages/flutter_tools/templates/app_shared/linux.tmpl/CMakeLists.txt.tmpl b/packages/flutter_tools/templates/app_shared/linux.tmpl/CMakeLists.txt.tmpl
index 23a19a4..ef572e5 100644
--- a/packages/flutter_tools/templates/app_shared/linux.tmpl/CMakeLists.txt.tmpl
+++ b/packages/flutter_tools/templates/app_shared/linux.tmpl/CMakeLists.txt.tmpl
@@ -1,11 +1,19 @@
+# Project-level configuration.
cmake_minimum_required(VERSION 3.10)
project(runner LANGUAGES CXX)
+# The name of the executable created for the application. Change this to change
+# the on-disk name of your application.
set(BINARY_NAME "{{projectName}}")
+# The unique GTK application identifier for this application. See:
+# https://wiki.gnome.org/HowDoI/ChooseApplicationID
set(APPLICATION_ID "{{linuxIdentifier}}")
+# Explicitly opt in to modern CMake behaviors to avoid warnings with recent
+# versions of CMake.
cmake_policy(SET CMP0063 NEW)
+# Load bundled libraries from the lib/ directory relative to the binary.
set(CMAKE_INSTALL_RPATH "$ORIGIN/lib")
# Root filesystem for cross-building.
@@ -18,7 +26,7 @@
set(CMAKE_FIND_ROOT_PATH_MODE_INCLUDE ONLY)
endif()
-# Configure build options.
+# Define build configuration options.
if(NOT CMAKE_BUILD_TYPE AND NOT CMAKE_CONFIGURATION_TYPES)
set(CMAKE_BUILD_TYPE "Debug" CACHE
STRING "Flutter build mode" FORCE)
@@ -27,6 +35,10 @@
endif()
# Compilation settings that should be applied to most targets.
+#
+# Be cautious about adding new options here, as plugins use this function by
+# default. In most cases, you should add new options to specific targets instead
+# of modifying this function.
function(APPLY_STANDARD_SETTINGS TARGET)
target_compile_features(${TARGET} PUBLIC cxx_std_14)
target_compile_options(${TARGET} PRIVATE -Wall -Werror)
@@ -34,9 +46,8 @@
target_compile_definitions(${TARGET} PRIVATE "$<$<NOT:$<CONFIG:Debug>>:NDEBUG>")
endfunction()
-set(FLUTTER_MANAGED_DIR "${CMAKE_CURRENT_SOURCE_DIR}/flutter")
-
# Flutter library and tool build rules.
+set(FLUTTER_MANAGED_DIR "${CMAKE_CURRENT_SOURCE_DIR}/flutter")
add_subdirectory(${FLUTTER_MANAGED_DIR})
# System-level dependencies.
@@ -45,16 +56,27 @@
add_definitions(-DAPPLICATION_ID="${APPLICATION_ID}")
-# Application build
+# Define the application target. To change its name, change BINARY_NAME above,
+# not the value here, or `flutter run` will no longer work.
+#
+# Any new source files that you add to the application should be added here.
add_executable(${BINARY_NAME}
"main.cc"
"my_application.cc"
"${FLUTTER_MANAGED_DIR}/generated_plugin_registrant.cc"
)
+
+# Apply the standard set of build settings. This can be removed for applications
+# that need different build settings.
apply_standard_settings(${BINARY_NAME})
+
+# Add dependency libraries. Add any application-specific dependencies here.
target_link_libraries(${BINARY_NAME} PRIVATE flutter)
target_link_libraries(${BINARY_NAME} PRIVATE PkgConfig::GTK)
+
+# Run the Flutter tool portions of the build. This must not be removed.
add_dependencies(${BINARY_NAME} flutter_assemble)
+
# Only the install-generated bundle's copy of the executable will launch
# correctly, since the resources must in the right relative locations. To avoid
# people trying to run the unbundled copy, put it in a subdirectory instead of
diff --git a/packages/flutter_tools/templates/app_shared/linux.tmpl/flutter/CMakeLists.txt b/packages/flutter_tools/templates/app_shared/linux.tmpl/flutter/CMakeLists.txt
index 33fd580..d5bd016 100644
--- a/packages/flutter_tools/templates/app_shared/linux.tmpl/flutter/CMakeLists.txt
+++ b/packages/flutter_tools/templates/app_shared/linux.tmpl/flutter/CMakeLists.txt
@@ -1,3 +1,4 @@
+# This file controls Flutter-level build steps. It should not be edited.
cmake_minimum_required(VERSION 3.10)
set(EPHEMERAL_DIR "${CMAKE_CURRENT_SOURCE_DIR}/ephemeral")
diff --git a/packages/flutter_tools/templates/app_shared/windows.tmpl/CMakeLists.txt.tmpl b/packages/flutter_tools/templates/app_shared/windows.tmpl/CMakeLists.txt.tmpl
index d969f43..eeb9078 100644
--- a/packages/flutter_tools/templates/app_shared/windows.tmpl/CMakeLists.txt.tmpl
+++ b/packages/flutter_tools/templates/app_shared/windows.tmpl/CMakeLists.txt.tmpl
@@ -1,13 +1,16 @@
+# Project-level configuration.
cmake_minimum_required(VERSION 3.14)
project({{projectName}} LANGUAGES CXX)
+# The name of the executable created for the application. Change this to change
+# the on-disk name of your application.
set(BINARY_NAME "{{projectName}}")
+# Explicitly opt in to modern CMake behaviors to avoid warnings with recent
+# versions of CMake.
cmake_policy(SET CMP0063 NEW)
-set(CMAKE_INSTALL_RPATH "$ORIGIN/lib")
-
-# Configure build options.
+# Define build configuration option.
get_property(IS_MULTICONFIG GLOBAL PROPERTY GENERATOR_IS_MULTI_CONFIG)
if(IS_MULTICONFIG)
set(CMAKE_CONFIGURATION_TYPES "Debug;Profile;Release"
@@ -20,7 +23,7 @@
"Debug" "Profile" "Release")
endif()
endif()
-
+# Define settings for the Profile build mode.
set(CMAKE_EXE_LINKER_FLAGS_PROFILE "${CMAKE_EXE_LINKER_FLAGS_RELEASE}")
set(CMAKE_SHARED_LINKER_FLAGS_PROFILE "${CMAKE_SHARED_LINKER_FLAGS_RELEASE}")
set(CMAKE_C_FLAGS_PROFILE "${CMAKE_C_FLAGS_RELEASE}")
@@ -30,6 +33,10 @@
add_definitions(-DUNICODE -D_UNICODE)
# Compilation settings that should be applied to most targets.
+#
+# Be cautious about adding new options here, as plugins use this function by
+# default. In most cases, you should add new options to specific targets instead
+# of modifying this function.
function(APPLY_STANDARD_SETTINGS TARGET)
target_compile_features(${TARGET} PUBLIC cxx_std_17)
target_compile_options(${TARGET} PRIVATE /W4 /WX /wd"4100")
@@ -38,12 +45,11 @@
target_compile_definitions(${TARGET} PRIVATE "$<$<CONFIG:Debug>:_DEBUG>")
endfunction()
-set(FLUTTER_MANAGED_DIR "${CMAKE_CURRENT_SOURCE_DIR}/flutter")
-
# Flutter library and tool build rules.
+set(FLUTTER_MANAGED_DIR "${CMAKE_CURRENT_SOURCE_DIR}/flutter")
add_subdirectory(${FLUTTER_MANAGED_DIR})
-# Application build
+# Application build; see runner/CMakeLists.txt.
add_subdirectory("runner")
# Generated plugin build rules, which manage building the plugins and adding
diff --git a/packages/flutter_tools/templates/app_shared/windows.tmpl/flutter/CMakeLists.txt b/packages/flutter_tools/templates/app_shared/windows.tmpl/flutter/CMakeLists.txt
index b2e4bd8..930d207 100644
--- a/packages/flutter_tools/templates/app_shared/windows.tmpl/flutter/CMakeLists.txt
+++ b/packages/flutter_tools/templates/app_shared/windows.tmpl/flutter/CMakeLists.txt
@@ -1,3 +1,4 @@
+# This file controls Flutter-level build steps. It should not be edited.
cmake_minimum_required(VERSION 3.14)
set(EPHEMERAL_DIR "${CMAKE_CURRENT_SOURCE_DIR}/ephemeral")
diff --git a/packages/flutter_tools/templates/app_shared/windows.tmpl/runner/CMakeLists.txt b/packages/flutter_tools/templates/app_shared/windows.tmpl/runner/CMakeLists.txt
index de2d891..b9e550f 100644
--- a/packages/flutter_tools/templates/app_shared/windows.tmpl/runner/CMakeLists.txt
+++ b/packages/flutter_tools/templates/app_shared/windows.tmpl/runner/CMakeLists.txt
@@ -1,6 +1,11 @@
cmake_minimum_required(VERSION 3.14)
project(runner LANGUAGES CXX)
+# Define the application target. To change its name, change BINARY_NAME in the
+# top-level CMakeLists.txt, not the value here, or `flutter run` will no longer
+# work.
+#
+# Any new source files that you add to the application should be added here.
add_executable(${BINARY_NAME} WIN32
"flutter_window.cpp"
"main.cpp"
@@ -10,8 +15,18 @@
"Runner.rc"
"runner.exe.manifest"
)
+
+# Apply the standard set of build settings. This can be removed for applications
+# that need different build settings.
apply_standard_settings(${BINARY_NAME})
+
+# Disable Windows macros that collide with C++ standard library functions.
target_compile_definitions(${BINARY_NAME} PRIVATE "NOMINMAX")
+
+# Add dependency libraries and include directories. Add any application-specific
+# dependencies here.
target_link_libraries(${BINARY_NAME} PRIVATE flutter flutter_wrapper_app)
target_include_directories(${BINARY_NAME} PRIVATE "${CMAKE_SOURCE_DIR}")
+
+# Run the Flutter tool portions of the build. This must not be removed.
add_dependencies(${BINARY_NAME} flutter_assemble)
diff --git a/packages/flutter_tools/templates/app_shared/winuwp.tmpl/CMakeLists.txt.tmpl b/packages/flutter_tools/templates/app_shared/winuwp.tmpl/CMakeLists.txt.tmpl
index fe718ef..9827cf9 100644
--- a/packages/flutter_tools/templates/app_shared/winuwp.tmpl/CMakeLists.txt.tmpl
+++ b/packages/flutter_tools/templates/app_shared/winuwp.tmpl/CMakeLists.txt.tmpl
@@ -1,16 +1,20 @@
+# Project-level configuration.
cmake_minimum_required(VERSION 3.8)
set(CMAKE_SYSTEM_NAME WindowsStore)
set(CMAKE_SYSTEM_VERSION 10.0)
set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED YES)
-
project({{projectName}} LANGUAGES CXX)
+# Explicitly opt in to modern CMake behaviors to avoid warnings with recent
+# versions of CMake.
cmake_policy(SET CMP0079 NEW)
+# The name of the executable created for the application. Change this to change
+# the on-disk name of your application.
set(BINARY_NAME "{{projectName}}")
-# Configure build options.
+# Define build configuration options.
get_property(IS_MULTICONFIG GLOBAL PROPERTY GENERATOR_IS_MULTI_CONFIG)
if(IS_MULTICONFIG)
set(CMAKE_CONFIGURATION_TYPES "Debug;Profile;Release"
@@ -23,7 +27,7 @@
"Debug" "Profile" "Release")
endif()
endif()
-
+# Define settings for the Profile build mode.
set(CMAKE_EXE_LINKER_FLAGS_PROFILE "${CMAKE_EXE_LINKER_FLAGS_RELEASE}")
set(CMAKE_SHARED_LINKER_FLAGS_PROFILE "${CMAKE_SHARED_LINKER_FLAGS_RELEASE}")
set(CMAKE_C_FLAGS_PROFILE "${CMAKE_C_FLAGS_RELEASE}")
@@ -33,6 +37,10 @@
add_definitions(-DUNICODE -D_UNICODE)
# Compilation settings that should be applied to most targets.
+#
+# Be cautious about adding new options here, as plugins use this function by
+# default. In most cases, you should add new options to specific targets instead
+# of modifying this function.
function(APPLY_STANDARD_SETTINGS TARGET)
target_compile_features(${TARGET} PUBLIC cxx_std_17)
target_compile_options(${TARGET} PRIVATE /W4 /WX /wd"4100" /await)
@@ -48,10 +56,9 @@
# Flutter library and tool build rules.
add_subdirectory(${FLUTTER_MANAGED_DIR})
-# Application build
+# Application build; see runner/CMakeLists.txt.
add_subdirectory("runner_uwp")
-
# Generated plugin build rules, which manage building the plugins and adding
# them to the application.
include(flutter/generated_plugins.cmake)
diff --git a/packages/flutter_tools/templates/app_shared/winuwp.tmpl/flutter/CMakeLists.txt b/packages/flutter_tools/templates/app_shared/winuwp.tmpl/flutter/CMakeLists.txt
index ddf4525..9adbd9d 100644
--- a/packages/flutter_tools/templates/app_shared/winuwp.tmpl/flutter/CMakeLists.txt
+++ b/packages/flutter_tools/templates/app_shared/winuwp.tmpl/flutter/CMakeLists.txt
@@ -1,3 +1,4 @@
+# This file controls Flutter-level build steps. It should not be edited.
cmake_minimum_required(VERSION 3.8)
set(CMAKE_SYSTEM_NAME WindowsStore)
set(CMAKE_SYSTEM_VERSION 10.0)
diff --git a/packages/flutter_tools/templates/app_shared/winuwp.tmpl/runner_uwp/CMakeLists.txt.tmpl b/packages/flutter_tools/templates/app_shared/winuwp.tmpl/runner_uwp/CMakeLists.txt.tmpl
index 4ac70c5..8dccdc4 100644
--- a/packages/flutter_tools/templates/app_shared/winuwp.tmpl/runner_uwp/CMakeLists.txt.tmpl
+++ b/packages/flutter_tools/templates/app_shared/winuwp.tmpl/runner_uwp/CMakeLists.txt.tmpl
@@ -112,6 +112,11 @@
set_property(SOURCE ${ITEM} PROPERTY VS_DEPLOYMENT_LOCATION ${RELPATH})
endforeach()
+# Define the application target. To change its name, change BINARY_NAME in the
+# top-level CMakeLists.txt, not the value here, or `flutter run` will no longer
+# work.
+#
+# Any new source files that you add to the application should be added here.
add_executable (${BINARY_NAME} WIN32
main.cpp
flutter_frameworkview.cpp
@@ -119,9 +124,18 @@
${RESOURCE_FILES}
${INSTALL_MANIFEST_CONTENT}
)
+
+# Apply the standard set of build settings. This can be removed for applications
+# that need different build settings.
apply_standard_settings(${BINARY_NAME})
+
+# Disable Windows macros that collide with C++ standard library functions.
target_compile_definitions(${BINARY_NAME} PRIVATE "NOMINMAX")
+
+# Add dependency libraries and include directories. Add any application-specific
+# dependencies here.
target_link_libraries(${BINARY_NAME} PRIVATE WindowsApp flutter flutter_wrapper_app)
target_include_directories(${BINARY_NAME} PRIVATE "${CMAKE_SOURCE_DIR}")
+# Run the Flutter tool portions of the build. This must not be removed.
add_dependencies(${BINARY_NAME} flutter_assemble)
diff --git a/packages/flutter_tools/templates/plugin/linux.tmpl/CMakeLists.txt.tmpl b/packages/flutter_tools/templates/plugin/linux.tmpl/CMakeLists.txt.tmpl
index 8df4546..40a885d 100644
--- a/packages/flutter_tools/templates/plugin/linux.tmpl/CMakeLists.txt.tmpl
+++ b/packages/flutter_tools/templates/plugin/linux.tmpl/CMakeLists.txt.tmpl
@@ -1,24 +1,46 @@
+# The Flutter tooling requires that developers have CMake 3.10 or later
+# installed. You should not increase this version, as doing so will cause
+# the plugin to fail to compile for some customers of the plugin.
cmake_minimum_required(VERSION 3.10)
+
+# Project-level configuration.
set(PROJECT_NAME "{{projectName}}")
project(${PROJECT_NAME} LANGUAGES CXX)
# This value is used when generating builds using this plugin, so it must
-# not be changed
+# not be changed.
set(PLUGIN_NAME "{{projectName}}_plugin")
+# Define the plugin library target. Its name must not be changed (see comment
+# on PLUGIN_NAME above).
+#
+# Any new source files that you add to the plugin should be added here.
add_library(${PLUGIN_NAME} SHARED
"{{pluginClassSnakeCase}}.cc"
)
+
+# Apply a standard set of build settings that are configured in the
+# application-level CMakeLists.txt. This can be removed for plugins that want
+# full control over build settings.
apply_standard_settings(${PLUGIN_NAME})
+
+# Symbols are hidden by default to reduce the chance of accidental conflicts
+# between plugins. This should not be removed; any symbols that should be
+# exported should be explicitly exported with the FLUTTER_PLUGIN_EXPORT macro.
set_target_properties(${PLUGIN_NAME} PROPERTIES
CXX_VISIBILITY_PRESET hidden)
target_compile_definitions(${PLUGIN_NAME} PRIVATE FLUTTER_PLUGIN_IMPL)
+
+# Source include directories and library dependencies. Add any plugin-specific
+# dependencies here.
target_include_directories(${PLUGIN_NAME} INTERFACE
"${CMAKE_CURRENT_SOURCE_DIR}/include")
target_link_libraries(${PLUGIN_NAME} PRIVATE flutter)
target_link_libraries(${PLUGIN_NAME} PRIVATE PkgConfig::GTK)
-# List of absolute paths to libraries that should be bundled with the plugin
+# List of absolute paths to libraries that should be bundled with the plugin.
+# This list could contain prebuilt libraries, or libraries created by an
+# external build triggered from this build file.
set({{projectName}}_bundled_libraries
""
PARENT_SCOPE
diff --git a/packages/flutter_tools/templates/plugin/windows.tmpl/CMakeLists.txt.tmpl b/packages/flutter_tools/templates/plugin/windows.tmpl/CMakeLists.txt.tmpl
index 5d7b0ef..3b05d1f 100644
--- a/packages/flutter_tools/templates/plugin/windows.tmpl/CMakeLists.txt.tmpl
+++ b/packages/flutter_tools/templates/plugin/windows.tmpl/CMakeLists.txt.tmpl
@@ -1,4 +1,10 @@
+# The Flutter tooling requires that developers have a version of Visual Studio
+# installed that includes CMake 3.14 or later. You should not increase this
+# version, as doing so will cause the plugin to fail to compile for some
+# customers of the plugin.
cmake_minimum_required(VERSION 3.14)
+
+# Project-level configuration.
set(PROJECT_NAME "{{projectName}}")
project(${PROJECT_NAME} LANGUAGES CXX)
@@ -6,18 +12,35 @@
# not be changed
set(PLUGIN_NAME "{{projectName}}_plugin")
+# Define the plugin library target. Its name must not be changed (see comment
+# on PLUGIN_NAME above).
+#
+# Any new source files that you add to the plugin should be added here.
add_library(${PLUGIN_NAME} SHARED
"{{pluginClassSnakeCase}}.cpp"
)
+
+# Apply a standard set of build settings that are configured in the
+# application-level CMakeLists.txt. This can be removed for plugins that want
+# full control over build settings.
apply_standard_settings(${PLUGIN_NAME})
+
+# Symbols are hidden by default to reduce the chance of accidental conflicts
+# between plugins. This should not be removed; any symbols that should be
+# exported should be explicitly exported with the FLUTTER_PLUGIN_EXPORT macro.
set_target_properties(${PLUGIN_NAME} PROPERTIES
CXX_VISIBILITY_PRESET hidden)
target_compile_definitions(${PLUGIN_NAME} PRIVATE FLUTTER_PLUGIN_IMPL)
+
+# Source include directories and library dependencies. Add any plugin-specific
+# dependencies here.
target_include_directories(${PLUGIN_NAME} INTERFACE
"${CMAKE_CURRENT_SOURCE_DIR}/include")
target_link_libraries(${PLUGIN_NAME} PRIVATE flutter flutter_wrapper_plugin)
-# List of absolute paths to libraries that should be bundled with the plugin
+# List of absolute paths to libraries that should be bundled with the plugin.
+# This list could contain prebuilt libraries, or libraries created by an
+# external build triggered from this build file.
set({{projectName}}_bundled_libraries
""
PARENT_SCOPE
