| <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" |
| "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> |
| <html lang="en" xmlns="http://www.w3.org/1999/xhtml" xml:lang="en"> |
| <head> |
| <meta name="copyright" content= |
| "Copyright (c) IBM Corporation and others 2000, 2011. This page is made available under license. For full details see the LEGAL in the documentation book that contains this page." /> |
| <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> |
| <meta http-equiv="Content-Style-Type" content="text/css" /> |
| <link rel="STYLESHEET" href="../book.css" charset="ISO-8859-1" type="text/css" /> |
| <title>Setting the Java build path</title> |
| <link rel="stylesheet" type="text/css" href="../book.css" /> |
| </head> |
| <body> |
| <h2>Setting the Java build path</h2> |
| <p>This section describes how to set the Java build path. The build path is the classpath |
| that is used for building a Java project (<b><a href= |
| "../reference/api/org/eclipse/jdt/core/IJavaProject.html">IJavaProject</a></b>).</p> |
| |
| <p>A classpath is simply an array of classpath entries (<b><a href= |
| "../reference/api/org/eclipse/jdt/core/IClasspathEntry.html">IClasspathEntry</a></b>) that describe |
| the types that are available. The types can appear in source or binary form and the ordering |
| of the entries on the path defines the lookup order for resolving types during a build.</p> |
| <p>The Java build path is reflected in the structure of a Java project element. You can query |
| a project for its package fragment roots (<b><a href= |
| "../reference/api/org/eclipse/jdt/core/IPackageFragmentRoot.html">IPackageFragmentRoot</a></b>). |
| Each classpath entry maps to one or more package fragment roots, each of which further contains a |
| set of package fragments.</p> |
| <p>This discussion of the build path does not involve the Java runtime path, which can be defined |
| separately from the build path. (See <b><a href="../guide/jdt_api_run.htm">Running Java |
| code</a></b> for a discussion of the runtime classpath.)</p> |
| |
| <h3>Changing the build path</h3> |
| <p>You can programmatically change a project's build path using <b><a href= |
| "../reference/api/org/eclipse/jdt/core/IJavaProject.html#setRawClasspath(org.eclipse.jdt.core.IClasspathEntry[],%20org.eclipse.core.runtime.IProgressMonitor)"> |
| setRawClasspath</a></b> on the corresponding project's Java element. The following code sets |
| the classpath for a project resource:</p> |
| <pre class="color1"> |
| |
| IProject project = ... // get some project resource |
| IJavaProject javaProject = JavaCore.create(project); |
| IClasspathEntry[] newClasspath = ...; |
| javaProject.setRawClasspath(newClasspath, someProgressMonitor); |
| |
| </pre> |
| <p>(Note: The use of the term "raw" classpath is used to emphasize the fact that any |
| variables used to describe entry locations have not been resolved.)</p> |
| |
| <p>The Java build path is persisted into a file named '.classpath' in the project's file |
| structure. The purpose of this file is to provide a way to share Java build path settings |
| with others through some source code repository. In particular, this file should not be manually |
| edited, since it may get corrupted.</p> |
| <h3>Classpath entries</h3> |
| <p>Classpath entries can be defined using factory methods defined on <b><a href= |
| "../reference/api/org/eclipse/jdt/core/JavaCore.html">JavaCore</a></b>. Classpath entries can |
| reference any of the following:</p> |
| <ul> |
| <li><b>a source folder</b> - a folder containing source compilation units organized under their |
| corresponding package directory structure. 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 <b><a href= |
| "../reference/api/org/eclipse/jdt/core/JavaCore.html#newSourceEntry(org.eclipse.core.runtime.IPath)"> |
| |
| newSourceEntry</a></b>. Inside a given source folder, each compilation unit is expected to be |
| nested in the appropriate folder structure according to its package statement. For example, |
| compilation unit 'X.java' in package 'p1' must be located inside sub-folder 'p1' of a source |
| folder. 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 class files should |
| be placed. If none is specified, then class files will be placed in the containing project's |
| output location (see <b><a href= |
| "../reference/api/org/eclipse/jdt/core/IJavaProject.html#setOutputLocation(org.eclipse.core.runtime.IPath,%20org.eclipse.core.runtime.IProgressMonitor)"> |
| IJavaProject.setOutputLocation</a></b>). |
| <p>The following is an example classpath entry that denotes the source folder 'src' of project |
| 'MyProject':</p> |
| <pre class="color1"> |
| IClasspathEntry srcEntry = JavaCore.newSourceEntry(new Path("/MyProject/src")); |
| </pre></li> |
| <li><b>a binary library</b> - either a class file folder (contained inside or outside the |
| workspace) or a class file archive file (contained inside or outside the workspace). Archive |
| libraries can have attached source archives, which are extracted when asking a class file element |
| for its source (<b><a href= |
| "../reference/api/org/eclipse/jdt/core/ISourceReference.html#getSource()">getSource</a></b>). The |
| factory method for libraries is <b><a href= |
| "../reference/api/org/eclipse/jdt/core/JavaCore.html#newLibraryEntry(org.eclipse.core.runtime.IPath,%20org.eclipse.core.runtime.IPath,%20org.eclipse.core.runtime.IPath,%20boolean)"> |
| |
| newLibraryEntry</a></b>. |
| <p>The following is an example classpath entry that denotes the class file folder 'lib' of |
| 'MyProject':</p> |
| <pre class="color1"> |
| |
| IClasspathEntry libEntry = JavaCore.newLibraryEntry( |
| new Path("/MyProject/lib"), |
| null, // no source |
| null, // no source |
| false); // not exported |
| |
| </pre> |
| <p>The following classpath entry has a source attachment:</p> |
| <pre class="color1"> |
| |
| IClasspathEntry libEntry = JavaCore.newLibraryEntry( |
| new Path("d:/lib/foo.jar"), // library location |
| new Path("d:/lib/foo_src.zip"), // source archive location |
| new Path("src"), // source archive root path |
| true); // exported |
| |
| </pre> |
| <p>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.</p> |
| <br /></li> |
| <li><b>a prerequisite project</b> - another Java project. A prerequisite project always |
| contributes its source folders to dependent projects. It can also optionally contribute any of its |
| classpath 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 classpath entries tagged as such. This allows prerequisite |
| projects to better hide their own structure changes. For example, a given project may choose |
| to switch from using a source folder to exporting a library. This can be done without |
| requiring its dependent projects to change their classpath. The factory method for a project |
| prerequisite is <b><a href= |
| "../reference/api/org/eclipse/jdt/core/JavaCore.html#newProjectEntry(org.eclipse.core.runtime.IPath,%20boolean)"> |
| newProjectEntry</a></b>. |
| |
| <p>The following classpath entry denotes a prerequisite project 'MyFramework'.</p> |
| <pre class="color1"> |
| |
| IClasspathEntry prjEntry = JavaCore.newProjectEntry(new Path("/MyFramework"), true); // exported |
| |
| </pre></li> |
| <li><b>an indirect reference to a project or library, using some classpath variable</b> - The |
| location of projects or libraries can be dynamically resolved relative to a classpath variable, |
| which is specified as the first segment of the entry path. The remainder of the entry path is then |
| appended to the resolved variable path. The factory method for a classpath variable is <b><a href= |
| "../reference/api/org/eclipse/jdt/core/JavaCore.html#newVariableEntry(org.eclipse.core.runtime.IPath,%20org.eclipse.core.runtime.IPath,%20org.eclipse.core.runtime.IPath)"> |
| newVariableEntry</a></b>. Classpath variables are global to the workspace, and can be manipulated |
| through JavaCore methods <b><a href= |
| "../reference/api/org/eclipse/jdt/core/JavaCore.html#getClasspathVariable(java.lang.String)">getClasspathVariable</a></b> |
| and <b><a href= |
| "../reference/api/org/eclipse/jdt/core/JavaCore.html#setClasspathVariable(java.lang.String,%20org.eclipse.core.runtime.IPath,%20org.eclipse.core.runtime.IProgressMonitor)"> |
| |
| setClasspathVariable</a></b>. |
| <p>It is possible to register an automatic <b><a href= |
| "../reference/api/org/eclipse/jdt/core/ClasspathVariableInitializer.html">classpath variable |
| initializer</a></b> which is invoked through the extension point <b><a href= |
| "../reference/extension-points/org_eclipse_jdt_core_classpathVariableInitializer.html">org.eclipse.jdt.core.classpathVariableInitializer</a></b> |
| when the workspace is started.</p> |
| <p>The following classpath entry denotes a library whose location is kept in the variable |
| 'HOME'. The source attachment is defined using the variables 'SRC_HOME' and 'SRC_ROOT' |
| :</p> |
| |
| <pre class="color1"> |
| |
| IClasspathEntry varEntry = JavaCore.newVariableEntry( |
| new Path("HOME/foo.jar"), // library location |
| new Path("SRC_HOME/foo_src.zip"), // source archive location |
| new Path("SRC_ROOT"), // source archive root path |
| true); // exported |
| JavaCore.setClasspathVariable("HOME", new Path("d:/myInstall"), null); // no progress monitor |
| |
| </pre></li> |
| <li><b>entry denoting a classpath container</b> - an indirect reference to a structured set of |
| project or libraries. Classpath containers are used to refer to a set of classpath entries that |
| describe a complex library structure. Like classpath variables, classpath containers |
| <b><a href= |
| "../reference/api/org/eclipse/jdt/core/IClasspathContainer.html">(IClasspathContainer)</a></b> are |
| dynamically resolved. Classpath containers may be used by different projects, causing their |
| path entries to resolve to distinct values per project. They also provide meta information |
| about the library that they represent (name, kind, description of library.) The factory |
| method for a classpath variable is <b><a href= |
| "../reference/api/org/eclipse/jdt/core/JavaCore.html#newContainerEntry(org.eclipse.core.runtime.IPath,%20boolean)"> |
| |
| newContainerEntry</a></b>. Classpath containers can be manipulated through JavaCore methods |
| <b><a href= |
| "../reference/api/org/eclipse/jdt/core/JavaCore.html#getClasspathContainer(org.eclipse.core.runtime.IPath,%20org.eclipse.jdt.core.IJavaProject)"> |
| getClasspathContainer</a></b> and <b><a href= |
| "../reference/api/org/eclipse/jdt/core/JavaCore.html#setClasspathContainer(org.eclipse.core.runtime.IPath,%20org.eclipse.jdt.core.IJavaProject[],%20org.eclipse.jdt.core.IClasspathContainer[],%20org.eclipse.core.runtime.IProgressMonitor)"> |
| setClasspathContainer</a></b>. |
| <p>It is possible to register an automatic <b><a href= |
| "../reference/api/org/eclipse/jdt/core/ClasspathContainerInitializer.html">classpath container |
| initializer</a></b> which is lazily invoked through the extension point <b><a href= |
| "../reference/extension-points/org_eclipse_jdt_core_classpathContainerInitializer.html">org.eclipse.jdt.core.classpathContainerInitializer</a></b> |
| when the container needs to be bound.</p> |
| |
| <p>The following classpath entry denotes a system class library container:</p> |
| <pre class="color1"> |
| |
| IClasspathEntry varEntry = JavaCore.newContainerEntry( |
| new Path("JDKLIB/default"), // container 'JDKLIB' + hint 'default' |
| false); // not exported |
| |
| JavaCore.setClasspathContainer( |
| new Path("JDKLIB/default"), |
| new IJavaProject[]{ myProject }, // value for 'myProject' |
| new IClasspathContainer[] { |
| new IClasspathContainer() { |
| public IClasspathEntry[] getClasspathEntries() { |
| return new IClasspathEntry[]{ |
| JavaCore.newLibraryEntry(new Path("d:/rt.jar"), null, null, false); |
| }; |
| } |
| public String getDescription() { return "Basic JDK library container"; } |
| public int getKind() { return IClasspathContainer.K_SYSTEM; } |
| public IPath getPath() { return new Path("JDKLIB/basic"); } |
| } |
| }, |
| null); |
| </pre></li> |
| </ul> |
| <h3>Exclusion patterns</h3> |
| <p>A classpath source entry may be assigned an exclusion pattern, which prevents certain resources |
| in a source folder from being visible on the classpath. Using a pattern allows specified |
| portions of the resource tree to be filtered out. Each exclusion pattern path is relative to |
| the classpath entry and uses a pattern mechanism similar to Ant. Exclusion patterns can be |
| used to specify nested source folders as long as the outer pattern excludes the inner pattern.</p> |
| |
| <p>See <b><a href= |
| "../reference/api/org/eclipse/jdt/core/IClasspathEntry.html#getExclusionPatterns()">getExclusionPatterns</a></b> |
| for more detail on exclusion patterns.</p> |
| <p>The Java project API <b><a href= |
| "../reference/api/org/eclipse/jdt/core/IJavaProject.html#isOnClasspath(org.eclipse.core.resources.IResource)"> |
| isOnClasspath</a></b> checks both inclusion and exclusion patterns before determining whether a |
| particular resource is on the classpath.</p> |
| <p>Remarks:</p> |
| <ul> |
| <li>Exclusion patterns have higher precedence than inclusion patterns; in other words, exclusion |
| patterns can remove files from the ones that are to be included, not the other way around.</li> |
| <li>A nested source folder excluded from build path can be set as an output location. The following |
| is an example classpath entry that denotes the source folder 'src' of project 'MyProject' with an |
| excluded nested source folder used as an output location: |
| |
| <pre class="color1"> |
| |
| IPath sourceFolder = new Path("/MyProject/src"); |
| IPath outputLocation = sourceFolder.append("bin"); |
| IClasspathEntry srcEntry = JavaCore.newSourceEntry( |
| sourceFolder, // source folder location |
| new Path[] { outputLocation }, // excluded nested folder |
| outputLocation); // output location |
| |
| </pre></li> |
| </ul> |
| <h3>Inclusion patterns</h3> |
| <p>A classpath source entry may also be assigned an inclusion pattern, which explicitly defines |
| resources to be visible on the classpath. When no inclusion patterns are specified, the |
| source entry includes all relevant files in the resource tree rooted at this source entry's path. |
| Specifying one or more inclusion patterns means that only the specified portions of the resource |
| tree are to be included. Each path specified must be a relative path, and will be interpreted |
| relative to this source entry's path. File patterns are case-sensitive. A file matched by one or |
| more of these patterns is included in the corresponding package fragment root unless it is excluded |
| by one or more of this entry's exclusion patterns.</p> |
| <p>See <b><a href= |
| "../reference/api/org/eclipse/jdt/core/IClasspathEntry.html#getExclusionPatterns()">getExclusionPatterns</a></b> |
| for a discussion of the syntax and semantics of path patterns. The absence of any inclusion |
| patterns is semantically equivalent to the explicit inclusion pattern <code>**</code>.</p> |
| |
| <p>The Java project API <b><a href= |
| "../reference/api/org/eclipse/jdt/core/IJavaProject.html#isOnClasspath(org.eclipse.core.resources.IResource)"> |
| isOnClasspath</a></b> checks both inclusion and exclusion patterns before determining whether a |
| particular resource is on the classpath.</p> |
| <p>Examples:</p> |
| <ul> |
| <li>The inclusion pattern <code>src/**</code> by itself includes all files under a root folder |
| named <code>src</code>.</li> |
| <li>The inclusion patterns <code>src/**</code> and <code>tests/**</code> includes all files under |
| the root folders named <code>src</code> and <code>tests</code>.</li> |
| |
| <li>The inclusion pattern <code>src/**</code> together with the exclusion pattern |
| <code>src/**/Foo.java</code> includes all files under a root folder named <code>src</code> except |
| for ones named <code>Foo.java</code>.</li> |
| </ul> |
| <h2>Classpath resolution</h2> |
| Since classpath variables and containers allow you to define dynamically bound classpath entries, |
| the classpath API distinguishes between a raw and a resolved classpath. The raw |
| classpath is the one originally set on the Java project using <b><a href= |
| "../reference/api/org/eclipse/jdt/core/IJavaProject.html#setRawClasspath(org.eclipse.jdt.core.IClasspathEntry[],%20org.eclipse.core.runtime.IProgressMonitor)"> |
| |
| setRawClasspath</a></b>, and can be further queried by asking the project for <b><a href= |
| "../reference/api/org/eclipse/jdt/core/IJavaProject.html#getRawClasspath()">getRawClasspath</a></b>. |
| The resolved classpath can be queried using <b><a href= |
| "../reference/api/org/eclipse/jdt/core/IJavaProject.html#getResolvedClasspath(boolean)">getResolvedClasspath</a></b>. |
| This operation triggers initialization of any variables and containers necessary to resolve the |
| classpath. Many Java Model operations implicitly cause the Java build path to be |
| resolved. For example, computing a project's package fragment roots requires the build path |
| to be resolved. |
| </body> |
| </html> |
