Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

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

(I actually used this to set up a new workspace and found some flaws in the instructions, which I have now fixed.)
(31 intermediate revisions by 8 users not shown)
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 developed for Eclipse 3.5.1 + CDT 6.0.0.''
+
Tip: Increase heap size before starting the index for Linux Kernel. See [[FAQ_How_do_I_increase_the_heap_size_available_to_Eclipse%3F]]
  
−
#Download and install Eclipse plus the CDT.  
+
#Download and install Eclipse plus the CDT.
−
#Configure and build your kernel. This can be done before or after downloading and installing Eclipse.  
+
#Configure and build your kernel to define CONFIG_* and generate autoconf.h.
−
#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'''
−
#Click '''Finish'''  
+
#On the right side, select '''Linux GCC'''. Click '''Next'''
−
#Eclipse will start indexing the kernel source files, so double click on the little moving "activity" icon in the lower right part of the Eclipse window.
+
#Click '''Advanced settings...''' and a Properties dialog will pop up.
−
#Click the square red stop button on the indexer.
+
# 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. 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.
−
#Right click the top-level project in the '''Project Explorer''' pane on the left, and select '''Properties''' at the bottom.  
+
−
#Select '''Resource''' on the left, and then in the '''Text file encoding''' section, select '''Other''' and '''ISO-8859-1''' in the box, then click '''Apply'''
+
−
#Select '''C/C++ Build''' on the left.
+
−
#Click the '''Manage Configurations''' at the top right.
+
−
#Click '''New...'''
+
−
#Give it a name like ''Linux config'' and a similar description, and click '''OK'''  
+
−
#Select your new configuration, and click '''Set Active''' and then '''Apply'''
+
 
#Open the '''C/C++ General''' selection on the left.
 
#Open the '''C/C++ General''' selection on the left.
 +
#Click on '''Preprocessor Include Paths'''
 +
#Select '''GNU C''' in the '''Languages''' 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.
 +
#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 settings''' box.
 
#Uncheck '''Index source files not included in the build'''
 
#Uncheck '''Index source files not included in the build'''
−
#Clear out the '''Files to index up-front''' box.
+
#Click on '''Paths and Symbols''' on the left.
−
#Select '''Use active build configuration''' at the bottom, and click '''Apply'''
+
#Select the '''Includes''' tab and then select '''GNU C'''
−
#Click on '''Paths and Symbols''' on the left.  
+
#Click '''Add...'''
−
#Select the '''Includes''' tab and then select '''GNU C'''  
+
#Click '''Workspace...''' then select your kernel's {{Code|include}}, and {{Code|include/uapi}} directories
−
#Click '''Add...'''  
+
#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 '''Workspace...''' then select your kernel's {{Code|include}} directory
+
#Click the '''# Symbols''' tab
−
#Do another Add, Workspace and add {{Code|arch/}}''architecture''{{Code|/include}}, e.g., {{Code|arch/powerpc/include}}  
+
#Click '''Add...'''
−
#Click the '''# Symbols''' tab  
+
−
#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 twisty for your project.  
+
#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.
−
#Click '''OK''' on the Properties dialog.  
+
#Under '''C/C++ General''', select '''Preprocessor Include Paths, Macros etc.'''
−
#Right click on the project again and select '''Index''' then select '''Rebuild'''  
+
#Click the '''Providers''' tab and select '''CDT GCC Built-in Compiler Settings'''
−
#It will take about 20 minutes or so to complete.
+
#Uncheck '''Use global provider shared between projects
 +
#Append {{Code|-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.
 +
#Open a terminal, and type "echo -isystem $(gcc -print-file-name=include/)". Append ''the resulting output'' to the '''Command to get compiler specs''' mentioned above. If you're using a cross-toolchain to compile the kernel, use the full path of ''that'' cross GCC compiler, instead of just typing {{Code|gcc}} in the command mentioned. Rationale for this step: {{Code|-nostdinc}} already 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'' and so on, which are typically hosted by GCC under ''/usr/lib/gcc/<arch>/<version>/include''. Thus this step.
 +
#Click '''OK''' on the Properties dialog.
 +
#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.
 +
#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.
  
−
Corey Ashford [mailto:cjashfor@us.ibm.com cjashfor@us.ibm.com]
+
 
 +
Authored, and continuously updated from Linux v2.6.33 to Linux v5.1, by:
 +
 
 +
* Ahmed S. Darwish [mailto:darwish.07@gmail.com darwish.07@gmail.com]
 +
 
 +
 
 +
Based on earlier work by:
 +
 
 +
* Corey Ashford [mailto:cjashfor@us.ibm.com cjashfor@us.ibm.com]
 +
* Adam Duskett [mailto:Aduskett@gmail.com Aduskett@gmail.com]

Revision as of 05:40, 15 October 2020

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

Tip: Increase heap size before starting the index for Linux Kernel. See FAQ_How_do_I_increase_the_heap_size_available_to_Eclipse?

  1. Download and install Eclipse plus the CDT.
  2. Configure and build your kernel to define CONFIG_* and generate autoconf.h.
  3. Start up Eclipse.
  4. Click File -> New -> Project
  5. In the pop-up window, choose C/C++-> C Project. Click Next
  6. Fill in a project name like Linux v5.1
  7. Uncheck the Use default location box and type in the root directory of your kernel into the Location box.
  8. In the Project type: pane, click the Makefile project and select Empty Project
  9. On the right side, select Linux GCC. Click Next
  10. Click Advanced settings... and a Properties dialog will pop up.
  11. 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. 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.
  12. Open the C/C++ General selection on the left.
  13. Click on Preprocessor Include Paths
  14. Select GNU C in the Languages list
  15. Select CDT User Setting Entries in the Setting Entries list
  16. 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.
  17. Also add any other macros files you are using.
  18. Click on Indexer
  19. Checkmark the Enable project specific settings box.
  20. Uncheck Index source files not included in the build
  21. Click on Paths and Symbols on the left.
  22. Select the Includes tab and then select GNU C
  23. Click Add...
  24. Click Workspace... then select your kernel's include, and include/uapi directories
  25. 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)
  26. Click the # Symbols tab
  27. Click Add...
  28. Set the name to __KERNEL__
  29. Set the value to 1 and click OK
  30. Click the Source Location tab
  31. Click the plus sign (or arrow/triangle) next to your project name.
  32. Select the Filter item and click Edit Filter...
  33. 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)
  34. Click OK and OK again to dismiss that dialog.
  35. Under C/C++ General, select Preprocessor Include Paths, Macros etc.
  36. Click the Providers tab and select CDT GCC Built-in Compiler Settings
  37. Uncheck Use global provider shared between projects
  38. 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.
  39. Open a terminal, and type "echo -isystem $(gcc -print-file-name=include/)". Append the resulting output to the Command to get compiler specs mentioned above. If you're using a cross-toolchain to compile the kernel, use the full path of that cross GCC compiler, instead of just typing gcc in the command mentioned. Rationale for this step: -nostdinc already 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 and so on, which are typically hosted by GCC under /usr/lib/gcc/<arch>/<version>/include. Thus this step.
  40. Click OK on the Properties dialog.
  41. 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.
  42. Click Finish on the C Project dialog.
  43. The Project will index automatically.
  44. 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:

Retrieved from "https://wiki.eclipse.org/index.php?title=HowTo_use_the_CDT_to_navigate_Linux_kernel_source&oldid=441361"

Copyright © Eclipse Foundation, Inc. All Rights Reserved.