|
Size: 13640
Comment:
|
Size: 7431
Comment:
|
| Deletions are marked like this. | Additions are marked like this. |
| Line 1: | Line 1: |
| 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]. |
Hooray! Thanks for your interest in working on the Linux kernel. The next step is to [:OPWApply:apply] to OPW, and use this tutorial to create your first patch to the Linux kernel. |
| Line 6: | Line 4: |
| Line 9: | Line 6: |
| 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. | [[Anchor(kernel-setup-done)]] = Contribution Instructions = '''PLEASE NOTE: DO NOT SEND YOUR FIRST PATCH TO THE MAIN LINUX MAILING LISTS!''' |
| Line 11: | Line 10: |
| 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: | Instead, send your patch to the [https://groups.google.com/forum/#!forum/opw-kernel opw-kernel mailing list]. |
| Line 13: | Line 12: |
| [[TableOfContents(0)]] | [[Include(FirstKernelPatch)]] |
| Line 15: | Line 14: |
| == Hardware Requirements == | = Resending patches = |
| Line 17: | Line 16: |
| 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. | If you find a mistake in your initial patch submission, and you need to correct it, make sure to version your new patch as described in the previous section. |
| Line 19: | Line 18: |
| == 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: |
If your patch has not been responded to within three business days (not including weekend days), the mentors may have missed it, and you may want to resend it. Make sure to use RESEND in the subject line if the patch itself has not been changed (meaning no changes in the patch description or body). You can use the `--subject-prefix` argument to `git format-patch` to add RESEND, by running |
| Line 40: | Line 21: |
| ls -l}}} | git format-patch --subject-prefix="RESEND PATCH" }}} |
| Line 42: | Line 24: |
| Then look at at the file's listing, and see if it has the executable ("x") bit set: | That command will create an email you can send with mutt (or your approved mail client) that will have a subject that looks like: |
| Line 45: | Line 27: |
| $ 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 |
[RESEND PATCH] Foo: Fix these things |
| Line 107: | Line 30: |
| 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. | If your patch hasn't been responded to within a week, ping a mentor (or sarahsharp) on the IRC channel. '''Do not ping mentors immediately after sending patches.''' We know you're excited/worried about submitting your first patch, but mentors need to take time to properly respond and review patches. |
| Line 109: | Line 32: |
| You can view the commit history by running | [[Anchor(tips)]] = Tips for Applying to be an OPW Kernel intern = |
| Line 111: | Line 35: |
| {{{ git log}}} |
After you complete the first patch tutorial and get a patch accepted into the Linux kernel, you may wonder what to do next. We recommend getting 3-5 single cleanup patches accepted, and then moving on to create a patchset with several different cleanups for the same staging driver. Please limit your patchsets to no more than 10 patches, unless you've been told to break the patchset down further. Please try to limit your patches to no more than 100 to 200 lines total, to avoid mentors getting patch review fatigue. If you're bored and losing focus when you're tediously creating the patch, it's highly likely the mentors will get tired while reviewing it. :) Once you've gotten 3-5 patchsets accepted, move onto exploring more complex tools, like sparse and coccinelle. Try to tackle some code refactoring, or take on a [:OPWTasks:small task] that a mentor has recommended for their project. Mentors are more likely to pick you for their project if they see you tackling tasks from that project or asking questions about that project. |
| Line 114: | Line 37: |
| 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: | Tackling increasingly complex patches mean the OPW mentors will get a sense of how good a C programmer you are. It's very easy for beginner C programmers to do some of the more simple checkpatch cleanups, but it takes more skill to complete our mentor's small tasks, or sparse and coccinelle patches. You may find yourself trying to understand advanced C topics, such as [http://stackoverflow.com/questions/1665250/why-declare-a-variable-or-function-static-in-c/1665270#1665270 when to declare a function static]. If you are attempting silence a checkpatch.pl warning, and you don't understand what the warning message means, please ask on IRC or the mailing list before blindly trying to silence the warning. We value applicants that know when they need help, and we are happy to share knowledge and expand your skillset. |
| Line 116: | Line 39: |
| {{{ git log --pretty=oneline --abbrev-commit}}} |
Please remember that we value consistently clean patches, so make sure to compile your code and ensure that no checkpatch errors or build warnings were added. Do this every single time for every patch revision, immediately before you send your patches out. We value applicants that learn fast enough to avoid making the same mistakes twice. It's a good practice to keep a log of improvements people have suggested for your previous patches, and double check that before submitting a new patch or patchset. |
| Line 119: | Line 41: |
| = Play with some git basics = | We look for applicants that can revise patches based on feedback from mentors. If you get feedback on a patch, change the code and send a revised patch. Don't just go onto the next patch. We value applicants that consistently send or revise patches every day, or every other day, rather than being sporatic about when patches are sent. Our best interns made the application process a part of their daily routine: prepare a patchset early in the day, go about their lives, and revise the patchset based on feedback received later in the day. Rinse and repeat. |
| Line 121: | Line 43: |
| 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. | We also value clear, concise communication. If you have a setup issue, tell us the exact failure mode, how to reproduce the failure, and what you've done to try and trouble shoot the failure. Please ensure that when you ask a question on IRC, you remain connected to the channel until someone answers your question. If no one answers in a couple hours, send the question to the mailing list. |
| Line 123: | Line 45: |
| 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. | We look for applicants that have a knack for seeking documentation and resources their own, while still knowing when to ask questions. If you have been stuck on a problem for more than a day, seek help! We love to see applicants ask questions on IRC and the mailing list, and we especially appreciate applicants that help each other out. Helping out someone who is struggling means you get to share your knowledge, and the act of writing down what you know will solidify that knowledge in your mind. It also shows the OPW mentors that you're learning new skills, and are willing to share that knowledge. Bonus points if you make a kernelnewbies account (email Sarah Sharp for edit privileges) and correct or add knowledge to this wiki. |
| Line 125: | Line 47: |
| 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 }}} |
During the intern selection process, mentors will often already have a particular applicant in mind they want to pick. This applicant has often worked directly with the mentor, asked them questions, or sent them a detailed timeline for their project. Often times one particular project is very popular, because the mentor is highly responsive on the mailing list, and applicants like working with them. In that case, that project may be the first or second choice for many of the OPW applicants. Therefore, it is important to list at least four projects you are interested in, and make sure to work on small tasks from at least 2-3 OPW mentors. |
| Line 131: | Line 49: |
| 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". | There are also a few factors outside your control that may impact whether you are selected for an OPW internship. We try to ensure that the timezone difference between mentors and interns is acceptable. If the project requires specialized hardware, and it is difficult to get packages through customs in your country, you may not be selected for that project. An OPW internship is a full-time commitment, so we cannot accept you if you're working a full-time job, or taking more than one or two classes during the internship period. If there are many very good candidates, you may not be selected to be an OPW intern this round. We encourage you to apply next round, since you'll have a head start over the other candidates. |
| Line 133: | Line 51: |
| 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 by pass 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 = TODO: * Outline of what this tutorial covers * If you run into any issues, ask on the opw irc channel, or email sarah.a.sharp at linux.intel.com * Find out which drivers you have installed (maybe plug in any USB devices on hand) * Make small change in one of the drivers (e.g. run checkpatch over them, or fix some grammer in the printks) * Or maybe pick a driver in staging and run checkpatch on it * Test your patch (may need to enable debugging) * Make a patch (link to art of patch description creation) * Send patch to kernel newbies mailing list as RFC (perhaps we need a separate mailing list?) |
Good luck, future Linux kernel developers! |
Hooray! Thanks for your interest in working on the Linux kernel. The next step is to [:OPWApply:apply] to OPW, and use this tutorial to create your first patch to the Linux kernel.
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].
Contribution Instructions
PLEASE NOTE: DO NOT SEND YOUR FIRST PATCH TO THE MAIN LINUX MAILING LISTS!
Instead, send your patch to the [https://groups.google.com/forum/#!forum/opw-kernel opw-kernel mailing list].
Resending patches
If you find a mistake in your initial patch submission, and you need to correct it, make sure to version your new patch as described in the previous section.
If your patch has not been responded to within three business days (not including weekend days), the mentors may have missed it, and you may want to resend it. Make sure to use RESEND in the subject line if the patch itself has not been changed (meaning no changes in the patch description or body). You can use the --subject-prefix argument to git format-patch to add RESEND, by running
git format-patch --subject-prefix="RESEND PATCH"
That command will create an email you can send with mutt (or your approved mail client) that will have a subject that looks like:
[RESEND PATCH] Foo: Fix these things
If your patch hasn't been responded to within a week, ping a mentor (or sarahsharp) on the IRC channel. Do not ping mentors immediately after sending patches. We know you're excited/worried about submitting your first patch, but mentors need to take time to properly respond and review patches.
Tips for Applying to be an OPW Kernel intern
After you complete the first patch tutorial and get a patch accepted into the Linux kernel, you may wonder what to do next. We recommend getting 3-5 single cleanup patches accepted, and then moving on to create a patchset with several different cleanups for the same staging driver. Please limit your patchsets to no more than 10 patches, unless you've been told to break the patchset down further. Please try to limit your patches to no more than 100 to 200 lines total, to avoid mentors getting patch review fatigue. If you're bored and losing focus when you're tediously creating the patch, it's highly likely the mentors will get tired while reviewing it. 
Once you've gotten 3-5 patchsets accepted, move onto exploring more complex tools, like sparse and coccinelle. Try to tackle some code refactoring, or take on a [:OPWTasks:small task] that a mentor has recommended for their project. Mentors are more likely to pick you for their project if they see you tackling tasks from that project or asking questions about that project.
Tackling increasingly complex patches mean the OPW mentors will get a sense of how good a C programmer you are. It's very easy for beginner C programmers to do some of the more simple checkpatch cleanups, but it takes more skill to complete our mentor's small tasks, or sparse and coccinelle patches. You may find yourself trying to understand advanced C topics, such as [http://stackoverflow.com/questions/1665250/why-declare-a-variable-or-function-static-in-c/1665270#1665270 when to declare a function static]. If you are attempting silence a checkpatch.pl warning, and you don't understand what the warning message means, please ask on IRC or the mailing list before blindly trying to silence the warning. We value applicants that know when they need help, and we are happy to share knowledge and expand your skillset.
Please remember that we value consistently clean patches, so make sure to compile your code and ensure that no checkpatch errors or build warnings were added. Do this every single time for every patch revision, immediately before you send your patches out. We value applicants that learn fast enough to avoid making the same mistakes twice. It's a good practice to keep a log of improvements people have suggested for your previous patches, and double check that before submitting a new patch or patchset.
We look for applicants that can revise patches based on feedback from mentors. If you get feedback on a patch, change the code and send a revised patch. Don't just go onto the next patch. We value applicants that consistently send or revise patches every day, or every other day, rather than being sporatic about when patches are sent. Our best interns made the application process a part of their daily routine: prepare a patchset early in the day, go about their lives, and revise the patchset based on feedback received later in the day. Rinse and repeat.
We also value clear, concise communication. If you have a setup issue, tell us the exact failure mode, how to reproduce the failure, and what you've done to try and trouble shoot the failure. Please ensure that when you ask a question on IRC, you remain connected to the channel until someone answers your question. If no one answers in a couple hours, send the question to the mailing list.
We look for applicants that have a knack for seeking documentation and resources their own, while still knowing when to ask questions. If you have been stuck on a problem for more than a day, seek help! We love to see applicants ask questions on IRC and the mailing list, and we especially appreciate applicants that help each other out. Helping out someone who is struggling means you get to share your knowledge, and the act of writing down what you know will solidify that knowledge in your mind. It also shows the OPW mentors that you're learning new skills, and are willing to share that knowledge. Bonus points if you make a kernelnewbies account (email Sarah Sharp for edit privileges) and correct or add knowledge to this wiki.
During the intern selection process, mentors will often already have a particular applicant in mind they want to pick. This applicant has often worked directly with the mentor, asked them questions, or sent them a detailed timeline for their project. Often times one particular project is very popular, because the mentor is highly responsive on the mailing list, and applicants like working with them. In that case, that project may be the first or second choice for many of the OPW applicants. Therefore, it is important to list at least four projects you are interested in, and make sure to work on small tasks from at least 2-3 OPW mentors.
There are also a few factors outside your control that may impact whether you are selected for an OPW internship. We try to ensure that the timezone difference between mentors and interns is acceptable. If the project requires specialized hardware, and it is difficult to get packages through customs in your country, you may not be selected for that project. An OPW internship is a full-time commitment, so we cannot accept you if you're working a full-time job, or taking more than one or two classes during the internship period. If there are many very good candidates, you may not be selected to be an OPW intern this round. We encourage you to apply next round, since you'll have a head start over the other candidates.
Good luck, future Linux kernel developers!