For the full guide see https://grapheneos.org/build.
Glossary : GOS => GrapheneOS
Who is this guide for?
This guide is for beginners interested in development of Graphene OS (GOS) and want to build and run a local emulator. This guide assumes you are on Windows 10/11 and want to 'get started' on becoming a developer
Who is this guide not for?
If you want to flash your code to your phone, you will need to follow the full guide linked above.
Disclaimer:
I am not, nor claim to be a developer for GOS, this is my personal guide to help others who want to try out the code.
System requirements:
If your score is around these, you'll get roughly the same build times, if it's significantly lower you will have to wait longer for builds.
Do I need to upgrade my PC?
If you have enough storage space, I'd say not yet. If you get to the point of doing lots of builds and get frustrated with the build times THEN consider upgrading. To work out WHAT to upgrade, open process manager (control + shift + escape) and go to the performance tab and see what is currently maxed out then upgrade THAT component.
Support:
If this guide helps you please like the post, don't post a message saying thanks (so this thread can stay as easy to use as possible).
If you get stuck please post where in the guide you were up to and the error message you are getting and hopefully together we can iron any problems out.
The build guide
1. Installing Windows Subsystem for Linux (WSL)
Open power shell as an administrator.
Run the following command to enable WSL:
dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart
Run the following command to enable the Virtual machine feature:
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart
Restart you PC
Set the default wsl version to 2 with the following command:
wsl --set-default-version 2
Install Debian with the following command:
wsl --install Debian
When prompted create an easy to remember username and password or use a password manager. For this guide we will use:
username gos
password: gos
Extend the wsl pagefile:
Click Start > run and enter the following:
%USERPROFILE%
This will take you to your local user folder, open the file .wslconfig in notepad ( if it doesn't exist create the file).
Add the following to the file:
[wsl2]
memory=20GB
swap=44GB
Memory: I have 32gb installed, I have reserved 12 for windows, giving a value of 20gb, this must be higher than 16Gb or it will fail to build later on.
swap: I have set this so my memory + swap = 64gb
Restart your PC
2. Installing dependencies
Log into your wsl in powershell:
wsl -d Debian
Change your working folder :
cd /home/gos
This value is /home/{username from step 1.5}.
This is important, if you don't change the folder, you are likely to be in the user folder from windows, this will cause everything to be really slow.
Log into the root user:
sudo su
Run the following command to update your system:
apt-get update && apt-get dist-upgrade
Run the following get the majority of dependencies:
apt install yarnpkg zip rsync python3 git gnupg curl openssh-server pulseaudio
install Repo with the following commands:
mkdir ~/bin
PATH=~/bin:$PATH
curl https://storage.googleapis.com/git-repo-downloads/repo > ~/bin/repo
chmod a+x ~/bin/repo
3. Pulling the code
==For this section I am going to assume a stable tag, this is deliberate for stages further in the guide therefore we will use 2025050700.==
Change to the home directory:
cd /home/gos
Create your source folder:
mkdir graphenesource
cd graphenesource
Run the repo initialize command:
repo init -u https://github.com/GrapheneOS/platform_manifest.git -b refs/tags/2025050700
When you do this for the first time, you will be asked for the name and email for Git, if you don't intend to push anything, set this to test and test@test.com, otherwise set your details
Obtain the SSH public keys:
curl https://grapheneos.org/allowed_signers > ~/.ssh/grapheneos_allowed_signers
Verify the manifest:
cd .repo/manifests
git config gpg.ssh.allowedSignersFile ~/.ssh/grapheneos_allowed_signers
git verify-tag $(git describe)
cd ../..
Start the sync process:
repo sync -j8
This step will take some time, I have a 300mbps connection which took : 51 minutes
4. Building and running the emulator
You will need to run through these steps each time you open WSL so you can run the emulator.
NOTE: the first time will be slow, the second will be much much faster
Change to the source folder:
cd /home/gos/graphenesource
Setup the build environment:
source build/envsetup.sh
Set the build target, this allows for the emulator to run on your x86 system:
lunch sdk_phone64_x86_64-cur-userdebug
Set off your build:
m
This step initially will take a long time, mine took : 6 hours
Run the emulator:
emulator
This will load the emulator and a window should pop up loading Graphene OS!
Congratulations! You've build GOS and can now browse the platform locally! Next lets look at the code :D
The Edit Guide
For this section, we are going to use Visual Studio Code IN Windows. The recommended software is Android Studio For Platform, however I couldn't get it working, if someone can, please extend this guide in a future post / comment below
1. Setting up VS Code
Download Visual studio code from here:
https://code.visualstudio.com/download
During installation check the options to add to the context menu to be able to right click to open vs code
Install the follow extensions:
Opening the files:
Open VS code
In the very bottom left corner, click on the blue >< icon marked 'open a remote window'
The focus will then move to the search box at the top in the middle
Choose Connect to WSL using Distro...
Choose Debian from the options
VS code will then reload
Click Open folder and browse to /home/gos/graphenesource
click ok
Congratulations! You can now view and edit the source code!
Fixing a bug guide
This guide will take you through replicating, fixing and testing your first bug, I have chosen a simple one that I know how to replicate and how to fix to help you understand the process
1. Replicate the bug
Load your emulator and try and follow the steps below to find the bug :
Reproduction steps:
Given a user is trying to write a text message
When I press the enter key
Then a new line is added
Bug: When the keyboard loads, the enter key is replaced with an emoji button and I can't add the new line.
2. Fix the bug
This bug has a solution, it was found by 'dot166' thanks very much!
Get the solution code:
https://github.com/GrapheneOS/platform_packages_inputmethods_LatinIME/pull/34/commits
At this link you will find 1 commit with changes to 2 files:
- key_styles_enter.xml
- layoutCustomizer.java (a test file)
Apply the fix in vs code:
To find where this code goes, you need to follow first the repository path then file path to get to the file, you can find this information on the linked pull request, here is how to work out where the first one goes:
Repository: platform_packages_inputmethods_LatinIME
FilePath: java/res/xml/key_styles_enter.xml
combined: packages/inputmethods/LatinIME/java/res/xml/key_styles_enter.xml
Try to work out yourself where the test file goes :)
Test your fix:
- Go back to Building and running the emulator and follow the steps, the rebuild should take around 2 minutes.
- See if the bug is fixed by following the steps
Congratulations, you've now fixed your first bug!
Troubleshooting:
The UI app crashes
it does that, so don't worry about it or work out why and fix it :D
Warning about graphics drivers
Ignore them, it's fine
I can't save my changes in vscode
Make sure you have gone through the steps to use vscode through wsl, the other issue might be where you have downloaded your code to.
Error - you are trying to build in a case in-sensitive file system
You have likely checked out the code to you windows folder. Cut your loses, delete the folder and re-download in the /home/gos folder. Don't try to copy it, it will be so incredible slow to transfer.
Training
Now you have the tools to be able to build GOS now what? Where do you start learning ASOP development.
This is where I am now, so if GOS developer could point to some good training that'd be great.
My learning is here from this playlist:
https://www.youtube.com/watch?v=sF5iU5ChsK8&list=PLAlSOSt8vS8T1841snb91fdx3lBmCs8sO