See also: Flutter's code of conduct
.../engine/src/third_party/android_tools/sdk/platform-tools
.brew install android-platform-tools
sudo apt-get install android-tools-adb
adb
(from the Android platform tools) is in your path (e.g., that which adb
prints sensible output).https://github.com/flutter/flutter
into your own GitHub account. If you already have a fork, and are now installing a development environment on a new machine, make sure you‘ve updated your fork so that you don’t use stale configuration options from long ago.git clone git@github.com:<your_name_here>/flutter.git
cd flutter
git remote add upstream git@github.com:flutter/flutter.git
(So that you fetch from the master repository, not your clone, when running git fetch
et al.)bin
directory to your path. That will let you use the flutter
command in this directory more easily.flutter update-packages
This will fetch all the Dart packages that Flutter depends on. You can replicate what this script does by running pub get
in each directory that contains a pubspec.yaml
file.flutter ide-config --overwrite
to create all of the IntelliJ configuration files so you can open the main flutter directory as a project and run examples from within the IDE.To run an example, switch to that example's directory, and use flutter run
. Make sure you have an emulator running, or a device connected over USB and debugging enabled on that device.
cd examples/hello_world
flutter run
You can also specify a particular Dart file to run if you want to run an example that doesn't have a lib/main.dart
file using the -t
command-line option. For example, to run the widgets/spinning_square.dart
example in the examples/layers directory on a connected Android device, from that directory you would run: flutter run -t widgets/spinning_square.dart
When running code from the examples directory, any changes you make to the example code, as well as any changes to Dart code in the packages/flutter directory and subdirectories, will automatically be picked when you relaunch the app. You can do the same for your own code by mimicking the pubspec.yaml
files in the examples
subdirectories.
When editing Flutter code, it's important to check the code with the analyzer. There are two main ways to run it. In either case you will want to run flutter update-packages
first, or you will get bogus error messages about core classes like Offset from dart:ui
.
For a one-off, use flutter analyze --flutter-repo
. This uses the analysis_options_repo.yaml
file at the root of the repository for its configuration.
For continuous analysis, use flutter analyze --flutter-repo --watch
. This uses normal analysis_options.yaml
files, and they can differ from package to package.
If you want to see how many members are missing dartdocs, you should use the first option, providing the additional command --dartdocs
.
If you omit the --flutter-repo
option you may end up in a confusing state because that will assume you want to check a single package and the flutter repository has several packages.
To automatically find all files named _test.dart
inside a package's test/
subdirectory, and run them inside the flutter shell as a test, use the flutter test
command, e.g:
cd examples/stocks
flutter test
Individual tests can also be run directly, e.g. flutter test lib/my_app_test.dart
Flutter tests use package:flutter_test which provides flutter-specific extensions on top of package:test.
flutter test
runs tests inside the flutter shell. To debug tests in Observatory, use the --start-paused
option to start the test in a paused state and wait for connection from a debugger. This option lets you set breakpoints before the test runs.
To run all the tests for the entire Flutter repository, the same way that Travis runs them, run dart dev/bots/test.dart
.
If you've built your own flutter engine, you can pass --local-engine
to change what flutter shell flutter test
uses. For example, if you built an engine in the out/host_debug_unopt
directory, you can pass --local-engine=host_debug_unopt
to run the tests in that engine.
Flutter tests are headless, you won't see any UI. You can use print
to generate console output or you can interact with the DartVM via observatory at http://localhost:8181/.
To add a test to the Flutter package, create a file whose name ends with _test.dart
in the packages/flutter/test
directory. The test should have a main
function and use the test
package.
The flutter tool itself is built when you run flutter
for the first time and each time you run flutter upgrade
. If you want to alter and re-test the tool's behavior itself, locally commit your tool changes in git and the tool will be rebuilt from Dart sources in packages/flutter_tools
the next time you run flutter
.
Alternatively, delete the bin/cache/flutter_tools.snapshot
file. Doing so will force a rebuild of the tool from your local sources the next time you run flutter
.
flutter_tools' tests run inside the Dart command line VM rather than in the flutter shell. To run the tests, ensure that no devices are connected, then navigate to flutter_tools
and execute:
../../bin/cache/dart-sdk/bin/pub run test -j1
The pre-built flutter tool runs in release mode with the observatory off by default. To enable debugging mode and the observatory on the flutter
tool, uncomment the FLUTTER_TOOL_ARGS
line in the bin/flutter
shell script.
We gladly accept contributions via GitHub pull requests.
Please peruse our style guides and design principles before working on anything non-trivial. These guidelines are intended to keep the code consistent and avoid common pitfalls.
To start working on a patch:
git fetch upstream
git checkout upstream/master -b name_of_your_branch
git commit -a -m "<your informative commit message>"
git push origin name_of_your_branch
To send us a pull request:
git pull-request
(if you are using Hub) or go to https://github.com/flutter/flutter
and click the “Compare & pull request” buttonPlease make sure all your checkins have detailed commit messages explaining the patch.
Once you've gotten an LGTM from a project maintainer and once your PR has received the green light from all our automated testing (Travis, Appveyor, etc), and once the tree is green (see the design principles document for more details), submit your changes to the master
branch using one of the following methods:
You must complete the Contributor License Agreement. You can do this online, and it only takes a minute. If you‘ve never submitted code before, you must add your (or your organization’s) name and contact info to the AUTHORS file.
We grant commit access to people who have gained our trust and demonstrated a commitment to Flutter.
We strive for a high degree of test coverage for the Flutter framework. We use Coveralls to track our test coverage. You can download our current coverage data from cloud storage and visualize it in Atom as follows:
packages/flutter
folder in Atom.lib
directory an type Ctrl+Alt+C
to bring up the coverage data.If you don't see any coverage data, check that you have an lcov.info
file in the packages/flutter/coverage
directory. It should have been downloaded by the flutter update-packages
command you ran previously.
If you want to iterate quickly on improving test coverage, consider using this workflow:
flutter test --merge-coverage path/to/your/test_test.dart
.This workflow merges the coverage data from this test run with the base coverage data downloaded by flutter update-packages
.
See issue 4719 for ideas about how to improve this workflow.
You can work both with this repository (flutter.git) and the Flutter engine repository at the same time using the following steps.
Follow the instructions above for creating a working copy of this repository.
Follow the contributing instructions for the engine repository to create a working copy of the engine. When you create the .gclient
file for the engine, be sure to create it in a directory named engine
that is a sibling of the directory in which you cloned this repository. For example, if you cloned this repository into the /foo/bar/flutter
directory, you should create the .gclient
file in the /foo/bar/engine
directory. The actual code from the engine repository will end up in /foo/bar/engine/src
because gclient
creates a src
directory underneath the directory that contains the .gclient
file.
To run tests on your host machine, build one of the host configurations (e.g., out/host_debug_unopt
). To run examples on Android, build one of the Android configurations (e.g., out/android_debug_unopt
). When running on the device with --preview-dart-2
flag you will still need to build corresponding host configuration (e.g., out/host_debug_unopt
if you are using out/android_debug_unopt
, out/host_release
if you use out/android_release
). Host configuration provides standalone dart sdk for the engine, that is used to run engine dart scripts on the host.
You should now be able to run the tests against your locally built engine using the flutter test --local-engine=host_debug_unopt
command. To run one of the examples on your device using your locally built engine, use the --local-engine=android_debug_unopt
option to the flutter
tool:
flutter run --local-engine=android_debug_unopt
If you make a breaking change to the engine, you'll need to land your change in a few steps:
Land your change in the engine repository.
Publish a new version of the engine that contains your change. See the engine's release process for instructions about how to publish a new version of the engine. Publishing a new version is important in order to not break folks using prebuilt binaries in their workflow (e.g., our customers).
Land a change that update our dependency on the sky_engine
and sky_services
packages to point to the new version of the engine that you just published. These dependencies are defined by packages/flutter/pubspec.yaml. After changing the pubspec.yaml
file, you'll need to run ./dev/update_packages.dart
to update all the packages in this repository to see the new dependency. As part of landing this change, you should make whatever other changes are needed in this repository to account for your breaking change.
To view the API docs for the master
branch, visit https://master-docs-flutter-io.firebaseapp.com/.
Those docs should be updated after a successful CI build of Flutter's master
branch.
(Looking for the API docs for our releases? Please visit https://docs.flutter.io.)
We build and test Flutter on: