Skip to main content
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index] [List Home]
[cdt-core-dev] Draft of core model ICPathEntry mechanism 
Bonjour

	This is the first draft describing a proposed scheme for the CDT core model
to handle paths information like; include paths, macros, source paths, libraries,
third party contributions via the container extension point etc ..

The document is in cdt-core-dev and attach to the email.



<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
 <title>Setting the CDT path entries</title>
 <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
 <LINK rel="stylesheet" HREF="http://dev.eclipse.org/viewcvs/index.cgi/%7Echeckout%7E/cdt-home/cdt.css?cvsroot=Tools_Project"; type="text/css">
</head>

<body>


<!-- Document Header -->
<TABLE cellPadding=2 width="100%" border=0>
 <TBODY>
  <TR>
   <TD align=left width="72%">
    <FONT class=indextop>CDT Core</FONT><BR>
    <FONT class=indexsub>ICPathEntry</FONT>
   </TD>
   <TD width="28%"><IMG height=86 src="http://dev.eclipse.org/images/Idea.jpg"; width=120 alt=""></TD>
  </TR>
 </TBODY>
</TABLE>
<table>
 <tbody>
  <tr><td>Author</td><td>         : <a href="mailto:alain@xxxxxxx";>Alain Magloire</a></td></tr>
  <tr><td>Author</td><td>         : <a href="mailto:dinglis@xxxxxxx";>Dave Inglis</a></td></tr>
  <tr><td>Revision Date</td><td>  : 11/24/2003 - Version: 0.0.1</td></tr>
  <tr><td>Change History</td><td> : 0.0.1 - Document Creation</td></tr>
 </tbody>
</table>
<br>
<!-- End of Document Header -->

<!-- Table of Contents -->
<div class=section>Table of Contents</div>
<br>
<div class=indent><a href="#settings">1. Setting the path entries</a> </div>
<div class=indent><a href="#ICPathEntry">2. ICPathEntry</a> </div>
<div class=indent><a href="#scenario_1">3. Scenario 1</a> </div>
<div class=indent><a href="#scenario_2">4. Scenario 2</a> </div>
<div class=indent><a href="#scenario_3">5. Scenario 3</a> </div>
<div class=indent><a href="#references"> 6. References</a> </div>
<br><br>
<!-- End of Table of Contents -->



<div class=section><a name="settings"> 1. Setting the entries</a></div>

<p>

Different types of information must be provided to the core model, for example
include directories, builtin macros.  To help, the core model provides a scheme to
save and extract this information. A number of factory methods are provided from the core model.
<ul>
<li> Source code in the project.
<li> Macros for a current project/resource.
<li> Include paths for a project/resource.
<li> Libraries in the project, in another project, or in the external file system.
<li> A required project.
<li> A named container, it provides a way to indirectly reference a set of ICPathEntry entries.
</ul>

<div class=section><a name="ICPathEntry"> 2. ICPathEntry</a></div>
<p>

the entries can programmatically be change for a project using setRawCPathEntry() on
the corresponding project.  The following code sets the ICPathEntry for a project:

<pre>
	IProject project = ... // get some project resource
	ICPathEntry[] entries = ...;
	CoreModel.getDefault().setRawCPathEntry(project, entries, someProgressMonitor);
Or:
	IProject project = ... // get some project resource
	ICProject cProject = CoreModel.getDefault().create(project);
	ICPathEntry[] entries = ...;
	cProject.setRawCPathEntry(entries, someProgressMonitor);
</pre>
	

(Note:  The use of the term "raw" is used to emphasize the fact that any
 variables or container used to describe entry locations have not been resolved.)

<h3>CPathEntry entries</h3>
<p>

The CDT entries are persisted into a file named ".cdtproject" in the project's
file structure.  The purpose of this file is to provide a way to share CDT
settings with others through some repository.

ICPathEntry[] entries can be defined using factory methods defined on CoreModel:

<ul> 
<li> <b>a source folder</b> - a folder containing source translation units.
Source folders are used to better structure source files in large projects, and may
only be referenced within the containing project. The corresponding factory
method is newSourceEntry.  It is possible to use multiple source folders, as
long as they don't overlap.  A source folder may be assigned its own output
location which determines where generated object files should be placed.
If none is specified, then object files will be placed in the containing
project's output location (see ICProject.setOutputLocation).

The following is an example ICPathEntry entry that denotes the source folder
'src' of project 'MyProject':

<pre>
	ICPathEntry srcEntry = CoreModel.newSourceEntry(new Path("/MyProject/src");
</pre>

<li><b>a binary library</b> - either a binary file folder (contained inside the
workspace) or a archive file (contained inside or outside the workspace).
Archive libraries can have attached source archives, which are extracted when
asking a file for its source (getSource). The factory method for libraries is
newLibraryEntry.

<pre>
  ICPathEntry libEntry = CoreModel.newLibraryEntry(new Path("/MyProject/lib"), 
    null, //no source
    null, //no source
    false); //not exported
	
  ICPathEntry libEntry = CoreModel.newLibraryEntry(
    new Path("/usr/local/lib/libfoo.a"), // library location
    new Path("/home/alain/lib/foo_src.zip"), //source archive location
    new Path("src"), //source archive root path
    true); //exported
	
</pre>
 The source archive root path describes the location of the root within the source
archive.  If set to null, the root of the archive will be inferred dynamically.

<li><b>a macro</b> - defined on a project, folder or file

<pre>
  ICPathEntry prjEntry = CoreModel.newMacroEntry(
      new Path("src/foo.c"), // applied only to resource foo.c
      "NDEBUG"),
      "0"),
      false); //exported

    * An include directory 

  ICPathEntry prjEntry = CoreModel.newIncludeEntry(
      new Path("src"), // 
      new Path("/usr/local/include"), // the path
      false, // Not an system include.
      false); //exported
</pre>

<li><b>a prerequisite project - another C/C++ project</b>
A prerequisite project contributes any of its ICPathEntry entries which are tagged as exported
(see factory methods supporting the extra boolean argument 'isExported'). This
means that in addition to contributing its source to its dependents, a project
will also export all entries tagged as such.  This allows prerequisite projects to
better hide their own structure changes.

<pre>
  ICPathEntry prjEntry = CoreModel.newProjectEntry(
      new Path("/MyFramework"),
      true); //exported
	
</pre>

<li> <b>an entry denoting a container</b> - an indirect reference to a structured set of project, libraries include paths or macros.
Containers are used to refer to a set of entries that describe a complex structure, containers (ICPathContainer) are
dynamically resolved.  Containers may be used by different projects, causing them their path
entries to resolve to distinct values per project.  They also provide meta
information about the path that they represent (name, kind, description of
library.).  Containers can be manipulated through CoreModel methods
getCPathContainer and setCPathContainer. 

<pre>
  ICPathEntry contEntry = CoreModel.newContainerEntry(
    new Path("com.qnx.tools.ide.qde/6.2"), // container "QNX" version 6.2
    false); //not exported
	                             
  CoreModel.getDefault().setCPathContainer(
    new Path("com.qnx.tools.ide.qde/6.2"), 
    new IProject[]{ myProject }, // value for 'myProject'
    new ICPathEntryContainer[] {
        new ICPathEntryContainer() {
            public ICPathEntry[] getCPathEntries() {
                return new ICPathEntry[]{ 
                   CoreModel.newIncludeEntry(new Path("/usr/qnx-6.2/usr/include"), null, null, false),
                   CoreModel.newLibaryEntry(new Path("/usr/qnx-6.2/lib/libc.so.2"), null, null, false),
                }; 
            }
            public String getDescription() { return "QNX Version 6.2"; }
            public int getKind() { return ICPathEntryContainer.K_SYSTEM; }
            public IPath getPath() { return new Path("com.qnx.tools.ide.qde/6.2"); }
          }
        }, 
    null);

<pre>
</ul>

<div class=section><a name="scenario_1"> 3. Scenario 1</a></div>
<h3>
Managed builder
</h3>
<p>

The ManagedBuilder provides its own persistency so it will use a container to set
an indirect reference.  In the ManagedBuilder wizards:

<pre>
    ICPathEntry entry =
      CoreModel.newContainerEntry(new Path("org.eclipse.cdt.managedbuilder.MANAGED_CONTAINER"), true);

    public class ManagedBuilderCPathEntryContainer implements ICPathEntryContainer[] {
        public ICPathEntry[] getCPathEntries() {
            // return the information saved by the ManagedBuilder.
        }
        public String getDescription() {
            return "CDT Managed Builder";
        }
        public int getKind() { return ICPathEntryContainer.K_SYSTEM; }
        public IPath getPath() { return new Path("org.eclipse.cdt.managedbuilder.MANAGED_CONTAINER"); }
    }
</pre>

Retrieving the information

<pre>
IIncludeEntry[] CoreModel.getDefault().getIncludePaths(IResource resource);
IMacroEntry[] CoreModel.getDefault().getMacroPaths(IResource res);
....
</pre>

<div class=section><a name="scenario_2"> 4. Scenario 2</a></div>
<h3>
Std Make builder
</h3>
<p>
     The standard make does not provide any persistency or any parsing so the
information the information would be obtained by the user through a common UI block,
allowing input of macros, source paths, include paths, libraries and contributed containers.  

<div class=section><a name="scenario_3"> 5. Scenario 3</a></div>
<h3>
Third party libraries integration
</h3>
<p>
 
  The compagny MailSort inc. has a library that they want to make available to CDT user
and to do this they ship a plugin with the necessary library and headers:
<pre>
     mailsorting/
                 lib/libmailsorting.a
                 include/libmailsorting.h
                 src/mailsorting_src.zip
                 .cdtproject
</pre>

  An excerpt of the the ".cdtproject" would look something like this:
   
<pre>
  &lt;?xml version="1.0" encoding="UTF-8"?&gt;
  &lt;cdtproject id="com.foobar.mailsorting"&gt;
  ...
    &lt;cpathentry exported="true" kind="lib" path="lib/libmaisorting.a" sourcepath="src/mailsorting_src.zip"/&gt;
    &lt;cpathentry kind="inc" path="include"/&gt;
  ...
  &lt;/cdtproject&gt;
</pre>

</body>
</html>

Back to the top