Skip to content

Address the 'How do I just use it' FAQ #246

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Jan 22, 2019
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 10 additions & 0 deletions Flutter-Requirements.md
Original file line number Diff line number Diff line change
Expand Up @@ -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).
48 changes: 48 additions & 0 deletions Quick-Start.md
Original file line number Diff line number Diff line change
@@ -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.
3 changes: 3 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down