View source for BlissRoms/Compiling BlissRoms

This page only applies to official devices with official maintainers. For information on porting BlissRoms to a new device, visit the [[Porting BlissRoms]] page.

Remember, BlissRoms is a fluid project. Things may change and break at any time. If your device seems to not compile, please get in touch with your device's maintainer, or try and fix the problem yourself. Submit a patch if you think it is necessary.

== Requirements ==

A moderately powerful x86_64 platform machine is required to compile BlissRoms.

The minimum specifications are:
* Any x86_64 CPU with at least two cores
* 8 GB of RAM
* 150 GB of storage

The recommended specifications are:
* A CPU from the last 2-3 years with at least four or more cores
* 16 GB of RAM
* 200 GB of storage (preferably on solid state drives)

This page assumes your machine is already running a fresh copy of Ubuntu 20.04 (LTS), or a derivative, or similar. Builds on other distributions are not officially supported and may not work.

== Dependencies ==

Depending on what version you are trying to compile, refer to the specific page for specific dependencies that are required:

* [[BlissRoms/Compiling BlissRoms/Dependencies/Q | Q]]
* [[BlissRoms/Compiling BlissRoms/Dependencies/P | P (p9.0)]]
* [[BlissRoms/Compiling BlissRoms/Dependencies/O | O (o8.0-o8.1)]]
* [[BlissRoms/Compiling BlissRoms/Dependencies/N | N (n7.0-n7.1)]]
* [[BlissRoms/Compiling BlissRoms/Dependencies/Legacy | All past versions (m6.0 and lower)]]

Once you have finished installing the specific dependencies, refer below for the common dependencies that are required.

First, update the apt cache:

<pre>
sudo apt update
</pre>

This ensures that apt knows about the latest packages (or you will get errors like "missing installation candidate")

Install required build tools (note that this is one line and should be pasted in full to the Terminal):

<pre>
sudo apt install git gnupg flex bison gperf build-essential zip curl zlib1g-dev gcc-multilib g++-multilib libc6-dev-i386 lib32ncurses-dev x11proto-core-dev libx11-dev lib32z1-dev lib32z1-dev ccache libgl1-mesa-dev libxml2 libxml2-utils xsltproc unzip squashfs-tools python-mako libssl-dev ninja-build lunzip syslinux syslinux-utils gettext genisoimage bc xorriso liblz4-tool libncurses5 libncurses5-dev libsdl1.2-dev libwxgtk3.0-gtk3-dev lzop maven pngcrush schedtool lib32readline-dev python
</pre>

Install <code>repo</code>:

<pre>
mkdir -p ~/bin
curl https://storage.googleapis.com/git-repo-downloads/repo > ~/bin/repo
chmod a+x ~/bin/repo
</pre>

Add <code>repo</code> to the <code>PATH</code> by editing <code>.bashrc</code>. Scroll to the end of the file and add those lines:

<pre>
# Export ~/bin
export PATH=~/bin:$PATH
</pre>

To apply your changes to <code>.bashrc</code>, type:

<pre>
source .bashrc
</pre>

You can replace <code>source</code> with <code>.</code> for the same effect.

===== What is <code>source</code>? =====

<code>source</code> is a bash command to read aliases, functions, and commands from the specified file. Typically, you'll supply <code>bash</code> with a configuration file such as <code>.bashrc</code> or <code>.bash_profile</code>, or an initialization file such as <code>envsetup.sh</code>. The difference is that while the configuration file lists configuration and user-defined aliases and functions, initialization files typically hold build commands such as <code>breakfast</code>, <code>brunch</code>, and <code>lunch</code>. Without those commands building would be significantly harder as you would have to memorize the long command to invoke a build manually!

But why do you need to run it after modifying a file? Well, bash cannot automatically detect changes in our files. To solve this, we either <code>source</code> it or log out and log back in, forcing <code>bash</code> to reload configuration files. Keep this in mind, because unlike configuration files, if you forget to source initialization files, build commands will not function!

== Downloading the source ==

You are now ready to download the source code for BlissRoms.

Create a directory for the source:

<pre>
mkdir -p ~/bliss/q
cd ~/bliss/q
</pre>

Before we download, we need to tell <code>repo</code> and <code>git</code> who we are. Run the following commands, substituting your information:

<pre>
git config --global user.email "john.appleseed@example.com"
git config --global user.name "John Appleseed"
</pre>

Now, we’re ready to initialize. We need to tell <code>repo</code> which manifest to use:

<pre>
repo init -u https://github.com/BlissRoms/platform_manifest.git -b q
</pre>

<code>-b</code> is for the branch, and we’re on <code>q</code>, Android 10. It’ll take a couple of seconds. You may need to type <code>y</code> for the color prompt.

Then sync the source:

<pre>
repo sync -j$(nproc --all) -c
</pre>

Note: For more information about the <code>repo</code> tool, visit the [[BlissRoms/Build Tips]] guide to learn more about the <code>repo</code> flags.

<code>repo</code> will start downloading all of the code. This will take a couple of hours, even on a fiber network. Go grab a coffee while you wait!

== Build ==

Set up the build environment:

<pre>
. build/envsetup.sh
</pre>

This is the initialization file we talked about earlier up top. This "initializes" the environment, and imports a bunch of useful build commands required to build your device. Again, you need to remember to <code>source</code> this file every time you log out and log back in, or launch a new <code>bash</code>/Terminal instance.

Define what device you’re going to build. For example, the Nexus 5X, has a codename of <code>bullhead</code>. You can check your specific device's codename on GitHub or on Google. Execute:

<pre>
breakfast bullhead
</pre>

What does this do? <code>breakfast</code> searches repositories for your device "tree", which contains all the details needed to make the build suitable for your device. CPU, kernel info, device screen size, whether the board has Bluetooth, NFC, what frequencies the build needs for Wi-Fi, and a bunch of other things. <code>breakfast</code> will automatically search in the [https://github.com/BlissRoms-Devices/ BlissRoms-Devices GitHub repository], and grab your device tree for you.

Once the device trees have been downloaded, feel free to browse around the source code to see what changed. You should see folders added to device/, kernel/ and vendor/. If you want to return to the root of the source code, execute:

<pre>
croot
</pre>

This command, however, requires you to have <code>source</code>d <code>build/envsetup.sh</code> earlier.

We're ready to build, but before we use the easy command to execute a build, we will first try the manual method. To set up the current terminal environment for building your particular device, execute:

<pre>
lunch bliss_bullhead-userdebug
</pre>

Let's break down the command. <code>lunch</code> initializes the proper environmental variables required for the build tools to build your specific device. Things like <code>BLISS_DEVICE</code> and other variables are set in this stage, and the changed variables will be shown as output. <code>bliss</code> is the ROM that we are building. As convention, all devices will have this prefix. <code>bullhead</code> is the specific device we are building - in this case, the Nexus 5X. Finally, <code>userdebug</code> means that we will build a "user-debuggable" variant. This is usually what most ROMs use for publishing their builds. Manufacturers typically use <code>user</code>, which disables a lot of logging functions and other debugging features.

===== My device isn't booting, and <code>userdebug</code> won't print any <code>adb logcat</code>s. What gives? =====

There is a third build variant called <code>eng</code>, short for "engineering builds". These builds will activate <code>adb logcat</code> during boot, and will show you exactly what is going wrong, where, and why. However, these builds are NOT recommended for normal usage as they are not securely hardened, have log spam that will slow down your device, and other unexpected problems like userspace utilities crashing during runtime. If you want to submit your device for mainline, do NOT submit an <code>eng</code> build!

All set? Let's start the building process. Run:

<pre>
mka blissify
</pre>

And the build should start. The build process will take a long time. Prepare to wait a few hours, even on a decent machine.

===== Why <code>mka</code> and not <code>make</code>? =====

<code>make</code> only runs with 1 thread. <code>mka</code> is properly aliased to use all of your threads by checking <code>nproc</code>.

If you want to customize your thread count (maybe you're building with a fan-screaming laptop in a quiet coffee shop), use <code>make blissify -j#</code>, replacing the hash with the number of threads (example: <code>make blissify -j4</code>).

===== I get an error about no <code>blissify</code> target to build against; what's wrong? =====

If you are building other ROMs, it is usually <code>make bacon</code>. For BlissRoms, we chose the build target of <code>blissify</code>. If that doesn't work, sometimes there is a bug, or the ROM developers do not implement a <code>bacon</code> target to build against. In this case, you will need to find what name they use to initialize a full build of the ROM. Conventionally, it is supposed to be <code>bacon</code>, but some ROM developers change this name, or their build system may actually have a bug that causes the build target to not be found. If you cannot locate the build target, ask the developers of the ROM. Alternatively, you can try poking around in <code>build/make/core/Makefile</code> to see what the build target name is. But this is out of the scope of this article as you're not supposed to be building other ROMs (that's not what this tutorial is for, sorry!)

All right, but that's annoying. You had to type '''three''' commands to build it all. What about running one command?

<pre>
blissify bullhead
</pre>

But what is <code>blissify</code>? It is a compact form of these commands:

<pre>
breakfast bullhead
lunch bliss_bullhead-userdebug
make blissify
</pre>

Note that on other ROMs this command will usually be <code>brunch</code>. Once you have run the command, jump over to the next section.

== After building ==

There are two outcomes to a build - either it fails and you get a red error message from <code>make</code>, or it succeeds and you see the Bliss logo in ASCII. If you encounter the former, you need to go back and fix whatever it's complaining about. Typically, 90% of the time the problem will be in your device tree. For the other 10%, submit a bug report to the ROM developers. Be sure to include the full log of your build to help diagnose the problem, and your device tree.

If you face the latter, congratulations! You've successfully built BlissRoms for your device. Grab the artifacts for your device:

<pre>
cd out/target/product/bullhead/
</pre>

In here, you’ll find a <code>.zip</code> that goes along the lines of <code>Bliss-v11.9-Stable-bullhead-UNOFFICIAL-20190531.zip</code>. Install TWRP, flash the build to your device, and enjoy!

== Troubleshooting ==

If your build failed, there are a couple things you can try.

* Try a fresh <code>repo sync</code> to make your repository up to date. Sometimes, the Internet connection between you and GitHub can be flaky. In rare cases a commit merge might be ongoing, and you might've grabbed an incomplete merge. This should fix the issue 70% of the time.
* Make sure your dependencies are installed correctly. Error messages help out a lot here! Often it will say <code>shared/linked library not found</code> or something along those lines.
* Make sure you <code>source</code>d <code>build/envsetup.sh</code>. This is especially common and worth suspecting if none of the build commands like breakfast and lunch work. If you have <code>repo sync</code>ed do this again.
* Make sure you’re at the root of the build tree. Again, to quickly jump there, use <code>croot</code>.
* Make sure you ran <code>breakfast</code> correctly and it did not error out. Missing device files will prevent successful builds.
* Make sure your computer meets minimum requirements to compile AOSP. Chances are, you need more memory/CPU power to complete a build. Some users are often confused, as the builds will appear to start and work on a under-specification machine, but crash or stop midway with no apparent cause. If this happens, you will probably need better hardware, or you will need to tweak your configuration so that the build will progress normally on your under-spec machine ('''not recommended''').
* Make sure your computer isn't faulty. This is unlikely, but to check, use a stress-test program like Prime95.

If something goes wrong and you've tried everything above, first use Google to look up your error! Most of the errors you encounter is due to misconfiguration and wrong commands entered. More often than not, Google will have the answer you are looking for. If you're still stuck and nothing fixes the problem, then ask us via [https://t.me/Team_Bliss_Build_Support our Telegram Build Support chat]. (Please only ask issues about BlissRoms, not other custom ROMs as we are unable to assist with those!)

== Conclusion ==

Building a ROM is very hard and tedious and the results are very rewarding! If you managed to follow along, congratulations!

After you finish building, you can try out the Git Started guide. Make changes, commit, and send them off to our Gerrit for review! Or better yet, download experimental commits not ready for the mainline repositories and review them! Again, ROM building is a fun project you can work with. I hope this guide was a lot of fun to run through!

-- Eric Park (ideaman924)