Hooray!  Thanks for your interest in working on the Linux kernel.

Warning: this is still a work in progress.  We'll announce on the opw-kernel mailing list when this tutorial is finished.  Please [https://live.gnome.org/OutreachProgramForWomen#Application_Process turn in your application] to express interest in the kernel project, and sign up for the [https://groups.google.com/forum/#!forum/opw-kernel opw-kernel mailing list].

== Intro ==

If you run into any issues with this tutorial, please ask questions on the #kernel-opw IRC channel on irc.oftc.net, or on the [https://groups.google.com/forum/#!forum/opw-kernel opw-kernel mailing list].

This tutorial will cover how to get your first patch submitted.  We would love it if accepted interns could test their kernel code on a computer running Linux, however, to get applicants started, this tutorial will describe how to set Linux up in a virtual machine.

You can run Linux from within Windows (or even run Linux on Linux!) from a virtual machine (VM).  This tutorial will show you how to:

[[TableOfContents(0)]]

== Hardware Requirements ==

You need a system with virtualization (VT-d), at least 4GB of RAM, and 40GB of free hard drive space in order to run Linux in a VM.

== Alternatives ==

If your system doesn't meet those requirements, you will need to be running Linux, or dual boot your machine so you can run both Linux and Windows.  We strongly suggest you use the [http://www.ubuntu.com/download/desktop/thank-you?distro=desktop&bits=64&release=lts Ubuntu 12.04 64-bit version].  If your machine doesn't have 64-bit support, you can use the [http://www.ubuntu.com/download/desktop/thank-you?release=lts&bits=32&distro=desktop&status=zeroc 32-bit version].  Once you have Ubuntu installed, please follow the directions [:OPWfirstpatchAlt:here].

If you already have Linux working on a system, please follow the directions [:OPWfirstpatchAlt:here].

= Install VMPlayer =

Go to the [http://www.vmware.com/products/player/ VMPlayer website] and click the 'download' link.  Download the VMPlayer that's appropriate for your operating system (e.g. Windows or Linux 64-bit), and install it.

== Linux installation instructions ==

The [http://www.vmware.com/products/player/ VMPlayer download] comes as a .bundle file.  That's a binary executable, that will launch a setup wizard.

First, change to the directory where you downloaded the VMPlayer binary by using the command {{{cd}}}.

   Tip: {{{cd}}} changes the current working directory to a different directory.  You can learn more about any command by reading the manual pages.  Simply prefix the command with the word "man", e.g. {{{man cd}}}.

Next, check to see if the file is executable.  Run this command:

{{{
ls -l}}}

Then look at at the file's listing, and see if it has the executable ("x") bit set:

{{{
$ ls -l
total 181056
-rw-rw-r-- 1 sarah sarah 185386101 Apr 26 22:19 VMware-Player-5.0.2-1031769.x86_64.bundle}}}

If it doesn't show the executable bit, make the file executable by running:

{{{
chmod a+x VMware-Player-5.0.2-1031769.x86_64.bundle}}}

Then execute the binary by prefixing it with a ./ and running it as the root user with sudo:

{{{
sudo ./VMware-Player-5.0.2-1031769.x86_64.bundle}}}

   Tip: Be careful about what you run as root!  The root user has access to all the files on your system, so you usually don't want to run arbitrary commands as root.  Always run commands without sudo, and without changing to a root terminal, where ever possible.

Now run VMPlayer with the command:

{{{
vmplayer}}}


= Download our Linux VM image =

First, you'll need to install [http://www.7-zip.org/ 7zip].  The homepage has instructions for installing it under Windows.  Under Ubuntu, you can install 7zip by running:

{{{
sudo aptitude install p7zip}}}

Next, download the VM image and uncompress it with 7zip.  Start VMPlayer, choose "Open a Virtual Machine", and open the "OPW kernel Ubuntu 12.04 64-bit" directory.

Before you start the VM, you need to make some adjustments to the emulated hardware.  Click "Edit virtual machine settings".  Now, adjust the amount of memory available to the VM to be the maximum recommended amount of RAM.  You'll need to give the VM at least 2GB of RAM.  You also want to adjust the number of CPUs available to the guest.  It should not be more CPUs than you have available (e.g. if you have a dual core, it should not be more than 2).

Once you've adjusted the emulated hardware, start the VM by clicking "Play virtual machine".

The password for the VM image is "{{{LinuxRules!}}}" (yes, this includes the exclamation point).  If you want to change the password, you can do so with the {{{`passwd`}}} command.

= Explore the kernel tree =
[[Anchor(opw-first-patch-native-start)]]

The VM Image already has Linus' git tree checked out for you.  Open a terminal and change to that git checkout:

{{{
cd git/kernels/linux/}}}

This is the Linux kernel tree.  You can explore it by using the {{{`ls`}}} and {{{`cd`}}} commands.  If you run {{{`ls}}}, you'll see several different folders:

{{{
intern@ubuntu:~/git/kernels/linux$ ls
arch                init             modules.order     System.map
block               ipc              Module.symvers    tags
COPYING             Kbuild           net               tools
CREDITS             Kconfig          README            usr
crypto              kernel           REPORTING-BUGS    virt
Documentation       lib              samples           vmlinux
drivers             MAINTAINERS      scripts           vmlinux.o
extra_certificates  Makefile         security          x509.genkey
firmware            mm               signing_key.priv
fs                  Module.markers   signing_key.x509
include             modules.builtin  sound
}}}

There's more to this directory than meets the eye!  If you run ls -A, you'll see there's a hidden directory called {{{.git}}}.  This contains all the meta information that git uses to track branches, remote repositories, and changes to files in the local directory.

You can view the commit history by running

{{{
git log}}}

If you want a more compact form, you can run a command to see just the "short description" for each commit, with an abbrevated git commit ID:

{{{
git log --pretty=oneline --abbrev-commit}}}

= Play with some git basics =

Git is a distributed revision control system, which means you can hack on your version of the code without having to coordinate with other developers.  Think of your git checkout as a separate copy of Linus' kernel respository.

Git includes support for branches.  Each branch can contain a completely different set of patches.  Kernel developers typically use one branch per patchset.  For example, you might have one branch that includes bug fixes, and another branch that contains commits for a new feature you're working on.

You can run {{{`git branch`}}} to see which branch you're on, and what other branches are available:
{{{
intern@ubuntu:~/git/kernels/linux$ git branch
* master
}}}

In this case, there is only one branch, called master.  The start indicates that the "master" branch is the one you are currently on.  In git speak, we say that you currently have the master branch "checked out".

Create a new branch called 'staging', and checkout that branch by running:

{{{
git checkout -b staging}}}

Now if you run git branch, you'll see that there are two branches, and you are currently on the "staging" branch:

{{{
intern@ubuntu:~/git/kernels/linux$ git branch
  master
* staging
}}}

You can also use the git branch command to show branches on Linus' repository (the remote repository).  Run the command:

{{{intern@ubuntu:~/git/kernels/linux$ git branch -a
  master
* staging
  remotes/origin/HEAD -> origin/master
  remotes/origin/master}}}

The first remote repository that is used to create the git checkout is called "origin".  For now, just remember that "origin" means Linus' remote git repository.

= Update your kernel =

When you create patches, you want to create them on top of the latest kernel from Linus.  If your patch is out-of-date and doesn't apply to the latest tree, it may be rejected.  You'll need to use git to fetch the latest changes:

{{{
git fetch origin}}}

The third word in that command is the name of the remote repository you are fetching from.

That command will fetch the changes from Linus' tree, but it won't actually change in files in the working copy (i.e. the files in this directory).  Git stores the changes in a special hidden directory called {{{.git}}}.  You can view the history of Linus' repository by giving git log the "master" branch of the "origin" remote repository (i.e. Linus' master branch):

{{{
git log origin/master}}}

Next, we need to update our branch to include the changes in Linus' tree.  The safest way to do this is to "rebase" your branch.  This means that if you have any commits on your branch, they will be placed on top of Linus' commits.  Sometimes you may have to edit your commits if there are conflicts, but you should ask your mentor for help with this.  For now, run:

{{{
git rebase origin/master}}}

If you run {{{`git log`}}} to show your staging branch history and then {{{`git log origin/master`}}} to show Linus' master branch history, you should see that they have exactly the same commits.

= Configure, compile, and install the kernel =

The next step is to create a configuration file, compile the new kernel, and install it.

The first thing to know is that the Linux kernel is completely configurable.  Each driver can be separately configured to be installed or not.  There are three choices for driver installation:
 * disable the driver completely,
 * build the driver into the main kernel file (vmlinuz),
 * or build it as a module.

If you build the driver into the main kernel file, it will be loaded at boot time.  The downside is that the kernel will have to load more code at boot for drivers that may not even corespond to hardware on the system.  To avoid this, kernel developers often compile drivers as "modules".  A module is a stand-alone .ko driver file that is loaded when the kernel detects hardware that matches the driver.  For example, you could configure your wifi driver as a module, and the kernel will load it when it detects the wifi card.

The Linux kernel make system uses a special file called {{{.config}}} that stores what drivers are compiled in, or compiled as modules.  Most Linux distributions store the .config file they used to compile your distro kernel in the /boot/ directory:

{{{
FIXME: show boot directory
}}}

You can duplicate the distro's configuration by copying one of the config-* files to a .config file in your git tree.  This has already been done for you in the VM image.

If you want to change the configuration at all, you can run

{{{
make menuconfig}}}

This opens up a text-based GUI that allows you to explore the configuration options.  For now, your configuration is probably fine.

= Make a driver change =

These next couple of steps will allow you to make a change to a driver, and test that you've correctly compiled and installed the modified driver.

= Test your changes =

= Set up git =

Before you make your first commit using git, you'll need to do some setup.

First, you need to tell git what your name and email address is, so that it can be used in the authorship information in the git commit.  Create a file called {{{.gitconfig}}} and add lines like these to it:

{{{
[user]
        name = Your Name
        email = your.email@example.com
}}}

Git includes some "hooks" for scripts that can be run before specific git commands are executed.  The "pre-commit" hook is run before you make a git commit with the {{{`git commit``}}} command.

Linux kernel developer have very stringent guidelines for [http://lxr.linux.no/#linux/Documentation/CodingStyle coding style].  They're so picky, they created a script called [http://lxr.linux.no/#linux/scripts/checkpatch.pl checkpatch.pl] that you can run over your patches to make sure the patch compiles to the kernel coding style.

To ensure that you create good commits that comply with the coding style, you can run checkpatch.pl over your commit with the "pre-commit" hook.  That means git will refuse to commit your changes if it doesn't compily with kernel coding style (unless you pass {{{git commit}}} the -n flag to bypass git hooks).

Edit the {{{.git/hooks/pre-commit}}} file and add the following line:

{{{
exec git diff --cached | scripts/checkpatch.pl --no-signoff -}}}

= Create a patch =

Before you create your patch, we suggest you read about PatchPhilosophy.  That document will help you create patches that are easy to read, and have a better chance of being applied by maintainers.

= Submit a patch =