Pkg-config support for Eclipse CDT documentation
- 1. Petri Tuononen 12/08/2011 Google Summer of Code 2011 Pkg-config support for Eclipse CDT Introduction The work discussed here is a plug-in for Eclipse CDT which forms a bridge between pkg-config utility and Eclipse CDT. The aim is to provide a user-friendly interface and automation of compiler and linker flag configuration. Basic requirements • Pkg-config utility • Eclipse 3.7 or newer • CDT 8.0 (C/C++ Development Tooling) or newer • Windows/Linux • MinGW or Cygwin for Windows users Basic functionality of the plug-in PkgConfigUtil class calls pkg-config utility via command line process in multiple occasions. The callback is then parsed and separated to contain information in suitable format for CDT's Managed Build System. Processed information is then visible on the properties page (package names and descriptions) and compiler flags that belong to checked packages are automatically added to MBS. Indexer is then rebuilt and unresolved inclusions related to the checked packages should disappear. After indexer shows no errors the project is ready to be build. The pkg-config utility process is first triggered when the user opens the pkg- config property tab. The plug-in will then be able to show packages and their descriptions in alphabetical order that were found by the pkg-config utility. The second time the pkg-config utility process is triggered is when the user checks one or more packages. The pkg-config utility will produce an output of flags that are necessary in order to build a given package. That information is then parsed into a suitable format and delivered to MBS (compiler and linker tools). 1
- 2. Petri Tuononen 12/08/2011 Google Summer of Code 2011 Figure 1. Illustrates the main workflow of the plug-in. Basic information Preference page Pkg-config preference page can be used to change environment variables for PKG_CONFIG_PATH and PKG_CONFIG_LIBDIR. This feature is mainly to make the plug-in a bit more user-friendly by allowing change of the most common and useful pkg-config specific environment variables via Eclipse IDE. These environment variables are only visible to Eclipse. One shall remember that the pkg-config path cannot contain white spaces (a feature of pkg-config utility). One can find pkg-config preference page by navigating Window → Preferences → Pkg-config. Figure 2. Pkg-config preference page. 2
- 3. Petri Tuononen 12/08/2011 Google Summer of Code 2011 Property tab Packages and their descriptions are listed on the pkg-config property tab. One can find project specific pkg-config property tab by navigating Properties → C/C++ Build → Settings → Pkg-config. Figure 3. Pkg-config property tab Tool settings The following pictures illustrate how includes, libraries and other flags get added to corresponding compiler and linker tools after a package is checked in pkg- config property tab. 3
- 4. Petri Tuononen 12/08/2011 Google Summer of Code 2011 Figure 4. Include flags added to a compiler. Figure 5. Library files and paths added to a linker. 4
- 5. Petri Tuononen 12/08/2011 Google Summer of Code 2011 Figure 6. Other flags added to a compiler. Templates Automatically generated template projects for GTK+ and gtkmm are available. These templates include sample code for Hello World button. Currently the necessary packages are not checked by default but work is in progress to support that in future revisions. 5
- 6. Petri Tuononen 12/08/2011 Google Summer of Code 2011 Figure 7. Template project wizards for gtk+ and gtkmm projects. Technical implementation Preference page The preference page consists of one list editor and one field editor. They both accept directories only. The list editor is modified so that PkgConfigListEditor extends org.eclipse.jface.preference.ListEditor and PkgConfigPathListEditor extends PkgConfigListEditor. This way we can customize getNewInputObject(), removePressed(), remove unneeded buttons, edit list control etc. LibDirFieldEditor is extended from StringButtonFieldEditor. Preference store is used to load and store values added to the list or field editor. PreferencePage class takes care that environment variables are created and set from the values stored in the preference store when the user presses OK button in the preferences dialog. 6
- 7. Petri Tuononen 12/08/2011 Google Summer of Code 2011 Figure 8. Preferences package class diagram. Property tab Pkg-config property tab constructs around CheckboxTableViewer. CreateControls() method contains all layout specifications and components. There are also listeners that are triggered if packages are checked by clicking a checkbox next to them, double-clicking a line or selecting multiple packages and pressing the select button. Checked package states are saved into ICStorageElement and initialized similarly. In the end updateData() is called which updates pkg-config specific external setting provider and finally index is rebuilt. The packages and descriptions have their own columns in the table viewer. DataModel class was created to unite packages and descriptions. DataModelProvider class creates an arraylist of DataModels containing packages 7
- 8. Petri Tuononen 12/08/2011 Google Summer of Code 2011 (and descriptions belonging to them) in alphabetical order. DataModelProvider is then set as an input for table viewer. When creating columns for the table viewer DataModel arraylist is processed so that a package from the DataModel is inserted into a first column and description to a second column. This continues until no DataModel objects are left. Figure 9. Properties package class diagram. External Setting Provider First of all an External Setting Provider must be identified by an ID in order to associate a unique External Setting Provider for the plug-in. Also name for the storage is given and in this case the storage contains the checked package names. When updateData() is called in the PkgConfigPropertyTab an external setting provider is updated for ICProjectDescription. At the same time PkgConfigExternalSettingProvider's getSettings() method is triggered automatically. PkgConfigExternalSettingProvider is responsible for returning includes, libraries and other flags for a given project in a right format. 8
- 9. Petri Tuononen 12/08/2011 Google Summer of Code 2011 Figure 10. PkgConfigExternalSettingProvider class diagram. Pkg-config utility – Eclipse bridge PkgConfigUtil is basically a class where multiple command line interpreter commands are formed using ProcessBuilder. Process is then started and an output is returned and read by InputStreamReader. Using similar approach we can get all necessary information from the pkg-config utility by modifying command and package names. Figure 11. PkgConfigUtil class diagram. Parser After the pkg-config utility has returned it's result it is not in a suitable format for us. The output needs to be processed so that dashes and single letters after them 9
- 10. Petri Tuononen 12/08/2011 Google Summer of Code 2011 are removed and that separate flag types are classified into homogeneous arrays containing one entry per cell. It is then easy to output them to CDT's Managed Build System (compiler and linker tools). Figure 12. Parser class diagram. Links Project website http://code.google.com/p/pkg-config-support-for-eclipse-cdt Eclipse Bugzilla entry https://bugs.eclipse.org/bugs/show_bug.cgi?id=44761 Eclipse Marketplace entry http://marketplace.eclipse.org/content/pkg-config-support-eclipse-cdt 10
- 11. Petri Tuononen 12/08/2011 Google Summer of Code 2011 Appendix 1. Class diagram containing all classes in pkg-config plug-in project. 11