# Building on Linux

**Notes:**

* The following steps are verified on
  * [x] Lubuntu 20.04 - x86\_64
  * [x] Linux Mint 20.3 - x86\_64
  * [ ] Ubuntu 20.04 - aarch64
  * [ ] Redhat Linux - x86\_64
  * [x] Fedora 37 - x86\_64
  * [x] Arch Linux - x86\_64
  * [ ] Deepin - x86\_64
  * [ ] Raspberry Pi OS - aarch64
* You may need to disable hardware 3D acceleration if you are running AppFlowy in a VM. Otherwise, certain GL failures will prevent the app from launching.
* This guide assumes that you are using the **bash** shell on Linux. You can however, replicate these steps on **zsh** or other alternative Linux terminal shells, with minor alterations.

{% hint style="warning" %}
**If you encounter any issues, have a look at** [**Troubleshooting**](https://appflowy.gitbook.io/docs/essential-documentation/contribute-to-appflowy/software-contributions/environment-setup/trouble-shotting) **first. If your issue is not included in the page, please create an** [**issue**](https://github.com/AppFlowy-IO/appflowy/issues/new/choose) **or ask on** [**Discord**](https://discord.gg/9Q2xaN37tV)**.**
{% endhint %}

{% hint style="danger" %}
**Attention:** There is an issue affecting Ubuntu 22.04, Fedora 37, and PopOS 22.04:

Failed to load dynamic library 'libdart\_ffi.so': libssl.so.1.1: cannot open shared object file: No such file or directory. The issue can be fixed by installing the required missing libraries:

**For Fedora Workstation:**

```shell
sudo dnf install openssl-devel
```

**For Fedora Silverblue:**

```shell
rpm-ostree upgrade
rpm-ostree install openssl1.1.x86_64
```

For Silverblue, it is necessary to perform both the upgrade and the installation.

**For Ubuntu & PopOS:**

1. Download the required package by executing the following command:

```shell
wget http://archive.ubuntu.com/ubuntu/pool/main/o/openssl/libssl1.1_1.1.0g-2ubuntu4_amd64.deb
```

2. Install the downloaded package using the following command:

```shell
sudo dpkg -i libssl1.1_1.1.0g-2ubuntu4_amd64.deb
```

If the provided link for Ubuntu & PopOS is expired or returns an error 404, you can search for "libssl1.1\_1.1.1" on the [page](http://nz2.archive.ubuntu.com/ubuntu/pool/main/o/openssl/?C=M;O=D).
{% endhint %}

### Step 1: Get the source code

Clone the source code from our Github project.

```shell
git clone https://github.com/AppFlowy-IO/AppFlowy.git
```

{% hint style="warning" %}
Ensure that git is installed in your system!! Use your package manager to install git if your distribution doesn't ship with git.

```bash
# Ubuntu
sudo apt install git
```

```bash
# Fedora
sudo dnf install git
```

```bash
# Arch
sudo pacman -S git
```

{% endhint %}

{% hint style="info" %}
You should fork the code instead if you wish to submit code to AppFlowy. You will find information on that in [Setting Up Your Repositories](https://docs.appflowy.io/docs/~/changes/m6N8vk400Qj23REmHprl/essential-documentation/contribute-to-appflowy/software-contributions/submitting-code/setting-up-your-repositories).
{% endhint %}

<figure><img src="https://1003959744-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fvs4LQcuzr0JR34ApS5sM%2Fuploads%2FYZYPGWsQYhdzsH0zHwxx%2FScreenshot%20from%202023-02-27%2013-51-27.png?alt=media&#x26;token=38d243a8-40d8-49f8-b0a0-f5d148c86b98" alt=""><figcaption><p>Image: Cloning the source from the Github repository.</p></figcaption></figure>

### Step 2: Install your build environment

#### **Install system prerequisites:**

{% tabs %}
{% tab title="Ubuntu" %}

```bash
sudo apt-get install curl build-essential libsqlite3-dev libssl-dev clang cmake ninja-build pkg-config libgtk-3-dev unzip libkeybinder-3.0-dev
```

{% endtab %}

{% tab title="Fedora" %}

```bash
sudo dnf install sqlite-devel keybinder3-devel clang cmake ninja-build openssl-devel
```

{% endtab %}

{% tab title="Arch" %}

```bash
sudo pacman -S curl base-devel sqlite openssl clang cmake ninja pkg-config gtk3 unzip libkeybinder3 xdg-user-dirs
```

{% endtab %}
{% endtabs %}

<figure><img src="https://1003959744-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fvs4LQcuzr0JR34ApS5sM%2Fuploads%2Fky8BP5iodQkY7ESCPqUs%2FScreenshot%20from%202023-02-27%2013-32-41.png?alt=media&#x26;token=1a3b62a6-3061-4959-a588-efe2685c7892" alt=""><figcaption><p>Image: Installing prerequisites on Ubuntu.</p></figcaption></figure>

#### **Install flutter (three different methods):**

{% hint style="danger" %}
Flutter version 3.7.9 is the recent supported stable release used for for building AppFlowy. Building with the latest stable Flutter release is not tested and might throw errors while building.
{% endhint %}

* **Method 1:** Install flutter according to <https://docs.flutter.dev/get-started/install/linux>. Make sure to install flutter in a directory that is appropriate for you.
* **Method 2:** You can use the code below to install flutter manually on your linux system.

```bash
git clone https://github.com/flutter/flutter.git --branch 3.7.9
cd flutter
echo -e "\nexport PATH=\$PATH:"`pwd`"/bin" >> ~/.bashrc
source ~/.bashrc
flutter
cd ..
```

<figure><img src="https://github.com/AppFlowy-IO/documentations/blob/main/.gitbook/assets/Screenshot%20from%202023-02-27%2013-55-23.png" alt=""><figcaption><p>Image: Installing flutter manually.</p></figcaption></figure>

* **Method 3**: You can also use a runtime version manager like [asdf](https://asdf-vm.com/) or a flutter-specific version manager to install flutter on your system. Assuming you are using the **bash** shell, follow these steps:

1. Clone asdf.

```bash
git clone https://github.com/asdf-vm/asdf.git ~/.asdf --branch v0.11.1
```

2. Add the path to asdf and enable asdf auto-completion in your shell.

```bash
echo -e '\n# asdf configuration \n. "$HOME/.asdf/asdf.sh"\n. "$HOME/.asdf/completions/asdf.bash"' >> ~/.bashrc
source ~/.bashrc
```

{% hint style="warning" %}
If you are not using **bash**, check the official [asdf guide](https://asdf-vm.com/guide/getting-started.html) to learn how to set up asdf for your shell.
{% endhint %}

3. Install flutter via asdf and set it as your local runtime at the AppFlowy source directory (`xx/AppFlowy/`).

```bash
cd AppFlowy
asdf plugin-add flutter
asdf install flutter 3.7.9-stable
rm -rf .tool-versions
asdf local flutter 3.7.9-stable 
cd ..
```

{% hint style="warning" %}
Some distributions might miss certain packages essential for asdf, such as `jq`, `curl`, or `wget`. Please make sure they are installed via your package manager.\
\
👉 **Ubuntu 22.04** does not come with the package `jq` installed by default, you will have to install by doing:

```bash
sudo apt install jq
```

{% endhint %}

<figure><img src="https://1003959744-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fvs4LQcuzr0JR34ApS5sM%2Fuploads%2F2s4fvNLpUiaL9FPST4mQ%2FScreenshot%20from%202023-02-27%2022-39-23.png?alt=media&#x26;token=16e78504-8746-4d3c-87ce-a6dc90c66e33" alt=""><figcaption><p>Image: Installing flutter using asdf</p></figcaption></figure>

#### **Setting up your development environment**:

Run the setup script from the base directory. (**Note:** You can skip this step if you installed rust using asdf and set it as the local runtime inside the`xx/AppFlowy/` source.)

```bash
cd AppFlowy
./frontend/scripts/install_dev_env/install_linux.sh
source ~/.bashrc
```

<figure><img src="https://1003959744-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fvs4LQcuzr0JR34ApS5sM%2Fuploads%2FZAqR8rBEIyNWbJgQhNvt%2FScreenshot%20from%202023-02-27%2022-43-35.png?alt=media&#x26;token=285b98c2-10f9-4978-87a6-488ffbf2904b" alt=""><figcaption><p>Image: Running script install_linux.sh inside <code>xx/AppFlowy/frontend/scripts/install_dev_env/</code>.</p></figcaption></figure>

{% hint style="warning" %}
**If you get this following warning (image shown below** 👇\*\*):\*\*

***

`Warning: Pub installs executables into $HOME/.pub-cache/bin, which is not on your path. You can fix that by adding this to your shell's config file (.bashrc, .bash_profile, etc.):`

`export PATH="$PATH":"$HOME/.pub-cache/bin"`\
\
Run following command to add the path inside your shell configuration dotfile (`.bashrc`, `.zshrc`, etc.). For **bash** users:

```bash
echo -e '\nexport PATH="$PATH":"$HOME/.pub-cache/bin"' >> ~/.bashrc
source ~/.bashrc
```

OR, you can alternatively do this:

```bash
export PATH="$PATH":"$HOME/.pub-cache/bin
```

{% endhint %}

<figure><img src="https://1003959744-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fvs4LQcuzr0JR34ApS5sM%2Fuploads%2F4edDuqCPFr4CVH6Y39bg%2FScreenshot%20from%202023-02-27%2020-44-39.png?alt=media&#x26;token=18e3856e-a4d0-4ffc-aee2-564f04046433" alt=""><figcaption><p>Image: <code>"Warning: Pub installs executables into $HOME/.pub-cache/bin, which is not on your path."</code></p></figcaption></figure>

### Step 3: Build AppFlowy (Flutter GUI application)

Change your path to the `frontend` directory.

```bash
cd frontend
```

#### Building the AppFlowy binary:

{% tabs %}
{% tab title="Release binary" %}

```bash
cargo make --profile production-linux-x86_64 appflowy 
```

{% endtab %}

{% tab title="Debug binary" %}

```bash
cargo make --profile development-linux-x86_64 appflowy-dev 
```

{% endtab %}
{% endtabs %}

You will find the binary in `frontend/appflowy_flutter/product/[version in x.x.x]/linux/[Binary type (Release/ Debug)]/AppFlowy/`.

<figure><img src="https://1003959744-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fvs4LQcuzr0JR34ApS5sM%2Fuploads%2F7h74K9PWgWFe39Eo4aZR%2FScreenshot%20from%202023-02-27%2023-03-46.png?alt=media&#x26;token=517116f2-2aeb-4c87-843c-ae70ed2bd6cc" alt=""><figcaption><p>Image: Building AppFlowy</p></figcaption></figure>

### Step 4: Run the application

#### For running the release binary:

```bash
cd appflowy_flutter/product/[version number in x.x.x]/linux/Release/AppFlowy
./app_flowy
```

#### For running the debug binary:

```bash
cd appflowy_flutter/product/[version number in x.x.x]/linux/Debug/AppFlowy
./app_flowy
```

{% hint style="info" %}
If you do not know the version number for the AppFlowy binary that you have built, please use your terminal shells' tab completion, or type and enter the`ls`(list) command to reveal the name of folder which is the version number you are building.

**The current version of AppFlowy is 0.1.0.**
{% endhint %}

A new window as shown below will show up after you run the application:

<figure><img src="https://1003959744-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fvs4LQcuzr0JR34ApS5sM%2Fuploads%2Fgit-blob-5a4a88b73f9f3109a9a1ca559a6cec9ab23df297%2FScreenshot%20from%202023-02-27%2021-59-56%20(2)%20(1).png?alt=media" alt=""><figcaption><p>Image: AppFlowy window</p></figcaption></figure>

If using a virtual machine, run the Linux GUI application through x11 on windows (use MobaXterm) for instance:

`export DISPLAY=localhost:10`

### Miscellaneous: Running the application without building (using VS Code)

{% hint style="warning" %}
**Do not use the flatpak distribution of VS Code!**\
\*\*\*\*The flatpak VS Code is sandboxed and uses an isolated shell environment, and cannot access any binaries or libraries installed in your system, including your default system shell.
{% endhint %}

1. Open the `frontend` folder located at `xx/AppFlowy/` with VS Code.
2. Go to the Run and Debug tab and then click AF-desktop: Clean + Rebuild All for the first time running.

![Image: Running the application using VS Code](https://1003959744-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fvs4LQcuzr0JR34ApS5sM%2Fuploads%2Fgit-blob-4de14bff5ec0d1c12f75ec383c5a412b65c8b13a%2Flaunch_appflowy.png?alt=media)