diff --git a/Flutter-Requirements.md b/Flutter-Requirements.md index cdfcf43b8..8074f8ac0 100644 --- a/Flutter-Requirements.md +++ b/Flutter-Requirements.md @@ -62,3 +62,13 @@ on all platforms. Symptoms of missing fonts can include text failing to display, console logging about failure to load fonts, or in some cases crashes. + +## Plugins + +If your project uses any plugins with platform components, they won't +work, as the native side will be missing. Depending on how the Dart side of the +plugin is written, they may fail gracefully, or may throw errors. + +You may need to make the calls to those plugins conditional based on the host +platform. Alternately, if you have the expertise, you could implement the native +side of the plugin in your desktop project(s). diff --git a/Quick-Start.md b/Quick-Start.md new file mode 100644 index 000000000..8c6c49a00 --- /dev/null +++ b/Quick-Start.md @@ -0,0 +1,48 @@ +# Quick Start + +A common question for people discovering this project is: How do I easily add +desktop support to my existing Flutter application? + +The answer is that at this point, you don't. The project is still in early +stages, and a lot of things are still in flux; if you don't already have +experience doing desktop development on the platform(s) you want to add, +this project is probably not ready for you to use it yet. The focus is currently +on improving core functionality, not on ease of use. Neither the API surface nor +the project structure are stable, and no attempt will be made to provide +supported migration paths as things change. + +However, if you want to try out an existing Flutter application running on the +desktop even with those caveats, and don't have experience with desktop +development, here are two approaches that might work for you. + +With either approach, be sure to follow the [main README](README.md) and +[library README](library/README.md) instructions on setting up prerequisites +and adjusting your Flutter application. + +## Replace the 'example' Flutter Code + +Since `example/` is already configured to run on all the platforms this project +supports, you can swap in your project's Dart code, `pubspec.yaml`, resources, +etc., then follow the [normal directions](example/README.md) for building the +example application on your platform. + +This will be the easiest approach to keep working as the project changes, but +requires that you essentially wrap your whole application in a +flutter-desktop-embedding checkout. + +## Copy the '\*\_fde' Directories + +Starting from the example projects means you don't have to create projects from +scratch, and since they are self-contained they can be added to an existing +project without needing to move it. However, because the projects build +the flutter-desktop-embedding libraries from source, they contain relative paths +to the flutter-desktop-embedding projects and tools they depend on. You will +need to update those paths in order for the projects to work. On Linux, the +variables you will need to change are documented in the Makefile. On macOS and +Windows, you will need some familiarity with Xcode and Visual Studio +respectively to make the changes. + +With this approach, you should expect breakage when you update the +flutter-desktop-embedding reposity; when that happens you will need to look at +what has changed in the exmaple projects and update your copies accordingly, or +start over with fresh copies and adjust the paths again. diff --git a/README.md b/README.md index 36fd1f8ec..d8bd010f5 100644 --- a/README.md +++ b/README.md @@ -11,6 +11,9 @@ optional plugins to access other native platform functionality. ## How to Use This Code +_If you have an existing Flutter app and just want to get it running, see +the [quick start](Quick-Start.md) page before continuing._ + ### Setting Up The tooling and build infrastructure for this project requires that you have