Setting up Flutter

Orblit is a set of Flutter packages, so Flutter comes first. If flutter --version already says 3.47.0 or newer on the stable channel, and flutter doctor has a tick against the platform you want to build for, skip to Installing. This page is for everything before that.

Which Flutter

3.47.0 or newer, on the stable channel. The Dart SDK comes inside Flutter, so there’s nothing else to install: 3.47.0 carries Dart 3.13.0.

On anything older, flutter pub get stops before anything builds:

The current Flutter SDK version is 3.46.0.

Because my_app depends on orblit_filament from git which requires Flutter SDK version >=3.47.0, version solving failed.

If you already have an older Flutter, flutter upgrade moves it to the newest stable. If flutter --version names a channel other than stable, run flutter channel stable first.

The engine is developed against 3.47.0. CI builds it with whatever stable is current, so a newer stable that breaks something should show up there first.

Getting the SDK

Flutter’s own instructions have you download an archive and unpack it. This page clones it with Git instead. Both give you a working Flutter, but the clone is one command that’s the same on every machine, you need Git for Orblit anyway, and it’s how Flutter got onto the machines Orblit is built on, the Linux container included.

Wherever it goes, pick a path with no spaces in it that you can write to without admin rights. That’s Flutter’s advice too, and its docs suggest ~/develop.

The clone comes to about 680 MB, 490 MB of which is Git history. The first flutter command then downloads the Dart SDK, and each platform’s build tools arrive the first time you build for it. Linux’s came to 225 MB. The Flutter this page was written with, holding the tools for every platform, takes 4.9 GB.

On a Mac

xcode-select --install
git clone https://github.com/flutter/flutter.git -b stable ~/develop/flutter
echo 'export PATH="$HOME/develop/flutter/bin:$PATH"' >> ~/.zprofile

The first line installs Apple’s command line tools, which is where a Mac gets Git. Skip it if git --version already works. zsh is the Mac’s shell, and ~/.zprofile is what it reads when Terminal opens a window, so open a new one before going on.

Flutter still runs on an Intel Mac, though it’s deprecating support for them, and Orblit’s renderer doesn’t run on one.

On Linux

sudo apt-get install -y curl git unzip xz-utils zip libglu1-mesa
git clone https://github.com/flutter/flutter.git -b stable ~/develop/flutter
echo 'export PATH="$HOME/develop/flutter/bin:$PATH"' >> ~/.bashrc

The packages are Flutter’s own list, for Debian and Ubuntu. ~/.bashrc is for bash. If echo $SHELL says zsh, the line goes in ~/.zshenv instead, and fish takes fish_add_path -g -p ~/develop/flutter/bin. Open a new terminal before going on.

On Windows

Install Git for Windows first. Then, in PowerShell:

git clone https://github.com/flutter/flutter.git -b stable C:\src\flutter

Then put C:\src\flutter\bin on your Path. Search the Start menu for “environment variables”, open “Edit environment variables for your account”, select Path, choose Edit, add the folder and move it to the top. Open a new PowerShell window before going on.

Flutter’s docs suggest %USERPROFILE%\develop rather than C:\src. That’s fine unless your user name has a space in it, because then so does the path. C:\Program Files is out too, because writing there needs admin rights. They also warn that antivirus software sometimes quarantines bin\flutter.bat, so if flutter isn’t found and that file is missing, look there first.

While Path is open: building Orblit for Windows needs Git’s bin folder on it as well, for its bash.

Checking the SDK

flutter --version

The first run is the slow one, because that’s when it downloads the Dart SDK. The first line it prints should read like this, with a newer version if there is one:

Flutter 3.47.0 • channel stable • https://github.com/flutter/flutter.git

If it names an older version, there’s another Flutter earlier on your PATH, from an old install or a package manager, and the first one found wins. This lists them all, in the order they’re found:

which -a flutter           # where.exe flutter on Windows

The same goes for dart. Flutter carries its own, in the same bin folder, and a Dart installed separately and found first can be a different version.

Each platform’s tools

Flutter builds each platform with that platform’s own tools, and flutter doctor checks for them:

flutter doctor

You only need a tick against the platforms you’re building for. A cross against Android doesn’t matter if all you want is macOS.

To build for	Flutter needs	Then, for Orblit
macOS and iOS	Xcode	macOS and iOS
Android	Android Studio, or the Android SDK’s command line tools	Android
Linux	clang, CMake, Ninja, pkg-config and the GTK 3 headers	Linux
Windows	Visual Studio 2022 or newer, with “Desktop development with C++”	Windows
The web	Chrome	The web

Xcode

Install it from the App Store, then point the command line at it and let it finish installing:

sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer
sudo xcodebuild -runFirstLaunch
sudo xcodebuild -license accept

For iOS, add the iOS platform, which brings the simulator with it:

xcodebuild -downloadPlatform iOS

Until you do, flutter doctor shows a warning like this against Xcode:

! iOS 27.0 Simulator not installed; this may be necessary for iOS and macOS development.

Despite the wording, it doesn’t stop a macOS build. The Mac this page was written on builds and draws macOS with that warning showing.

Android Studio

Install Android Studio and open it once, because its setup wizard is what downloads the Android SDK. Then, in its Settings, under Languages & Frameworks, Android SDK and then SDK Tools, tick “Android SDK Command-line Tools”, which flutter doctor asks for. Then accept the licences:

flutter doctor --android-licenses

Setting up Android adds the NDK and CMake versions Orblit pins.

Linux packages

Flutter’s Linux instructions install clang, CMake, Ninja, pkg-config, the GTK 3 headers and GNU’s libstdc++. That’s enough for an empty Flutter app, and it isn’t enough for Orblit, which links against LLVM’s libc++ and needs glibc 2.38 or newer. Use the list on the Linux page instead. The gallery builds with nothing else installed, so it covers what Flutter needs as well.

Visual Studio

Visual Studio 2022 or newer, not Visual Studio Code, with the “Desktop development with C++” workload ticked in its installer. The Community edition is enough. CI builds Orblit with Visual Studio 2026, and 2022 hasn’t been tried. Setting up Windows adds Developer Mode and bash.

Chrome

flutter doctor looks for Chrome where it’s normally installed. For Chromium, or a Chrome somewhere else, set CHROME_EXECUTABLE to its path. Orblit’s own web build needs a Mac for now, and setting up the web says why.

An empty app first

Before Orblit is involved, check that Flutter can build for your platform on its own:

flutter create hello
cd hello
flutter run -d macos     # or linux, windows or chrome

A window with Flutter’s counter demo in it means Flutter works there. For a phone or a simulator, flutter devices lists the ids to pass to -d.

If the empty app doesn’t run, nothing on Orblit’s pages will fix it, because the renderer builds with the same compilers Flutter’s own code does. flutter doctor -v says more about each cross, and Flutter’s install docs cover each one.

An editor

Nothing here needs one, because every step on this site runs from a terminal. For running and debugging from an editor, VS Code has a Flutter extension, and Android Studio and IntelliJ have a Flutter plugin.

Next: Installing, which adds Orblit to a project.