[Nexus S Android Development] bedalus:
Note: If you want to repost this guide, feel free to download it here (text file, includes all XDA formatting.) Please give credit.

Have you read this: http://xdaforums.com/showpost.php?p=21006133&postcount=1144

In that spirit, I'm going to attempt to write a plain-English tutorial on what to do to build this kernel. In fact, change one or two URLs, and you could build practically any kernel!

Note: I'm assuming you're on a PC here. I'm also assuming this isn't your first trip to linux-land, and you've at least used the terminal a few times before now. I'm also going to assume that even if you are a noob, you're not mentally sub-normal. :p

Note2: If this is your first time building a kernel, you may want to print this out, and go slowly, and if you get stuck, post about it in the thread! It will help me improve the guide. :)

I'm a noob at building, but a professional at teaching. It's literally my job! In my noobishness, I made good records of pretty much every step, and I've got lots of time for explaining what each step actually does.

THE STEPS

You'll need one to compile stuff. "For Gingerbread (2.3.x) and newer versions, including the master branch, a 64-bit environment is required." (source)

OK. You're probably thinking of compiling a kernel for ICS or higher right? Is your computer only 32 bit? Pull the processor off the motherboard and count the pins. Just kidding. It won't matter if it is AMD or Intel, but it needs to be a 64 bit processor. I can compile a kernel with just 2GB of RAM and my processor is approaching its 9 year. Even with this lousy set-up, compiling a whole kernel from scratch takes only five minutes.

Install Ubuntu 10.04 64-bit. (Click on this link to download the install CD.)

If you've got a spare hard drive, use the whole thing. If you're good at partitioning, you might consider putting the linux swap partition on a separate disk. You'll want it to be at least 8GB. Putting it on a separate disk will speed things up.

If you don't have a spare disk, you're going to have to resize a partition of an existing OS, to make some new space for Ubuntu. Lets say a minimum of 12GB for the OS plus 8GB for the swap. The more space you can give to the OS, the easier your life will be if you're serious about building stuff.

At the end of the installation it will ask to install a boot-loader. This should be on sda (not sda1!) but you may need to adjust your BIOS to point at the right hard-drive if you later find it doesn't boot into Ubuntu when you restart. Don't worry about Windows, Ubuntu provides a boot menu, so you have the option of booting to Windows instead.

Once Ubuntu is installed, reboot then open a terminal and sort out your credentials:

sudo passwd root

Type in the password you set during the install, then decide on a password for the root user, and enter it once, then again for confirmation. It can be the same as your user password if you like.

Do some updates (this could take a while):

sudo apt-get update && sudo apt-get dist-upgrade

When it's finally finished, you'll have to reboot, then repeat until there's no updates left.

First, you need a whole bunch of packages. You could copy and paste this into your terminal:

sudo add-apt-repository "deb http://archive.canonical.com/ lucid partner" && sudo apt-get update && sudo apt-get install sun-java6-jdk

That's java sorted.

Next up is the dependencies for compiling stuff:

sudo apt-get install git-core gnupg flex bison gperf build-essential zip curl zlib1g-dev libc6-dev lib32ncurses5-dev ia32-libs x11proto-core-dev libx11-dev lib32ncurses5-dev lib32z-dev libgl1-mesa-dev g++-multilib mingw32 tofrodos python-markdown libxml2-utils xsltproc libsdl-dev libesd0-dev libwxgtk2.6-dev libncurses5-dev lib32z1-dev gcc-multilib git-core && sudo ln -s /usr/lib32/mesa/libGL.so.1 /usr/lib32/mesa/libGL.so

Make sure ADB is initialised:

gedit /etc/udev/rules.d/51-android.rules

and copy the below into a blank text file, then edit both instances of <username> to your Ubuntu username (lower-case!) and no chevrons: ="<bedalus>" is wrong. You want ="bedalus"

# adb protocol on crespo/crespo4g (Nexus S)
SUBSYSTEM=="usb", ATTR{idVendor}=="18d1", ATTR{idProduct}=="4e22", MODE="0600", OWNER="<username>"
# fastboot protocol on crespo/crespo4g (Nexus S)
SUBSYSTEM=="usb", ATTR{idVendor}=="18d1", ATTR{idProduct}=="4e20", MODE="0600", OWNER="<username>"

Now save the file!

Follow this link to Mentor Graphics Sourcery CodeBench LITE and do a free signup to get the download link. You can get hold of other ones, like Linaro or Google's own, but I'm using this as an example, because it's the one I use, and Ezekeel published some R&D here that showed there was no measurable benefit to one toolchain over another.

When you've downloaded it, you need to copy it to /opt:

cd /home/<username>/Downloads
cp arm-some-date-some-version-some-arch.tar.bz2 /opt

Note- Obviously that's not the actual name of the file! But you can see what it's really called when you download it.

Now go to /opt and unpack it:

cd /opt
tar xjf arm-some-date-some-version-some-arch.tar.bz2

So now you need to get some source code. You can use 'git clone' if you don't plan on publishing your kernel. But if you've made some modifications and want to share your end result, you need to obey the GPL terms for the linux kernel, which is Open Source, meaning that you are required to make your source available publicly.

Go to github: https://github.com/

...and sign up. It's just a free registration provided you are non-commercial. Github has some useful getting started tutorials, which I suggest you follow:

https://help.github.com/articles/set-up-git

(just follow that first page for now. I will walk you through git in a bit...)

Next, fork a repo:

Go to whichever kernel you like: https://github.com/bedalus/bedalusKERNEL

I'm using mine as an example. Look for the big 'Fork' button.

You've now got your own copy on github, and you can do whatever you like with it, without affecting the original.

However, it's no use if it exists only in the cloud. You need to get a local copy. You'll also want something called a 'remote tracking branch', which will enable you to keep up-to-date with the changes going on in the original repository that you have forked-off from.

Shout 'fork-off!' at the top of your voice.

Uh... okay. Now, to get a local copy, and set up your remote-tracking branches, execute:

cd /home/<username>/
mkdir mykernel

...you can name your new directory whatever you want. It doesn't have to be 'mykernel', then:

git clone https://github.com/<your github username>/bedalusKERNEL.git

In the above, put your git username, and substitute bedalusKERNEL.git for whatever your fork is called. You can actually copy and paste the URL from the top of your new github repo's page if you want.

It's going to download about 800MB if I remember correctly. This will take a while, so go have some marmite on toast.

When that's done, you're ready for the remote-tracking branch:

cd bedalusKERNEL (or whatever your fork is called)
git remote add upstream https://github.com/bedalus/bedalusKERNEL.git
git fetch upstream

The 'git remote add upstream' creates a new branch called upstream, and any changes that the original developer uploads to github can be fetched to your machine with the 'git fetch upstream' command. Notice how this time, the download time is much shorter? That's because of 'delta downloads' which only downloads the differences between what you have, and what they have. (There's some technical detail here.)

You can now enter:

git branch

...to see all your branches. At this point there should be 'origin' and 'upstream'.

Changing branches (you might as well do this now just to have a little go):

git checkout upstream

That will move you onto the upstream branch, as long as you haven't made any 'uncommited' changes in origin. (More on that later.) Change back to origin with:

git checkout origin

You might want to rename your branches to help personalise them, just to make remembering which is which a little bit easier. To change origin to 'my_version' do this:

git branch -m origin my_version

You can change upstream to 'their_version' or something else if you want to. It won't stop anything from working.

More Git Tips later. Let's sort out a build script. If you tinker with any code, you'll inevitably break stuff, and need to fix it, and then need to try building again... So, having a build script is going to save you a lot of time, because there are several steps that can be automated.

Here's how the start of my script looks:

#!/bin/sh
cd /home/dave/mykernel
git branch
read -p "Correct branch? [Y/N]: " -n 1
if [[ ! $REPLY =~ ^[Yy]$ ]]
then
echo -e "\n"
exit 1
fi

This is just a little precaution that I put in to give myself the chance to abort the build before it starts if I'm on the wrong branch. If I don't hit y then the script aborts, and I can checkout the right branch, then restart the script.

echo -e "\nSTARTING...\n"

The \n prints a new line, then on that new line the message 'STARTING...' and then begins another new line. If you put \n\n you can print a blank line. The echo command is a good way of putting notices in a script so you know what stage it is at.

export PATH=$PATH:/opt/toolchain/bin/
export ARCH=arm
export SUBARCH=arm
export CROSS_COMPILE=arm-none-eabi-

If you put these lines in your script, it sets 'environment variables' that tells the make program where to find the compiler, and what processor it's compiling for (ARM).

If you now save your script in the /mykernel directory you created earlier, git can keep track of it as well as the files integral to the kernel. Save it as whatever you like, e.g. "myscript.sh"

...It's important to have the .sh extension so the system knows it is a script.

To make your script executable, run:

chmod a+x myscript.sh

Before you execute the script, you need a .config file in the mykernel directory. If you've cloned my repo, you can get a working one by executing:

cp arch/arm/configs/crespo_release_defconfig ./.config

...this command will only work properly if you are in the mykernel directory when you execute it.

You can mess with this config file if you like! But it's very easy to break the kernel. However, you can always just copy the crespo_release_defconfig again.

Now, to execute the build script run:

./myscript

If you execute your script, your compiler will now build the kernel. It will take time, but even on my ten-years-old PC it takes less than ten minutes from scratch.

The compiler will spit out a lot of messages. Most of the time it's telling you that it has compiled an object (i.e. a .o file, which will all be linked up later to form the kernel) and sometimes you'll see warnings, which is the compiler telling you it thinks something might be wrong. Don't worry, most of the time the compiler is just being over-cautious.

If the compiler hits a real problem with the code, it will print an error, and tell you what file, and what line, and how far along that line it managed to get to before it didn't know what to do. I'll get back to this later. For now, let's assume everything compiled.

You'll see a message about the zImage being created. That's the kernel. You can't use it as it is, you need to put it into a boot.img so you can flash it.

I find it useful to add this command in my build-script:

ls -l /home/dave/mykernel/arch/arm/boot/zImage

ls -l means list with long format. It'll print out the entire contents of a directory with size, time, permissions, etc. if you execute it in a directory, or point it to a directory. However, in the command above, I've pointed it specifically at the zImage file, so it only prints out the details for that. This is so I can check the time. If the time is from yesterday, I can see quickly that there has been an error in the build, and the zImage is still the same one I built yesterday, or an hour ago... etc. depending on the time-stamp printed out.

If you get a 'No such file' error, it's because there is no old zImage, because you haven't ever successfully built one yet.

If you sat and watched the entire thing build, then the timestamp should show the current time, minus a few seconds.

Yay! You've built a kernel. Now you need to make everybody else flash it to their phones too :p

To do this you need to put it into a boot.img, and then into a .zip file.

Download this: http://d-h.st/wVZ (make-boot necessary files)

It's a small download. It's some very simple tools that can split an existing boot image into a ramdisk and zImage, and can also stitch them back up.

Move mkboot.zip into your mykernel folder, right click on it, and select 'Extract Here'. You can now delete mkboot.zip. There is a tool called unbootimg, that can take apart existing boot.img files, I've made things simple by including my own ramdisk, which is compatible with AOSP and CM ROMs. That file is called cyan2disk_new.cpio.gz

We now need to add some new stuff to the script to stitch our zImage and ramdisk together.

If you've not already added the ls -l command I mentioned above, also add this now. Then:

cp /home/dave/mykernel/arch/arm/boot/zImage /home/dave/mykernel/mkboot/

cd /home/dave/mykernel/mkboot

./mkbootimg --kernel zImage --ramdisk cyan2disk_new.cpio.gz --cmdline 'no_console_suspend=1 console=bull's --base 0x30000000 --pagesize 4096 -o boot.img

Remember, your username is not dave! Unless it is. :p Make the appropriate changes to the path.

We're nearly there! This bit is relatively painless. At this point you could save and run the script to check that mkboot is working. If it has worked you can use the same ls -l trick from before, but this time target the boot.img file you just created. If the time-stamp is fresh, it means your boot.img is correct.

TIP: If you haven't switched branches, or run 'make clean', all your .o files are unchanged. The make program keeps track of changes, and only recompiles .o files when the corresponding .c file has been altered. If nothing has changed, your build script will execute very quickly!

To make a flashable .zip file, the easiest thing to do is modify an existing .zip file. You can download my kernel for simplicity, since it already has the necessary script for flashing the entire boot partition. (Most kernels here use koush's any-kernel script, which updates only the zImage and keeps the boot partition's existing ramdisk, so if you try to use another kernel .zip as a template, make sure you correct their updater-script. Using my ramdisk and kernel script will also ensure you keep MTP!)

Once you've downloaded my kernel you should extract it in your home folder, then rename the directory to something like 'myzip'

Now add these lines to your build-script:

cp /home/dave/mykernel/mkboot/boot.img /home/dave/myzip/boot.img

cp /home/dave/mykernel/drivers/scsi/scsi_wait_scan.ko /home/dave/myzip/system/modules/

"What's that second line? With the .ko file?" I hear you say. Depending on what modules you build, you'll need to copy all of them to the folder specified above. Fortunately, when the kernel finishes building, it tells you what modules have also been built. If you don't want modules in your kernel, you can remove the second line above. However, you must edit your .config file: Open it in gedit, use CTRL+F to open the find dialogue, then type "=m" Now, change every one you find into a "=y" ...so now instead of building modules, the kernel will now incorporate all that code into the zImage instead.

Finally, add this line to your build-script:

7z a -r -tzip /home/dave/mykernel.zip /home/dave/myzip/*

Run the script again. if everything has gone smoothly, then you now have a flashable .zip in your home directory!

Congratulations! :D

* * * * * * * * *

I've compiled a list of commands you may find handy when getting to know git.

Add a remote branch and track it

git remote add ezekeel git://github.com/Ezekeel/GLaDOS-nexus-s-ics.git

git fetch ezekeel

git checkout --track -b bln ezekeel/bln

Merge in the changes

git merge bln

Resolve conflicts

git mergetool

List local branches

git branch

List remote branches

git branch -r

Switch branch

git checkout branch_name

Rename a branch

git branch -m old_branch_name new_branch_name

View log with short sha1 hash

git log -10 --pretty=format:"%h - %ar: %s"

Restore to a particular point

(IMPORTANT! Don't do this if you've already pushed your commits to github!)

git reset --hard <sha1 hash>

Restore to your last commit

git reset --hard HEAD

Restore to one commit before your last commit:

git reset --hard HEAD^

Restore to two commits before your last commit:

git reset --hard HEAD^^ (etc.)

As long as you haven't pushed to github,

squash all your recent commits into one:

git rebase -i <sha1> ...then change push to squash (or fixup) for all except the first one

git rebase -i --abort (to abort!)

Add .file (i.e. hidden file)

git add .file (simple!)

Add all new and modified files

git add .

Deleting files

(i.e. after doing rm <files>)

git add -u (git will note which files have been deleted)

Bring files from a directory in another branch

git checkout cyanogenmod drivers/cpufreq/

Tells you what changes you've made so far

git status

Commit your changes

git commit (type in your notes about what you did, then CTRL+X then Y to save)

Sync your commits to your github repo

git push <repo_name> <branch_name>

Delete a remote branch

(WARNING: This will delete the entire branch from github

Note: You cannot do this to the default github branch, but you can change the default branch in the admin tab on the website)

git push <repo_name> :<branch to be deleted>

Find a file (useful for troubleshooting in some situations)

find /home/dave/ -name 'buildlean.sh'

(searches the home folder and subdirectories for 'buildlean.sh')

Find within any *.c file, the text "s5pv210_driver" (good for finding bits of code)

find ./ -type f -name *.c | xargs grep s5pv210_driver

Find within any file, the text "s5pv210_driver" (good for finding bits of code)

find ./ -type f | xargs grep s5pv210_driver