Upstream contributing: Difference between revisions

From Lustre Wiki
Jump to navigation Jump to search
mNo edit summary
Tag: Replaced
 
(20 intermediate revisions by 2 users not shown)
Line 1: Line 1:
== Getting started ==
Lustre client code targetted for upstream kernel submission is currently being managed as part of the 'master' Lustre development branch, and submitted patches should follow the normal Lustre patch submission process.  Once all issues in the Lustre code that are known to be blocking upstream submission have been addressed, then the client will be resubmitted to the upstream kernel.
 
The upstream Lustre client code is currently hosted in the staging area of the linux kernel tree. All current efforts for the upstream client are done with the git staging repo and that work then goes into Linus's tree during the merge window shortly after a Linux kernel release is cut. The git staging tree has several branches but the one of interest for contributing is the staging-testing branch. Any patches created against the other branches will likely not even apply correctly so please ensure  you are working and testing with the staging-testing branch. Before we can start developing patches we need to obtain the source repo, build and install the Lustre enabled kernel with the proper utilities. The steps to getting started are listed below. In my example I named by git repo top directory lustre-upstream but you can name it whatever you want.
 
cd your-work-directory<br>
git clone git://git.kernel.org/pub/scm/linux/kernel/git/gregkh/staging.git lustre-upstream<br>
cd lustre-upstream<br>
git checkout -b staging-testing origin/staging-testing<br>
 
=== Kernel configuration ===
 
With the lustre client source tree available the next step will be configuring your kernel to enable Lustre. The easiest way to configure a kernel is to run make menuconfig. If this fails it most likely is due to the missing libncurses library that is required. Running the make menuconfig will present you the top level menu. The section for Lustre is located in the Device Drivers section:
 
< > Volume Management Device Driver<br>
[*] Networking support  ---><br>
Device Drivers  ---><br>
Firmware Drivers ---><br>
 
Once in the Device Drivers menu you want to enable the Staging driver menu as shown here:
 
Virtio drivers  ---><br>
Microsoft Hyper-V guest support  ----<br>
[*] Staging drivers  ---><br>
[ ] X86 Platform Specific Device Drivers  ---><br>
 
Enable the staging driver allows you to display the options of that menu. Scroll down to the Staging drivers option and hit enter to go to the Staging menu.
In the menu you will see:
 
< >  GCT GDM724x LTE support><br>
< >  TTY over Firewire<br>
< >  Lustre networking subsystem (LNet)<br>
< >  Digi Neo and Classic PCI Products<br>
 
You want to select Lustre networking subsystem which will in turn enable several other options.
 
< >  GCT GDM724x LTE support<br>
< >  TTY over Firewire<br>
<M>  Lustre networking subsystem (LNet)<br>
 (1048576) Lustre lnet max transfer payload (default 1MB)
<M>    Lustre networking self testing<br>
<M>    LNET infiniband support<br>
<M>    Lustre file system client support<br>
(8192)    Lustre obd max ioctl buffer bytes (default 8KB)<br>   
[ ]      Enable Lustre DEBUG checks<br>
<M>      Lustre virtual block device<br>
< >  Digi Neo and Classic PCI Products<br>
< >  Xilinx FPGA firmware download module<br>
 
These default values will be enough to get you on your way to building a lustre client. Help sections are provided for all the entries to help you understand your options.
Once you have made your selections then the normal build process of make bzImage and make modules on x86 machines will produce the lustre client modules. For
other platforms or if you want to create debian or rpm packages please consult freely available documentation about kernel building on the web. Also feel free to ask
for help on the lustre-devel mailing list. Once your kernel is ready just install it as you normally would a new kernel and reboot.
 
=== Building the Lustre utilities ===
 
To use the lustre upstream client properly you will need to install the lustre utilities rpm or debian packages. First you will need to download the latest Lustre OpenSFS/Intel repository.
Like the upstream repo checkout you can name it something different than lustre-intel-branch in this example.
 
cd my-work-space<br>
git clone git://git.hpdd.intel.com/fs/lustre-release lustre-intel-branch<br>
cd lustre-intel-branch<br>
sh ./autogen.sh<br>
./configure --disable-server<br>
make rpm  -  make debs<br>
 
Once it completes you will have the debian based packages stored in the debs directory or the rpms in the top level source directory. In either case you only need the utilities package.
In the rpm case it is the lustre-'version'*.rpm and the debian package of interest is lustre-utils_*.deb. Besides the utility package the other package that could be of interest is the
lustre-tests-* package which contains an test suite used to validate Lustre to avoid potential regressions observed in the past. If you are interested in full fledge testing then I recommend
reading the [[TestingLustreCode | How to test Lustre Code]] section.
 
Once all your packages are installed you will need to setup a lustre file system. An excellent link to get the newcomer going is https://wiki.hpdd.intel.com/display/PUB/Create+and+Mount+a+Lustre+Filesystem.
As always if you have questions feel free to ask on the lustre-devel mailing and people will gladly help you.
 
== Developing for upstream client ==
 
This section goes over how to become actively involved in the upstream client work. The process of creating and sending patches is a very different from what is done for the OpenSFS/Intel branch.
We will go over the setup of sending patches as well as meeting the coding standards for acceptance.
 
=== git setup for patch submitting ===
Now that you are familiar with Lustre setup and would like to contribute the next step is too configure .gitconfig to send patches to Greg and the staging tree. I will show my .gitconfig I use for pushing patches upstream.
 
[sendemail]
:to = Greg Kroah-Hartman <[email protected]><br>
:to = Andreas Dilger <[email protected]><br>
:to = Oleg Drokin <[email protected]><br>
:cc = Linux Kernel Mailing List <linux-kernel@vger.kernel.org><br>
:cc = Lustre Development List <[email protected]><br>
[diff]  :renames = true<br>
 
Basically the .gitconfig is set to email patches to the correct people. I also add a [diff] field to handle renaming of files for when it does happen. Most users will most like never use that functionality. After you merge your patches the easiest way to prepare to send them by:
 
git format-patch -"# of patches" --cover-letter -o patch-directory/<br>
Edit your cover letter
git send-email patch-directory/
 
 
This is one approach but people that are much better at git know of ways to do the above more efficiently.
 
=== Coding Style ===

Latest revision as of 14:41, 3 April 2024

Lustre client code targetted for upstream kernel submission is currently being managed as part of the 'master' Lustre development branch, and submitted patches should follow the normal Lustre patch submission process. Once all issues in the Lustre code that are known to be blocking upstream submission have been addressed, then the client will be resubmitted to the upstream kernel.

Retrieved from "http://wiki.lustre.org/index.php?title=Upstream_contributing&oldid=4796"