website

website copied to clipboard

Page URL

https://docs.flutter.dev/development/platform-integration/windows/version-migration/

Page source

https://github.com/flutter/website/tree/main/src/development/platform-integration/windows/version-migration.md

Describe the problem

Step 4 of the migration instructions only describe to delete 2 files inside the windows folder (Delete the windows/runner/CMakeLists.txt and windows/runner/Runner.rc files), though this results in a build error afterwards.

Expected fix

Step 4 should be changed to deleting the whole windows folder, which will resolve the linker error described here: https://github.com/flutter/flutter/issues/110660#issuecomment-1232825018

Additional context

No response

Aug 31 '22 11:08 enwi

I feel like asking people to delete their entire windows folder might be a bit too much (and could potentially be dangerous).

I imagine the migration guide specified deleting those two files for a reason so if deleting those two files creates an issue afterward, it should likely be fixed.

@enwi, kindly reopen your issue on the main flutter repo so that it can be looked at.

In the interim, I'll be leaving this issue open until we can get a team member to look at the issue on the main flutter repo

Aug 31 '22 12:08 danagbemava-nc

@danagbemava-nc it might be too harsh to just delete the whole folder, but after letting flutter regenerate all the files I can see that it only changed the following windows/CMakeLists.txt, windows/flutter/CMakeLists.txt, windows/runner/CMakeLists.txt, windows/runner/flutter_window.cpp, windows/runner/flutter_window.h, windows/runner/main.cpp, windows/runner/runner.exe.manifest, windows/runner/Runner.rc and windows/runner/utils.cpp. The files windows/runner/run_loop.cpp and windows/runner/run_loop.h were deleted.

So maybe just deleting those might be an option?

Aug 31 '22 13:08 enwi

I think what you encountered was a bug that we need to investigate. I create a project with stable 3.0.5 before upgrading to stable 3.3.0 and deleted the files specified in the migration guide. After which I run flutter create --platform=windows . and flutter build windows and I didn't get any linker issues

Aug 31 '22 13:08 danagbemava-nc

I think I upgraded from 3.0.4 to 3.3.0, so that might be the clue

Aug 31 '22 13:08 enwi

@cbracken, can you comment?

Sep 15 '22 00:09 sfshaza2

I don't think anything changed in this regard in between 3.0.4 and 3.3.0. run_loop.cpp was removed in https://github.com/flutter/flutter/pull/79969 on 2021-04-27.

There's an open issue for auto-migration of very old projects here https://github.com/flutter/flutter/issues/80057, though at this point I suspect we should close it and simply rely on documentation (this change was landed prior to desktop stable).

While we could update the instructions to cover the exact files, I think we should probably go with the simplest solution which is to delete the entire windows subdirectory. If we wanted to go a little more specific, perhaps just the windows/runner directory?

@enwi what caused you to need to delete windows/CMakeLists.txt and windows/flutter/CMakeLists.txt?

Sep 15 '22 23:09 cbracken

@cbracken Diff of windows/CMakeLists.txt:

diff --git a/windows/CMakeLists.txt b/windows/CMakeLists.txt
index 47d780a..4d3c984 100644
--- a/windows/CMakeLists.txt
+++ b/windows/CMakeLists.txt
@@ -1,13 +1,16 @@
-cmake_minimum_required(VERSION 3.15)
+# Project-level configuration.
+cmake_minimum_required(VERSION 3.14)
 project(helios_gui 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 "helios_gui")
 
+# 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 @@ else()
       "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 @@ set(CMAKE_CXX_FLAGS_PROFILE "${CMAKE_CXX_FLAGS_RELEASE}")
 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 @@ function(APPLY_STANDARD_SETTINGS TARGET)
   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 of windows/flutter/CMakeLists.txt:

diff --git a/windows/flutter/CMakeLists.txt b/windows/flutter/CMakeLists.txt
index 744f08a..930d207 100644
--- a/windows/flutter/CMakeLists.txt
+++ b/windows/flutter/CMakeLists.txt
@@ -1,4 +1,5 @@
-cmake_minimum_required(VERSION 3.15)
+# 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")
 
@@ -23,6 +24,7 @@ list(APPEND FLUTTER_LIBRARY_HEADERS
   "flutter_windows.h"
   "flutter_messenger.h"
   "flutter_plugin_registrar.h"
+  "flutter_texture_registrar.h"
 )
 list(TRANSFORM FLUTTER_LIBRARY_HEADERS PREPEND "${EPHEMERAL_DIR}/")
 add_library(flutter INTERFACE)

Sep 16 '22 10:09 enwi

The CMakefile.txt diffs are unrelated to the version information change.

They may be useful nonetheless (e.g. CMake minimum version allows for more versions of Visual Studio, addition of flutter_texture_registrar.h is useful for anyone who wants to register an external texture), and removing and recreating the entire windows directory is probably the simplest solution in terms of the instructions.

One reason we try to list the minimum set of files possible is that once created, these files belong to the user, and they may have edited them with custom functionality. That's likely to be the minority scenario though. Perhaps we should suggest deleting and recreating the directory but to note that any custom changes made to the launcher will need to be reapplied.

/cc @loic-sharma for thoughts.

Sep 20 '22 01:09 cbracken

This problem affects folks that created their Windows project using Flutter 2.2.3 or earlier. Flutter 2.2.3 was the last version whose template contained the run loop; the next stable release, 2.5.0, removed this run loop. I can write a migration guide for folks that are still on these old Windows project templates. Does that seem reasonable @cbracken?

In the future, folks will be able to use the upcoming flutter migrate command to keep their projects up-to-date and avoid these kinds of issues.

flutter_window.obj : error LNK2019: unresolved external symbol "public: void __cdecl RunLoop::RegisterFlutterInstance(class flutter::FlutterEngine *)" (?RegisterFlutterInstance@RunLoop@@QEAAXPEAVFlutterEngine@flutter@@@Z) referenced in function "protected: virtual bool __cdecl FlutterWindow::OnCreate(void)" (?OnCreate@FlutterWindow@@MEAA_NXZ) [C:\Code\f\tests\x2\build\windows\runner\x2.vcxproj]
flutter_window.obj : error LNK2019: unresolved external symbol "public: void __cdecl RunLoop::UnregisterFlutterInstance(class flutter::FlutterEngine *)" (?UnregisterFlutterInstance@RunLoop@@QEAAXPEAVFlutterEngine@flutter@@@Z) referenced in function "protected: virtual void __cdecl FlutterWindow::OnDestroy(void)" (?OnDestroy@FlutterWindow@@MEAAXXZ) [C:\Code\f\tests\x2\build\windows\runner\x2.vcxproj]
main.obj : error LNK2019: unresolved external symbol "public: __cdecl RunLoop::RunLoop(void)" (??0RunLoop@@QEAA@XZ) referenced in function wWinMain [C:\Code\f\tests\x2\build\windows\runner\x2.vcxproj]
main.obj : error LNK2019: unresolved external symbol "public: __cdecl RunLoop::~RunLoop(void)" (??1RunLoop@@QEAA@XZ) referenced in function wWinMain [C:\Code\f\tests\x2\build\windows\runner\x2.vcxproj]
main.obj : error LNK2019: unresolved external symbol "public: void __cdecl RunLoop::Run(void)" (?Run@RunLoop@@QEAAXXZ) referenced in function wWinMain [C:\Code\f\tests\x2\build\windows\runner\x2.vcxproj]
C:\Code\f\tests\x2\build\windows\runner\Debug\x2.exe : fatal error LNK1120: 5 unresolved externals [C:\Code\f\tests\x2\build\windows\runner\x2.vcxproj]

Sep 20 '22 19:09 loic-sharma

Makes sense - I think it's probably reasonable to add a bit of detail for people on older versions of Flutter. Long-term the real solution for this sort of thing is going to be flutter migrate.

Sep 20 '22 20:09 cbracken

Hello we improved this documentation with: https://github.com/flutter/website/pull/7570

To summarize, folks affected by this should follow this guide: https://docs.flutter.dev/development/platform-integration/windows/run-loop-migration

Please let us know if you run into additional problems or have follow-up questions!

Oct 13 '22 15:10 loic-sharma