The following instructions outline how to set up your development environment for starting development on Lichess mobile.
If you get stuck during the installation process the most suitable place to seek help is the #lichess-dev-onboarding
channel on Discord (https://discord.gg/lichess).
This project uses Flutter.
- Follow the flutter install guide. This project is meant to run on iOS and Android, so you need to follow the "Platform setup" section of that guide to install the iOS and/or Android platform.
Warning
Installing on Linux using snapd
might cause some problems building stockfish.
Installing flutter manually is a known workaround.
- Switch to the beta channel by running
flutter channel beta
andflutter upgrade
Note
We'll use Flutter's beta
channel while the app itself is in Beta.
- Ensure Flutter is correctly configured by running
flutter doctor
Note that this application is not meant to be run on web platform.
If you want to use FVM to manage your Flutter versions effectively, please consult the FVM (Flutter Version Management) guide for comprehensive instructions on installing Flutter on your specific operating system.
This project is currently using FVM 3.x.
Pro Tip: Remember to prepend the 'flutter' prefix when using FVM commands, like this: fvm flutter [command]
.
By default, the app will target the Lichess dev server, so you can start developing without setting up a local server.
During development, you may need a local lila (lichess server scala app) instance to work on this project.
If you work with a local lila, you will also need to setup lila-ws (websocket server).
The fastest and most straight-forward way to get started is using lila-docker.
Instructions to install both lila
and lila-ws
locally can be found in the lila wiki.
To use a real device you will need to enable developer options on it and have adb installed on your computer.
Once that done, you can connect your device either with USB or with Wi-Fi.
Enable USB debugging and connect your phone with USB.
Run adb devices
to check that your device is connected.
On your Android phone:
- Connect your phone to the same wifi network as your host machine
- In Developer Options, toggle Wireless Debugging to ON
- Tap "Wireless Debugging" to enter its menu
- Select Pair device with pairing code
On your computer:
- Pair your phone with
adb pair [phone_ip_address]:[pair_port] [pairing_code]
. - Connect your phone with
adb connect [phone_ip_address]:[connection_port]
. Your phone IP address and connection port should be written on the wireless debugging menu. - Check that your device is connected with
adb devices
Simply follow the instructions in the flutter guide to install Xcode and the iOS simulator.
-
If Chrome crashes, it is likely you need to disable Vulkan in emulator settings:
$ emulator -avd <YourAVD> -feature -Vulkan
You can read more about this issue here.
-
If you cannot access internet you can try launching the emulator with a DNS address:
$ emulator -avd <YourAVD> -dns-server 1.1.1.1
If you are on Linux it seems that the emulator will try to read
/etc/resolv.conf
to find DNS servers. You might want to check that your/etc/resolv.conf
is configured properly rather than using the emulatordns-server
flag first. If you use systemd-resolved, the recommended mode of handling/etc/resolv.conf
is to symlink/etc/resolv.conf
to/run/systemd/resolve/stub-resolv.conf
. -
If you experience high lags or freezes, check the memory settings and be sure to enable hardware acceleration (
-gpu host
).Also disabling the snapshot storage may help:
$ emulator -avd <YourAVD> -no-snapshot-load -no-snapstorage -no-snapshot -no-snapshot-save
-
If you use Wayland, the emulator will not work. You can try to use Xwayland instead. The issue is tracked here.
This project uses code generation to generate data classes with freezed among other things.
We don't commit generated code to the repository, so you need to run it before anything else otherwise the project won't compile:
flutter pub get
dart run build_runner build
While developing you can use the watch command:
dart run build_runner watch
Flutter comes with an analyze
command to run static analysis. While developing you can run:
flutter analyze --watch
It will run analysis continuously, watching the filesystem for changes. It is important to always check for analysis errors.
Use the flutter run
command to run the app on an emulator or a real device. If you need to change the lichess host you can do it like so:
flutter run \
--dart-define=LICHESS_HOST=lichess.dev \
--dart-define=LICHESS_WS_HOST=socket.lichess.org
Warning
Do not use any scheme (https:// or ws://) in url in host, since it's already handled by URI helper method
Note
You can also use the production server but note that you will not be able to log in.
When using lila-docker, the easiest solution is to use the adb reverse command:
adb reverse tcp:8080 tcp:8080
You can then run the app with the following hosts:
flutter run \
--dart-define=LICHESS_HOST=localhost:8080 \
--dart-define=LICHESS_WS_HOST=localhost:8080
Another option is to use the ./lila-docker hostname
command and select your computer's IP address.
You can then run the app with the following hosts:
flutter run \
--dart-define=LICHESS_HOST=[your_computer_ip]:8080 \
--dart-define=LICHESS_WS_HOST=[your_computer_ip]:8080
If you are working with a local lila
server, you need to map some ports from the remote device to the local lila server.
Once your device is available, you can do this by running the following command (you can check if your device is available with adb devices
):
adb reverse tcp:9663 tcp:9663
adb reverse tcp:9664 tcp:9664
This will allow the app to communicate with the local server. 9663 is for http
and 9664 is for websocket
.
To run the application with the local server, you can use the following command:
flutter run \
--dart-define=LICHESS_HOST=localhost:9663 \
--dart-define=LICHESS_WS_HOST=localhost:9664
Note
The ports above are the default ones for lila, if you have changed them, you will need to adjust the commands accordingly.
dart devtools
Then run the app with the flutter run
command above, and a link to the logging page will be printed in the console.