Skip to main content
Jump to: navigation, search

Difference between revisions of "HowTo use the CDT to navigate Linux kernel source"

(Bugfix: Like the kernel Makefile does, append '-iwithprefix include' to the compiler specs. This automates things and avoids adding certain GCC-provided headers manually.)
(Update for Eclipse 2019-03 / Linux v5.1-rc + Streamline instructions)
Line 1: Line 1:
Here are some steps that I've found to get the CDT to work well with the Linux kernel source. If you exclude some of these steps, it may still work to a large degree, but some things may not work exactly right; for example it may find the wrong include file for a C file.
 
  
Anyway, as you do these steps, I think you may understand how they assist the indexer to do a good job for the Linux kernel source.
+
''Disclaimer: These steps were last updated for Eclipse 2019‑03, CDT 9.7.0, and Linux v5.1-rc4
  
''Disclaimer: these steps were last updated for Eclipse Oxygen 4.7.2 + CDT 9.4.0, and originally developed for Eclipse 3.5.1 + CDT 6.0.0''
+
#Download and install Eclipse plus the CDT.
 
+
#Download and install Eclipse plus the CDT.  
+
 
#Configure and build your kernel to define CONFIG_* and generate autoconf.h. This can be done before or after downloading and installing Eclipse.
 
#Configure and build your kernel to define CONFIG_* and generate autoconf.h. This can be done before or after downloading and installing Eclipse.
#Ensure that you have the right kernel source (e.g. make sure you are on the right git branch).  If you check out another branch later, that's ok, but you will need to re-index the source, and that takes about 20 minutes.
+
#Ensure that you have the right kernel source (e.g. make sure you are on the right git branch).  If you check out another branch later, that's ok, but you will need to re-index the source, which can take a big amount of time.
#Start up Eclipse.  
+
#Start up Eclipse.
#Click '''File'''->'''New'''->'''C Project'''  
+
#Click '''File''' -> '''New''' -> '''Project'''
#Fill in a project name like ''my_kernel''  
+
#In the pop-up window, choose '''C/C++'''-> '''C Project'''. Click '''Next'''
#Uncheck the '''Use default location''' box and type in the root directory of your kernel into the '''Location''' box.  
+
#Fill in a project name like ''Linux v5.1''
#In the '''Project type:''' pane, click the '''Makefile project''' and select '''Empty Project'''  
+
#Uncheck the '''Use default location''' box and type in the root directory of your kernel into the '''Location''' box.
#On the right side, select '''Linux GCC'''  
+
#In the '''Project type:''' pane, click the '''Makefile project''' and select '''Empty Project'''
 +
#On the right side, select '''Linux GCC'''. Click '''Next'''
 
#Click '''Advanced settings...''' and a Properties dialog will pop up.
 
#Click '''Advanced settings...''' and a Properties dialog will pop up.
# Note: At this point, latest Eclipse versions (e.g. Oxygen) will aggressively start indexing your project, which can make Eclipse painfully slow for the rest of the configuration steps below -- especially if the desire is to only index a small relevant part of the kernel. To mitigate that, temporarily disable indexing now by opening '''C/C++ General''' section, click on '''Indexer''', click on '''Enable project-specific settings''', then unmark the '''Enable indexer''' option.
+
# Note: At this point, and starting from Eclipse Oxygen, Eclipse will aggressively start indexing your project, which can make Eclipse painfully slow for the rest of the configuration steps below -- especially if the desire is to only index a small relevant part of the kernel. To mitigate that, temporarily disable indexing now by opening '''C/C++ General''' section, click on '''Indexer''', click on '''Enable project-specific settings''', then unmark the '''Enable indexer''' option.
 
#Open the '''C/C++ General''' selection on the left.
 
#Open the '''C/C++ General''' selection on the left.
 
#Click on '''Preprocessor Include Paths'''
 
#Click on '''Preprocessor Include Paths'''
Line 21: Line 19:
 
#Select '''CDT User Setting Entries''' in the '''Setting Entries''' list
 
#Select '''CDT User Setting Entries''' in the '''Setting Entries''' list
 
#Click on '''Add...'''. Choose '''Preprocessor Macros File''' from the top left dropdown, '''Project Path''' from the top right dropdown, and enter "{{Code|include/linux/kconfig.h}}" into the '''File''' text box. Note 1: For older kernels (e.g. 4.1.12, 4.2.7, or less), selecting "{{Code|include/generated/autoconf.h}}" works better. In newer kernels, selecting {{Code|kconfig.h}} is better as this file includes <generated/autoconf.h> and also makes sure that tests such as IS_ENABLED(option) are correctly expanded by the CDT scanner. Note 2: For kernels older than 2.6.33, the location of autoconf.h is {{Code|include/linux/autoconf.h}}
 
#Click on '''Add...'''. Choose '''Preprocessor Macros File''' from the top left dropdown, '''Project Path''' from the top right dropdown, and enter "{{Code|include/linux/kconfig.h}}" into the '''File''' text box. Note 1: For older kernels (e.g. 4.1.12, 4.2.7, or less), selecting "{{Code|include/generated/autoconf.h}}" works better. In newer kernels, selecting {{Code|kconfig.h}} is better as this file includes <generated/autoconf.h> and also makes sure that tests such as IS_ENABLED(option) are correctly expanded by the CDT scanner. Note 2: For kernels older than 2.6.33, the location of autoconf.h is {{Code|include/linux/autoconf.h}}
#Also add any other macros files you are using.  
+
#Also add any other macros files you are using.
 
#Click on '''Indexer'''
 
#Click on '''Indexer'''
 
#Checkmark the '''Enable project specific setttings''' box.
 
#Checkmark the '''Enable project specific setttings''' box.
 
#Uncheck '''Index source files not included in the build'''
 
#Uncheck '''Index source files not included in the build'''
#Click on '''Paths and Symbols''' on the left.  
+
#Click on '''Paths and Symbols''' on the left.
#Select the '''Includes''' tab and then select '''GNU C'''  
+
#Select the '''Includes''' tab and then select '''GNU C'''
#Click '''Add...'''  
+
#Click '''Add...'''
#Click '''Workspace...''' then select your kernel's {{Code|include}}, and {{Code|include/uapi}} directories  
+
#Click '''Workspace...''' then select your kernel's {{Code|include}}, and {{Code|include/uapi}} directories
 
#Do another Add, Workspace and add both {{Code|arch/}}''architecture''{{Code|/include}}, and {{Code|arch/}}''architecture''{{Code|/include/uapi}} directories. e.g., {{Code|arch/powerpc/include}} and {{Code|arch/powerpc/include/uapi}} (The UAPI directories are due to the kernel's user/kernel header split covered [http://lwn.net/Articles/507794/ here] in-detail)
 
#Do another Add, Workspace and add both {{Code|arch/}}''architecture''{{Code|/include}}, and {{Code|arch/}}''architecture''{{Code|/include/uapi}} directories. e.g., {{Code|arch/powerpc/include}} and {{Code|arch/powerpc/include/uapi}} (The UAPI directories are due to the kernel's user/kernel header split covered [http://lwn.net/Articles/507794/ here] in-detail)
#Click the '''# Symbols''' tab  
+
#Click the '''# Symbols''' tab
#Click '''Add...'''  
+
#Click '''Add...'''
 
#Set the name to {{Code|__KERNEL__}}
 
#Set the name to {{Code|__KERNEL__}}
#Set the value to {{Code|1}} and click '''OK'''  
+
#Set the value to {{Code|1}} and click '''OK'''
#Click the '''Source Location''' tab  
+
#Click the '''Source Location''' tab
#Click the plus sign next to your project name.
+
#Click the plus sign (or arrow/triangle) next to your project name.
#Select the '''Filter''' item and click '''Edit Filter...'''  
+
#Select the '''Filter''' item and click '''Edit Filter...'''
#Click '''Add Multiple...''' and then select all of the {{Code|arch/*}} directories in your kernel source that will not be used (i.e. all the ones that are not for the architecture you are using)  
+
#Click '''Add Multiple...''' and then select all of the {{Code|arch/*}} directories in your kernel source that will not be used (i.e. all the ones that are not for the architecture you are using)
#Click '''OK''' and '''OK''' again to dismiss that dialog.  
+
#Click '''OK''' and '''OK''' again to dismiss that dialog.
 
#Under '''C/C++ General''', select '''Preprocessor Include Paths, Macros etc.'''
 
#Under '''C/C++ General''', select '''Preprocessor Include Paths, Macros etc.'''
 
#Click the '''Providers''' tab and select '''CDT GCC Built-in Compiler Settings'''
 
#Click the '''Providers''' tab and select '''CDT GCC Built-in Compiler Settings'''
Line 48: Line 46:
 
#Note: If you temporarily disabled indexing as earlier recommended. This is the right time to re-enable it. Under '''C/C++ General''', click on '''Indexer''', and mark the '''Enable indexer''' option.
 
#Note: If you temporarily disabled indexing as earlier recommended. This is the right time to re-enable it. Under '''C/C++ General''', click on '''Indexer''', and mark the '''Enable indexer''' option.
 
#Click '''Finish''' on the C Project dialog.
 
#Click '''Finish''' on the C Project dialog.
#The Project will index automatically.  
+
#The Project will index automatically.
 
#On a platter drive indexing will take upwards of 20 minutes to complete, on a SSD indexing will take about 5 minutes to complete.
 
#On a platter drive indexing will take upwards of 20 minutes to complete, on a SSD indexing will take about 5 minutes to complete.
  
Notes:
 
  
# Adding {{Code|include}} and {{Code|arch/}}''architecture''{{Code|/include}} only gets you a couple of the common include paths.  To fully index all of the kernel, you would have to add dozens of paths, unfortunately. For this reason, I advise against using PTP's remote indexing capability for the linux kernel, because what happens is that it will report thousands of errors in locating header files, and the process of reporting those errors over a possibly long-latency link, will cause the indexing to take many hours.
+
Authored and continuously updated, from Linux v2.6.33 to Linux v5.1, by:
# If you change any of your CONFIG_* settings, in order for Eclipse to recognize those changes, you may need to do a "build" from within Eclipse. Note, this does ''not'' mean to re-build the index; this means to build the kernel, by having Eclipse invoke make (this is normally bound to the Ctrl-B key in Eclipse). Eclipse should automatically detect changes to include/generated/autoconf.h, reread the compilation #defines it uses, and reindex.
+
 
# The background color of "Quick Context View" will be dark if the Ambiance theme in Ubuntu is selected.
+
* Ahmed S. Darwish [mailto:darwish.07@gmail.com darwish.07@gmail.com]
#For some people, Eclipse may fail to index the kernel with a out of memory error. The fix seems to be to start eclipse with the arguments: eclipse  -vmargs -Xmx650M 
+
  
Corey Ashford [mailto:cjashfor@us.ibm.com cjashfor@us.ibm.com]
 
  
Updated by Adam Duskett [mailto:Aduskett@gmail.com Aduskett@gmail.com]
+
Based on earlier work by:
  
Continuous kernel-related updates (from ''v2.6.33'' up to ''v4.15'') by Ahmed S. Darwish [mailto:darwish.07@gmail.com darwish.07@gmail.com]
+
* Corey Ashford [mailto:cjashfor@us.ibm.com cjashfor@us.ibm.com]
 +
* Adam Duskett [mailto:Aduskett@gmail.com Aduskett@gmail.com]

Revision as of 15:54, 15 April 2019

Disclaimer: These steps were last updated for Eclipse 2019‑03, CDT 9.7.0, and Linux v5.1-rc4

  1. Download and install Eclipse plus the CDT.
  2. Configure and build your kernel to define CONFIG_* and generate autoconf.h. This can be done before or after downloading and installing Eclipse.
  3. Ensure that you have the right kernel source (e.g. make sure you are on the right git branch). If you check out another branch later, that's ok, but you will need to re-index the source, which can take a big amount of time.
  4. Start up Eclipse.
  5. Click File -> New -> Project
  6. In the pop-up window, choose C/C++-> C Project. Click Next
  7. Fill in a project name like Linux v5.1
  8. Uncheck the Use default location box and type in the root directory of your kernel into the Location box.
  9. In the Project type: pane, click the Makefile project and select Empty Project
  10. On the right side, select Linux GCC. Click Next
  11. Click Advanced settings... and a Properties dialog will pop up.
  12. Note: At this point, and starting from Eclipse Oxygen, Eclipse will aggressively start indexing your project, which can make Eclipse painfully slow for the rest of the configuration steps below -- especially if the desire is to only index a small relevant part of the kernel. To mitigate that, temporarily disable indexing now by opening C/C++ General section, click on Indexer, click on Enable project-specific settings, then unmark the Enable indexer option.
  13. Open the C/C++ General selection on the left.
  14. Click on Preprocessor Include Paths
  15. Select GNU C in the Languages list
  16. Select CDT User Setting Entries in the Setting Entries list
  17. Click on Add.... Choose Preprocessor Macros File from the top left dropdown, Project Path from the top right dropdown, and enter "include/linux/kconfig.h" into the File text box. Note 1: For older kernels (e.g. 4.1.12, 4.2.7, or less), selecting "include/generated/autoconf.h" works better. In newer kernels, selecting kconfig.h is better as this file includes <generated/autoconf.h> and also makes sure that tests such as IS_ENABLED(option) are correctly expanded by the CDT scanner. Note 2: For kernels older than 2.6.33, the location of autoconf.h is include/linux/autoconf.h
  18. Also add any other macros files you are using.
  19. Click on Indexer
  20. Checkmark the Enable project specific setttings box.
  21. Uncheck Index source files not included in the build
  22. Click on Paths and Symbols on the left.
  23. Select the Includes tab and then select GNU C
  24. Click Add...
  25. Click Workspace... then select your kernel's include, and include/uapi directories
  26. Do another Add, Workspace and add both arch/architecture/include, and arch/architecture/include/uapi directories. e.g., arch/powerpc/include and arch/powerpc/include/uapi (The UAPI directories are due to the kernel's user/kernel header split covered here in-detail)
  27. Click the # Symbols tab
  28. Click Add...
  29. Set the name to __KERNEL__
  30. Set the value to 1 and click OK
  31. Click the Source Location tab
  32. Click the plus sign (or arrow/triangle) next to your project name.
  33. Select the Filter item and click Edit Filter...
  34. Click Add Multiple... and then select all of the arch/* directories in your kernel source that will not be used (i.e. all the ones that are not for the architecture you are using)
  35. Click OK and OK again to dismiss that dialog.
  36. Under C/C++ General, select Preprocessor Include Paths, Macros etc.
  37. Click the Providers tab and select CDT GCC Built-in Compiler Settings
  38. Uncheck Use global provider shared between projects
  39. Append -nostdinc to the curretly-existing Command to get compiler specs. The kernel is a free-standing environment by ISO C99 definition. That is, it does not want to be polluted, and obviously cannot work with, the "host" header files and libraries.
  40. Also append -iwithprefix include to the Command to get compiler specs above. Rationale is, -nostdinc above asked gcc to not search the standard system directories for header files. But the Linux Kernel depends on GCC-provided "freestanding environment" headers like stdarg.h, stdbool.h, etc., and which are typically hosted by GCC under /lib/gcc/<arch>/<version>/include. Thus the append.
  41. Check Allocate console in the Console View so you can see that this is working
  42. Click OK on the Properties dialog.
  43. Note: If you temporarily disabled indexing as earlier recommended. This is the right time to re-enable it. Under C/C++ General, click on Indexer, and mark the Enable indexer option.
  44. Click Finish on the C Project dialog.
  45. The Project will index automatically.
  46. On a platter drive indexing will take upwards of 20 minutes to complete, on a SSD indexing will take about 5 minutes to complete.


Authored and continuously updated, from Linux v2.6.33 to Linux v5.1, by:


Based on earlier work by:

Back to the top