# Dot HQ Documentation Welcome to the documentation page for Dot HQ products. # Building Dot Browser A step by step guide on how to build Dot Browser. The steps to build Dot are different for every operating system. You will need to go to the appropriate guide for your OS. * [Windows](/main/cloning-dot/windows) * [macOS](/main/cloning-dot/macos) * [Linux](/main/cloning-dot/linux) # Windows This is a step by step guide on how to build Dot Browser on the world's most popular operating system, Windows. ## First things first... * Minimum requirements: * 8GB of RAM * 4 physical CPU cores * 20GB of disk space free * Recommended requirements: * 16GB of RAM * 8 physical CPU cores * 35GB of disk space free * You'll need to be on a 64-bit operating system to clone and build Dot Browser. * Don't know if your computer is 64-bit? (You can [check here](https://superuser.com/a/1225322/1083268)). * Optionally, The Windows 10 ISO is downloadable through the [Installation Media tool](https://www.microsoft.com/en-us/software-download/windows10) * The following software and tools are required for the build process: * Git ([git-scm.org](https://git-scm.org)) * MozillaBuild CLI ([mozilla.org](https://ftp.mozilla.org/pub/mozilla.org/mozilla/libraries/win32/MozillaBuildSetup-Latest.exe)) * Visual Studio ([visualstudio.microsoft.com](https://visualstudio.microsoft.com/downloads/)) * Docker ([docker.com](https://www.docker.com)) * Python 2.7 and 3.9 ([python.org](https://www.python.org/)) * Rust ([rust-lang.org](https://www.rust-lang.org/tools/install)) * Node.JS ([nodejs.org](https://nodejs.org)) * Yarn (`npm i -g yarn`) * Typescript (`npm i -g typescript`) * Select the following settings in Visual Studio Installer: * Desktop development with C++ * Game development with C++ * Windows 10 SDK (version **10.0.17134.0 or higher**) {% hint style="info" %} Dot Browser is based on Firefox, which is why it is referenced a lot in the build process. {% endhint %} ## Clone the repository We're now going to clone Dot Browser. {% tabs %} {% tab title="HTTPS" %} ``` git clone https://github.com/dothq/browser-desktop.git ``` {% endtab %} {% tab title="SSH" %} ``` git clone git@github.com:/dothq/browser-desktop.git ``` {% endtab %} {% endtabs %} Or if you prefer using GitLab: {% tabs %} {% tab title="HTTPS" %} ``` git clone https://gitlab.com/dothq/browser-desktop.git ``` {% endtab %} {% tab title="SSH" %} ``` git clone git@gitlab.com:dothq/browser-desktop.git ``` {% endtab %} {% endtabs %} After the clone is complete, you'll want to enter the `browser-ff` directory in Git Bash. ### Downloading the source code and mounting To download and set up the source code, run the following commands in Git Bash: ```bash ./melon download ./windows-init.sh ``` {% hint style="info" %} `melon` is a build toolkit for Dot Browser. {% endhint %} ## Importing the patches Next, you're going to want to import the patches. You can do this by running the command below in Git Bash. ```bash ./melon import ``` If everything went smoothly with the import, you should see a "success" message. {% hint style="info" %} If you see an error saying that a patch failed due to different line endings, run `./melon fix-le` in Git Bash and try again. {% endhint %} ## Building Dot Browser Now, we're going to want to build Dot Browser for Windows. It's a very resource intensive process so make sure you check the requirements against your computer. It usually takes between 30 minutes and an hour for computers meeting the recommended requirements. To start the build, open a MozillaBuild terminal and `cd` into `browser-ff`. To start the build, run these commands in MozillaBuild: ```bash cd src MOZCONFIG=../configs/windows/mozconfig ./mach build ``` {% hint style="info" %} If you get an error about missing required dependencies, you can install them by running `./melon download-artifacts` in Git Bash. {% endhint %} Once the build is done, we need to make sure the build was successful. Check to see if something appeared like: ``` 01:00:00 Your build was successful! ``` If you see that message, you can move on to the final step. ## Running Dot Browser The final step is to run your locally-built version of Dot Browser. It's as simple as entering the `src` folder and running: ```bash ./mach run ``` And voilà, Dot should appear before your eyes! ![It's magic! ✨](/files/-MP6L79Litc5_EDcMU75) {% hint style="info" %} The Windows build process is still a work-in-progress. If you encounter any issues, please [open an issue on our GitHub repository](https://github.com/dothq/browser/issues/new/choose). {% endhint %} # Linux This is a step by step guide on how to build Dot Browser on Linux. ## First things first... * Minimum requirements: * 8GB of RAM * 4 physical CPU cores * 20GB of disk space free * Recommended requirements: * 16GB of RAM * 8 physical CPU cores * 35GB of disk space free * You'll need to be on a 64-bit operating system to clone and build Dot Browser. * If typing `uname -m` into a terminal returns `x86_64` you are on a 64-bit computer. * The following software and tools are required for the build process: * Git ([git-scm.org](https://git-scm.org)) * NodeJS ([nodejs.org](https://nodejs.org)) * yarn ([npmjs.com/package/yarn](https://www.npmjs.com/package/yarn)) * Rust 1.53.0 ([rust-lang.org](https://www.rust-lang.org/tools/install)) {% hint style="info" %} Dot Browser is based on Firefox, which is why it is referenced a lot in the build process. {% endhint %} ## Clone the repository We're now going to clone Dot Browser. {% tabs %} {% tab title="HTTPS" %} ``` git clone https://github.com/dothq/browser-desktop.git ``` {% endtab %} {% tab title="SSH" %} ``` git clone git@github.com:/dothq/browser-desktop.git ``` {% endtab %} {% endtabs %} Or if you prefer using GitLab: {% tabs %} {% tab title="HTTPS" %} ``` git clone https://gitlab.com/dothq/browser-desktop.git ``` {% endtab %} {% tab title="SSH" %} ``` git clone git@gitlab.com:dothq/browser-desktop.git ``` {% endtab %} {% endtabs %} After the clone is complete, you'll want to enter the `browser-desktop` directory. ### Bootstrap Now run `./melon bootstrap` This will install the required dependencies. {% hint style="info" %} `melon bootstrap` only works on Arch or Ubuntu-based distros at this time. {% endhint %} Then run `cargo install cbindgen sccache` to install the two required Cargo packages. ### Downloading the source code and mounting Now run `./melon download` This will download the source code. {% hint style="info" %} `melon` is a build toolkit for Dot Browser. {% endhint %} ## Importing the patches Once you've downloaded the source code, you're going to want to import the patches. You can do this by running the command below. ```bash ./melon import ``` If everything went smoothly with the import, you should see a "success" message. ## Building Dot Browser Now, we're going to want to build Dot Browser for Linux. It's a very resource intensive process so make sure you check the requirements against your computer. It usually takes 30 minutes for computers in the recommended requirements region. ``` cd src/dot && yarn install && cd ../.. && ./melon build ``` > If you would like to build Dot for 32-bit machines, add the `--arch i686` flag to the build command. Once the build is done, we need to make sure the build was successful, check to see if something appeared like: ``` 01:00:00 Your build was successful! ``` If you see that message, you can move on to the final step. ## Running Dot Browser The final step is to run your locally-built version of Dot Browser. It's as simple as running: ``` ./melon run ``` And voilà, Dot should appear before your eyes! ![It's magic! ✨](/files/-MP6L79Litc5_EDcMU75) If you encounter any issues, [open an issue on our GitHub repository](https://github.com/dothq/browser/issues/new/choose). # macOS This is a step by step guide on how to build Dot Browser on macOS. ## First things first... * Make sure you have at least 20 GB of space free on your hard drive. * You'll need to be on a 64-bit operating system to clone and build Dot Browser. * If typing `uname -m` into a terminal returns `x86_64` you are on a 64-bit computer. * The following software and tools are required for the build process: * Git ([git-scm.org](https://git-scm.org)) * Mercurial ([mercurial-scm.org](https://www.mercurial-scm.org/)) * Homebrew ([brew.sh](https://brew.sh)) * python3 ([python.org](https://www.python.org/downloads/)) * python2 ([python.org](https://python.org)) * git-cinnabar ([github.com/glandium/git-cinnabar/#setup](https://github.com/glandium/git-cinnabar/#setup)) {% hint style="info" %} Dot Browser is based on Firefox, which is why it is referenced a lot in the build process. {% endhint %} ## Downloading the bootstrapper We're now going to install the tool to clone and bootstrap Dot Browser. ``` curl https://raw.githubusercontent.com/dothq/browser-ff/master/python/mozboot/bin/bootstrap.py -o bootstrap.py ``` This will download the `bootstrap.py` Python script from GitHub. Now we want to run the bootstrapper by typing the command below. The bootstrap will take around 10 minutes up to a couple hours. ```bash python3 bootstrap.py ``` After the clone is complete the bootstrapper will ask you what version you want to build. This table will demonstrate the differences between an artifact build and a generic build. | | Artifact builds | Generic builds | | ----------------------------------- | --------------- | -------------- | | Time to build | \~10 seconds | \~1 hour | | Can build on low-end computers | ✅ | ❌ | | Can build front-end (HTML, CSS, JS) | ✅ | ✅ | | Can build C++ code | ❌ | ✅ | | Can build Rust code | ❌ | ✅ | | Modify build system | ❌ | ✅ | ## Building Dot Browser It's time to build the browser! Start by entering the repo directory. ```bash cd dot # or the name of the repo you chose in the bootstrapper ``` Now we can start building. ``` ./mach build ``` If everything went smoothly with the build you should see the following text: ```jsx 1:03.56 Your build was successful! To take your build for a test drive, run: |mach run| ``` ## Running Dot Browser You've made it! You have successfully built Dot Browser. Now it's time to take our build for a test drive. We can do that by running: ``` ./mach run ``` If everything went according to plan, you should see Dot Browser appear before your eyes! ![It's magic! ✨](/files/-MP6L79Litc5_EDcMU75) If you encounter any issues, [open an issue with the correct component on our GitHub repository](https://github.com/dothq/browser/issues/new/choose). # Cross-platform Dot Browser supports cross-platform building. For example, you could be on Windows and you want to build for Linux. {% hint style="warning" %} **Beware!** Some of the features in this doc are broken or buggy {% endhint %} ## First things first... * Minimum requirements: * 8GB of RAM * 4 physical CPU cores * 20GB of disk space free * Recommended requirements: * 16GB of RAM * 8 physical CPU cores * 35GB of disk space free * You'll need to be on a 64-bit operating system to clone and build Dot Browser. * The following software and tools are required for the build process: * Git ([git-scm.org](https://git-scm.org)) * NodeJS ([nodejs.org](https://nodejs.org)) * yarn ([npmjs.com/package/yarn](https://www.npmjs.com/package/yarn)) * Docker {% hint style="warning" %} Follow steps 1 (Cloning Dot Browser) and 2 (Importing patches) on your host machine and then come back here to start step 3 {% endhint %} ## Supported build targets | Build target | Supported? | | -------------- | ---------- | | Windows 64-bit | ✅ | | macOS 64-bit | ✅ | | Linux 64-bit | ✅ | | Windows 32-bit | ❌ | | macOS 32-bit | ❌ | | Linux 32-bit | ❌ | ## Building Dot Browser Now, we're going to want to build Dot Browser for your target OS. See [Supported build targets](/main/cloning-dot/cross-platform#supported-build-targets) for a list of supported build targets. It's a very resource intensive process so make sure you check the requirements against your computer. It usually takes 30 minutes for computers in the recommended requirements region. ```bash ./melon build # target-os could be: windows, macos or linux ``` Once the build is done, we need to make sure the build was successful, check to see if something appeared like: ``` 01:00:00 Your build was successful! ``` If you see that message, you can move on to the final step. | OS | Built binaries | | ------- | ---------------------------------------------------- | | Windows | `MOZ_APP_NAME-VERSION-LANGUAGE-win64-installer.exe` | | Unix | `MOZ_APP_NAME-VERSION.LANGUAGE.linux-x86_64.tar.bz2` | ## Running Dot Browser The final step is to run your cross-built version of Dot Browser. {% hint style="danger" %} Just remember you **will not** be able to run Windows binaries on Unix based systems like macOS or Linux. And you still might have issues running macOS binaries on Linux and vice-versa. {% endhint %} It's as simple as running: ``` ./melon run ``` And voilà, Dot should appear before your eyes! # Common issues This is sort of like a FAQ for issues you might face while building Dot. ## Could not list any recent revisions in your clone. ### What happened? `git-cinnabar` could not find any cinnabar metadata in your clone. ### Solutions You could try updating the origin remote by typing `git remote update origin` # Components List of components in Dot Browser to easily identify what went wrong in bug reports. * [Accessibility](/main/components#accessibility) * [Adblocker](/main/components#adblocker) * [Bookmarks](/main/components#bookmarks) * [Build System](/main/components#build-system) * [DevTools](/main/components#devtools) * [DevTools: Accessibility](/main/components#accessibility-1) * [DevTools: Application](/main/components#application) * [DevTools: Console](/main/components#console) * [DevTools: Debugger](/main/components#debugger) * [DevTools: Inspector](/main/components#inspector) * [DevTools: Memory](/main/components#memory) * [DevTools: Network](/main/components#network) * [DevTools: Performance](/main/components#performance) * [DevTools: Storage](/main/components#storage) * [DevTools: Styles Editor](/main/components#styles-editor) * [Downloads](/main/components#downloads) * [Extensions](/main/components#extensions) * [Gecko](/main/components#extensions-1) * [History](/main/components#gecko-1) * [Icons](/main/components#icons) * [New Tab Page](/main/components#history-1) * [Search](/main/components#new-tab-page-1) * [Settings](/main/components#settings) * [Synchronisation/Sync server](/main/components#synchronisation-sync-server) * [Tabs](/main/components#tabs) * [User Interface](/main/components#user-interface) ## Accessibility Anything that affects the accessibility of the browser. ## Adblocker Example issues for this component could be: UI bugs in the Adblocker extension, false positives in the block lists or sites which might need to be added to the block lists. If your issue occurs in that component, it is most likely valid. ## Bookmarks Example issues for this component could be: problems with parsing exported bookmarks files, problems with the bookmarks bar. If the issue occurs in that component, it is most likely valid. ## Build System Example issues for this component could be: issues with building on your platform, issues with bootstrapping, build issues. If the issue occurs in that component, it is most likely valid. ## DevTools As DevTools is a large component, we have divided each section into sub-components. Make sure you state which sub-component the issue is occuring in, inside your issue. ### Accessibility Any issues with accessibility in the DevTools UI. ### Application Any issues with the "Application" tab in DevTools. ### Console Any issues parsing code or UI issues in the "Console" tab. We do not accept issues which are reproducible in other browser engines as it probably functions as intended and is not an issue. ### Debugger Any issues with the "Debugger" tab in DevTools. We do not accept issues which are reproducible in other browser engines as it probably functions as intended and is not an issue. ### Inspector Any issues with the "Inspector" tab in DevTools. ### Memory Any issues with the "Memory" tab in DevTools. ### Network Any issues with the "Network" tab in DevTools. Examples of issues for the Network sub-component could be: issues parsing headers, issues parsing the body, etc. ### Performance Any issues with the "Performance" tab in DevTools. We do not accept issues which are to do with your website's performance. However, if the issue is reproducible on other websites we may accept it. ### Storage Any issues with the "Storage" tab in DevTools. Make sure you redact any personal information like cookies, session tokens, etc. ### Styles Editor Any issues with the "Styles Editor" tab in DevTools. ## Downloads Example issues for this component could be: issues with downloading files, bad file formats, reporting false positives for the malware-detection. If the issue occurs in that component, it is most likely valid. ## Extensions Any issue with the extensions in the [extensions subrepo](https://github.com/dothq/browser/tree/main/extensions). If the issue occurs in that component, it is most likely valid. ## Gecko Any issues with renderering web pages, compatibility issues (works on Chromium-based browsers), or anything broken in the Gecko browser engine. If the issue occurs in that component, it is most likely valid. ## History If an issue occurs in that component, it is most likely valid. ## Icons Any issues with the icons in the browser. If an issue occurs in that component, it is most likely valid. ## New Tab Page Any issues with the Dot Browser version of [Compass (our New Tab Page)](https://github.com/dothq/ntp). If an issue occurs in that component, it is most likely valid. ## Search Any issues with the Awesome Bar (primary search bar) or the secondary search bar. Issues with the built-in search engines or the search engine system in Preferences can also count for this component. If an issue occurs in that component, it is most likely valid. ## Settings Any issues with the Settings Web UI (about:preferences). We also count issues in the Configuration Web UI (about:config). If an issue occurs in that component, it is most likely valid. ## Synchronisation/Sync server This component has no information yet. Sync server is still a work in progress. ## Tabs Any issues with the Tabbar, Tab switcher (Ctrl+Tab) or Tabs overflow list. If an issue occurs in that component, it is most likely valid. ## User Interface Any issues with the look and feel of the browser (bad styling, awful UI on 3rd party themes). If an issue occurs in that component, it is most likely valid. # Making changes to Dot Adding features or changing things in the Dot Browser source code can be quite complex at first, so this doc should make it easier to understand. ## Introduction We will assume you have cloned and setup Dot Browser already. If you haven't please read [🏗 Building Dot Browser](/main/cloning-dot) steps # Dot HQ Documentation Welcome to the documentation page for Dot HQ products. # Building Dot Browser A step by step guide on how to build Dot Browser. The steps to build Dot are different for every operating system. You will need to go to the appropriate guide for your OS. * [Windows](/cloning-dot/windows) * [macOS](/cloning-dot/macos) * [Linux](/cloning-dot/linux) # Windows This is a step by step guide on how to build Dot Browser on the world's most popular operating system, Windows. ## First things first... * Minimum requirements: * 8GB of RAM * 4 physical CPU cores * 20GB of disk space free * Recommended requirements: * 16GB of RAM * 8 physical CPU cores * 35GB of disk space free * You'll need to be on a 64-bit operating system to clone and build Dot Browser. * Don't know if your computer is 64-bit? (You can [check here](https://superuser.com/a/1225322/1083268)). * Optionally, The Windows 10 ISO is downloadable through the [Installation Media tool](https://www.microsoft.com/en-us/software-download/windows10) * The following software and tools are required for the build process: * Git ([git-scm.org](https://git-scm.org)) * MozillaBuild CLI ([mozilla.org](https://ftp.mozilla.org/pub/mozilla.org/mozilla/libraries/win32/MozillaBuildSetup-Latest.exe)) * Visual Studio ([visualstudio.microsoft.com](https://visualstudio.microsoft.com/downloads/)) * Docker ([docker.com](https://www.docker.com)) * Python 2.7 and 3.9 ([python.org](https://www.python.org/)) * Rust ([rust-lang.org](https://www.rust-lang.org/tools/install)) * Node.JS ([nodejs.org](https://nodejs.org)) * Yarn (`npm i -g yarn`) * Typescript (`npm i -g typescript`) * Select the following settings in Visual Studio Installer: * Desktop development with C++ * Game development with C++ * Windows 10 SDK (version **10.0.17134.0 or higher**) {% hint style="info" %} Dot Browser is based on Firefox, which is why it is referenced a lot in the build process. {% endhint %} ## Clone the repository We're now going to clone Dot Browser. {% tabs %} {% tab title="HTTPS" %} ``` git clone https://github.com/dothq/browser-desktop.git ``` {% endtab %} {% tab title="SSH" %} ``` git clone git@github.com:/dothq/browser-desktop.git ``` {% endtab %} {% endtabs %} Or if you prefer using GitLab: {% tabs %} {% tab title="HTTPS" %} ``` git clone https://gitlab.com/dothq/browser-desktop.git ``` {% endtab %} {% tab title="SSH" %} ``` git clone git@gitlab.com:dothq/browser-desktop.git ``` {% endtab %} {% endtabs %} After the clone is complete, you'll want to enter the `browser-ff` directory in Git Bash. ### Downloading the source code and mounting To download and set up the source code, run the following commands in Git Bash: ```bash ./melon download ./windows-init.sh ``` {% hint style="info" %} `melon` is a build toolkit for Dot Browser. {% endhint %} ## Importing the patches Next, you're going to want to import the patches. You can do this by running the command below in Git Bash. ```bash ./melon import ``` If everything went smoothly with the import, you should see a "success" message. {% hint style="info" %} If you see an error saying that a patch failed due to different line endings, run `./melon fix-le` in Git Bash and try again. {% endhint %} ## Building Dot Browser Now, we're going to want to build Dot Browser for Windows. It's a very resource intensive process so make sure you check the requirements against your computer. It usually takes between 30 minutes and an hour for computers meeting the recommended requirements. To start the build, open a MozillaBuild terminal and `cd` into `browser-ff`. To start the build, run these commands in MozillaBuild: ```bash cd src MOZCONFIG=../configs/windows/mozconfig ./mach build ``` {% hint style="info" %} If you get an error about missing required dependencies, you can install them by running `./melon download-artifacts` in Git Bash. {% endhint %} Once the build is done, we need to make sure the build was successful. Check to see if something appeared like: ``` 01:00:00 Your build was successful! ``` If you see that message, you can move on to the final step. ## Running Dot Browser The final step is to run your locally-built version of Dot Browser. It's as simple as entering the `src` folder and running: ```bash ./mach run ``` And voilà, Dot should appear before your eyes! ![It's magic! ✨](/files/-MP6L79Litc5_EDcMU75) {% hint style="info" %} The Windows build process is still a work-in-progress. If you encounter any issues, please [open an issue on our GitHub repository](https://github.com/dothq/browser/issues/new/choose). {% endhint %} # Linux This is a step by step guide on how to build Dot Browser on Linux. ## First things first... * Minimum requirements: * 8GB of RAM * 4 physical CPU cores * 20GB of disk space free * Recommended requirements: * 16GB of RAM * 8 physical CPU cores * 35GB of disk space free * You'll need to be on a 64-bit operating system to clone and build Dot Browser. * If typing `uname -m` into a terminal returns `x86_64` you are on a 64-bit computer. * The following software and tools are required for the build process: * Git ([git-scm.org](https://git-scm.org)) * NodeJS ([nodejs.org](https://nodejs.org)) * yarn ([npmjs.com/package/yarn](https://www.npmjs.com/package/yarn)) * Rust 1.53.0 ([rust-lang.org](https://www.rust-lang.org/tools/install)) {% hint style="info" %} Dot Browser is based on Firefox, which is why it is referenced a lot in the build process. {% endhint %} ## Clone the repository We're now going to clone Dot Browser. {% tabs %} {% tab title="HTTPS" %} ``` git clone https://github.com/dothq/browser-desktop.git ``` {% endtab %} {% tab title="SSH" %} ``` git clone git@github.com:/dothq/browser-desktop.git ``` {% endtab %} {% endtabs %} Or if you prefer using GitLab: {% tabs %} {% tab title="HTTPS" %} ``` git clone https://gitlab.com/dothq/browser-desktop.git ``` {% endtab %} {% tab title="SSH" %} ``` git clone git@gitlab.com:dothq/browser-desktop.git ``` {% endtab %} {% endtabs %} After the clone is complete, you'll want to enter the `browser-desktop` directory. ### Bootstrap Now run `./melon bootstrap` This will install the required dependencies. {% hint style="info" %} `melon bootstrap` only works on Arch or Ubuntu-based distros at this time. {% endhint %} Then run `cargo install cbindgen sccache` to install the two required Cargo packages. ### Downloading the source code and mounting Now run `./melon download` This will download the source code. {% hint style="info" %} `melon` is a build toolkit for Dot Browser. {% endhint %} ## Importing the patches Once you've downloaded the source code, you're going to want to import the patches. You can do this by running the command below. ```bash ./melon import ``` If everything went smoothly with the import, you should see a "success" message. ## Building Dot Browser Now, we're going to want to build Dot Browser for Linux. It's a very resource intensive process so make sure you check the requirements against your computer. It usually takes 30 minutes for computers in the recommended requirements region. ``` cd src/dot && yarn install && cd ../.. && ./melon build ``` > If you would like to build Dot for 32-bit machines, add the `--arch i686` flag to the build command. Once the build is done, we need to make sure the build was successful, check to see if something appeared like: ``` 01:00:00 Your build was successful! ``` If you see that message, you can move on to the final step. ## Running Dot Browser The final step is to run your locally-built version of Dot Browser. It's as simple as running: ``` ./melon run ``` And voilà, Dot should appear before your eyes! ![It's magic! ✨](/files/-MP6L79Litc5_EDcMU75) If you encounter any issues, [open an issue on our GitHub repository](https://github.com/dothq/browser/issues/new/choose). # macOS This is a step by step guide on how to build Dot Browser on macOS. ## First things first... * Minimum requirements: * 8GB of RAM * 4 physical CPU cores * 20GB of disk space free * Recommended requirements: * 16GB of RAM * 8 physical CPU cores * 35GB of disk space free * You'll need to be on a 64-bit operating system to clone and build Dot Browser. * If typing `uname -m` into a terminal returns `x86_64` you are on a 64-bit computer. * The following software and tools are required for the build process: * Git ([git-scm.org](https://git-scm.org)) * NodeJS ([nodejs.org](https://nodejs.org)) * yarn ([npmjs.com/package/yarn](https://www.npmjs.com/package/yarn)) * Docker * Rust ([rust-lang.org](https://www.rust-lang.org/tools/install)) {% hint style="info" %} Dot Browser is based on Firefox, which is why it is referenced a lot in the build process. {% endhint %} ## Clone the repository We're now going to clone Dot Browser. ``` git clone https://github.com/dothq/browser-ff ``` Or if you prefer using GitLab: ``` git clone https://gitlab.com/dothq/browser-ff ``` After the clone is complete, you'll want to enter the `browser-ff` directory. ### Downloading the source code and mounting Now run `./melon download` This will download the source code. {% hint style="info" %} `melon` is a build toolkit for Dot Browser. {% endhint %} ## Importing the patches Once you've downloaded the source code, you're going to want to import the patches. You can do this by running the command below. ```bash ./melon import ``` If everything went smoothly with the import, you should see a "success" message. ## Building Dot Browser Now, we're going to want to build Dot Browser for macOS. It's a very resource intensive process so make sure you check the requirements against your computer. It usually takes 30 minutes for computers in the recommended requirements region. ``` ./melon build ``` The build runs inside a Docker container so it is separate from your actual machine. Once the build is done, we need to make sure the build was successful, check to see if something appeared like: ``` 01:00:00 Your build was successful! ``` If you see that message, you can move on to the final step. ## Running Dot Browser The final step is to run your locally-built version of Dot Browser. It's as simple as running: ``` ./melon run ``` And voilà, Dot should appear before your eyes! ![It's magic! ✨](/files/-MP6L79Litc5_EDcMU75) If you encounter any issues, [open an issue on our GitHub repository](https://github.com/dothq/browser/issues/new/choose). # Cross-platform Dot Browser supports cross-platform building. For example, you could be on Windows and you want to build for Linux. {% hint style="warning" %} **Beware!** Some of the features in this doc are broken or buggy {% endhint %} ## First things first... * Minimum requirements: * 8GB of RAM * 4 physical CPU cores * 20GB of disk space free * Recommended requirements: * 16GB of RAM * 8 physical CPU cores * 35GB of disk space free * You'll need to be on a 64-bit operating system to clone and build Dot Browser. * The following software and tools are required for the build process: * Git ([git-scm.org](https://git-scm.org)) * NodeJS ([nodejs.org](https://nodejs.org)) * yarn ([npmjs.com/package/yarn](https://www.npmjs.com/package/yarn)) * Docker {% hint style="warning" %} Follow steps 1 (Cloning Dot Browser) and 2 (Importing patches) on your host machine and then come back here to start step 3 {% endhint %} ## Supported build targets | Build target | Supported? | | -------------- | ---------- | | Windows 64-bit | ✅ | | macOS 64-bit | ✅ | | Linux 64-bit | ✅ | | Windows 32-bit | ❌ | | macOS 32-bit | ❌ | | Linux 32-bit | ❌ | ## Building Dot Browser Now, we're going to want to build Dot Browser for your target OS. See [Supported build targets](/cloning-dot/cross-platform#supported-build-targets) for a list of supported build targets. It's a very resource intensive process so make sure you check the requirements against your computer. It usually takes 30 minutes for computers in the recommended requirements region. ```bash ./melon build # target-os could be: windows, macos or linux ``` Once the build is done, we need to make sure the build was successful, check to see if something appeared like: ``` 01:00:00 Your build was successful! ``` If you see that message, you can move on to the final step. | OS | Built binaries | | ------- | ---------------------------------------------------- | | Windows | `MOZ_APP_NAME-VERSION-LANGUAGE-win64-installer.exe` | | Unix | `MOZ_APP_NAME-VERSION.LANGUAGE.linux-x86_64.tar.bz2` | ## Running Dot Browser The final step is to run your cross-built version of Dot Browser. {% hint style="danger" %} Just remember you **will not** be able to run Windows binaries on Unix based systems like macOS or Linux. And you still might have issues running macOS binaries on Linux and vice-versa. {% endhint %} It's as simple as running: ``` ./melon run ``` And voilà, Dot should appear before your eyes! # Common issues This is sort of like a FAQ for issues you might face while building Dot. ## Could not list any recent revisions in your clone. ### What happened? `git-cinnabar` could not find any cinnabar metadata in your clone. ### Solutions You could try updating the origin remote by typing `git remote update origin` # Components List of components in Dot Browser to easily identify what went wrong in bug reports. * [Accessibility](/components#accessibility) * [Adblocker](/components#adblocker) * [Bookmarks](/components#bookmarks) * [Build System](/components#build-system) * [DevTools](/components#devtools) * [DevTools: Accessibility](/components#accessibility-1) * [DevTools: Application](/components#application) * [DevTools: Console](/components#console) * [DevTools: Debugger](/components#debugger) * [DevTools: Inspector](/components#inspector) * [DevTools: Memory](/components#memory) * [DevTools: Network](/components#network) * [DevTools: Performance](/components#performance) * [DevTools: Storage](/components#storage) * [DevTools: Styles Editor](/components#styles-editor) * [Downloads](/components#downloads) * [Extensions](/components#extensions) * [Gecko](/components#extensions-1) * [History](/components#gecko-1) * [Icons](/components#icons) * [New Tab Page](/components#history-1) * [Search](/components#new-tab-page-1) * [Settings](/components#settings) * [Synchronisation/Sync server](/components#synchronisation-sync-server) * [Tabs](/components#tabs) * [User Interface](/components#user-interface) ## Accessibility Anything that affects the accessibility of the browser. ## Adblocker Example issues for this component could be: UI bugs in the Adblocker extension, false positives in the block lists or sites which might need to be added to the block lists. If your issue occurs in that component, it is most likely valid. ## Bookmarks Example issues for this component could be: problems with parsing exported bookmarks files, problems with the bookmarks bar. If the issue occurs in that component, it is most likely valid. ## Build System Example issues for this component could be: issues with building on your platform, issues with bootstrapping, build issues. If the issue occurs in that component, it is most likely valid. ## DevTools As DevTools is a large component, we have divided each section into sub-components. Make sure you state which sub-component the issue is occuring in, inside your issue. #### Accessibility Any issues with accessibility in the DevTools UI. #### Application Any issues with the "Application" tab in DevTools. #### Console Any issues parsing code or UI issues in the "Console" tab. We do not accept issues which are reproducible in other browser engines as it probably functions as intended and is not an issue. #### Debugger Any issues with the "Debugger" tab in DevTools. We do not accept issues which are reproducible in other browser engines as it probably functions as intended and is not an issue. #### Inspector Any issues with the "Inspector" tab in DevTools. #### Memory Any issues with the "Memory" tab in DevTools. #### Network Any issues with the "Network" tab in DevTools. Examples of issues for the Network sub-component could be: issues parsing headers, issues parsing the body, etc. #### Performance Any issues with the "Performance" tab in DevTools. We do not accept issues which are to do with your website's performance. However, if the issue is reproducible on other websites we may accept it. #### Storage Any issues with the "Storage" tab in DevTools. Make sure you redact any personal information like cookies, session tokens, etc. #### Styles Editor Any issues with the "Styles Editor" tab in DevTools. ## Downloads Example issues for this component could be: issues with downloading files, bad file formats, reporting false positives for the malware-detection. If the issue occurs in that component, it is most likely valid. ## Extensions Any issue with the extensions in the [extensions subrepo](https://github.com/dothq/browser/tree/main/extensions). If the issue occurs in that component, it is most likely valid. ## Gecko Any issues with renderering web pages, compatibility issues (works on Chromium-based browsers), or anything broken in the Gecko browser engine. If the issue occurs in that component, it is most likely valid. ## History If an issue occurs in that component, it is most likely valid. ## Icons Any issues with the icons in the browser. If an issue occurs in that component, it is most likely valid. ## New Tab Page Any issues with the Dot Browser version of [Compass (our New Tab Page)](https://github.com/dothq/ntp). If an issue occurs in that component, it is most likely valid. ## Search Any issues with the Awesome Bar (primary search bar) or the secondary search bar. Issues with the built-in search engines or the search engine system in Preferences can also count for this component. If an issue occurs in that component, it is most likely valid. ## Settings Any issues with the Settings Web UI (about:preferences). We also count issues in the Configuration Web UI (about:config). If an issue occurs in that component, it is most likely valid. ## Synchronisation/Sync server This component has no information yet. Sync server is still a work in progress. ## Tabs Any issues with the Tabbar, Tab switcher (Ctrl+Tab) or Tabs overflow list. If an issue occurs in that component, it is most likely valid. ## User Interface Any issues with the look and feel of the browser (bad styling, awful UI on 3rd party themes). If an issue occurs in that component, it is most likely valid. #### # Making changes to Dot Adding features or changing things in the Dot Browser source code can be quite complex at first, so this doc should make it easier to understand. ## Introduction We will assume you have cloned the source code and imported the patches already. If you haven't please read [🏗 Building Dot Browser](/cloning-dot). ## Understanding the file structure | Directory | Purpose | | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | src | The src directory is where you should be editing files and making changes. | | common | The common directory is used for importing files manually. Using the common directory makes more sense for copying new directories and files as you are not able to export a patch for a file that didn't exist to begin with. | | patches | The patches directory is where all the .patch files are dumped after you run `./melon export` | | build | The build directory is where the code for the melon build tool is. It also includes the manual-patches.ts file which is where you declare the manual patches in the common directory. | | configs | The configs directory contains all the build configs for each build target. You shouldn't need to worry about this directory. | ## Exporting patches for files that have been modified If you have edited an existing file in the `src` directory you will need to export your file to the `patches` directory so it is available for everyone else as the `src` directory is never committed to source control. To export the modified file as a patch file, run the following command: ```bash ./melon export # or if you want to export an individual file ./melon export-file ``` You will notice that the files you changed in the `src` directory will now have their own patch files in the `patches` directory. For example, if you edited `src/browser/app/profile/firefox.js` it would create a file in the `patches` directory called `browser-app-profile-firefox-js.patch`. You would then commit that patch file, either to your fork to open a PR or directly to the source code if you have the correct permissions. You are now all done, your modifications to the source code have been saved! ✨ ## Creating manual patches for more advanced operations You are not able to create a patch file for files that did not exist in the `src` directory to begin with. An example of this is creating a new file or directory in `src` that didn't exist before. We can, however, use manual patches for this kind of thing. If you open up `build/manual-patches.ts` in your code editor of choice you should see something like this: ```typescript import { IPatch } from "./interfaces/patch"; const manualPatches: IPatch[] = [ { name: "branding", // name of the manual patch action: "copy", // what action we want to do src: "browser/branding/dot" // this will copy common/browser/branding/dot to src/browser/branding/dot }, { name: "dotui", action: "copy", src: [ "browser/themes/shared/dotui", "browser/themes/windows/dotui", "browser/themes/osx/dotui", "browser/themes/linux/dotui" ] }, ... ]; export default manualPatches; ``` These are all manual patches that are being applied to the source code. If we take a look at the first manual patch we can see it is copying `common/browser/branding/dot` to `src/browser/branding/dot`. This is where the common directory comes in. If we created a file in the `common` directory at the path `browser/testing.txt` and made a manual patch for this: ```typescript { name: "my new manual patch", action: "copy", src: "browser/testing.txt" }, ``` And then we ran `./melon rebuild` to rebuild the manual patches structure. And then `./melon import` to import our patch files and our manual patches, you should see your `my new manual patch` appearing in the logs. If you then went to `src/browser` in your file explorer, you should see `testing.txt` has been copied from `common/browser/testing.txt` to `src/browser/testing.txt`! Now what happens if you want to edit `src/browser/testing.txt`? Would you have to update `common/browser/testing.txt` too? Nope! When you edit `src/browser/testing.txt` if you run `./melon export` it will automatically export the manual patches too and it copies your changes in `src/browser/testing.txt` to `common/browser/testing.txt` so everything is up to date. And that is how manual patches work!