<!-- saved from url=(0022)http://internet.e-mail --> | |
<!doctype html public "-//w3c//dtd html 4.0 transitional//en"> | |
<html> | |
<head> | |
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> | |
<meta name="Author" content="Eclipse Project"> | |
<title>Problem Definition - Inflexible Project Structure</title> | |
<link rel="stylesheet" href="../../default_style.css" type="text/css"> | |
</head> | |
<body bgcolor="#FFFFFF" > | |
<div align="left"> | |
<h1>Problem Definition - Inflexible Project Structure</h1> | |
</div> | |
<blockquote> | |
<p><b>Summary</b> <br> | |
Eclipse requires that the contents of each project be stored in a single directory | |
on disk. Every file and folder in that directory tree on disk must belong | |
to the project in the workspace. This restriction makes it difficult to use | |
Eclipse in conjunction with tools that have specific layout requirements for | |
their files, or with users who have legacy file base layouts that they need | |
to maintain. We would like to improve the situation for the 2.1 release of | |
Eclipse. This, the first of two documents, describes the nature of the problem; | |
possible solutions are discussed in a <a href="towards-more-flexible-projects.html"> | |
follow-on document</a>.<br> | |
<br> | |
Last Modified: 14:00 October 4, 2002</p> | |
</blockquote> | |
<p>A number of users of the Eclipse Java IDE complain that Eclipse is overly | |
constraining in where their files are located. Before looking into these | |
complaints, we quickly review how projects are structured in Eclipse (both 2.0 | |
and 1.0).</p> | |
<h2>Review: Properties of Eclipse project structure</h2> | |
<p>Here are the properties of Eclipse workspace projects:</p> | |
<ul> | |
<li>A workspace consists of any number of projects.</li> | |
<li>A workspace has a root directory on disk.</li> | |
<li>The workspace data area holds metadata, and possibly project files.</li> | |
<li>Each project has a root directory on disk.</li> | |
<li>All of a project's files are contained under the root directory.</li> | |
<li>All files under the root directory show up in the project.</li> | |
<li>A project's root directory has a default location within the workspace | |
directory, but can also be assigned to an arbitrary location on disk</li> | |
<li>A project's root directory cannot coincide or overlap with any other | |
project's.</li> | |
<li>Each project can have a team provider.</li> | |
<li>A project descriptor file (".project") appears in the root | |
directory of each project.</li> | |
</ul> | |
<p>The Java development tools uses projects in the following way:</p> | |
<ul> | |
<li>A Java project can have one or more source folders on the compile-time | |
class path.</li> | |
<li>Each source folder contains Java source files and other resources in a | |
Java package hierarchy.</li> | |
<li>A source folder must be a subdirectory under the Java project (at any | |
depth).</li> | |
<li>A source folder must not coincide with or overlap any other source folder.</li> | |
<li>A Java project has one output folder.</li> | |
<li>The output folder must be a subdirectory under the Java project (at any | |
depth) to hold generated class files (and copied resource files).</li> | |
<li>The output folder may coincide with a source folder, but may not be nested | |
within it; and conversely.</li> | |
<li>A Java project can have any number of library JARs on the compile-time | |
class path.</li> | |
<li>A library JAR may be anywhere within the Java project, within a different | |
project, or outside the workspace entirely.</li> | |
<li>A Java project can have any number of other Java projects on the | |
compile-time class path.</li> | |
</ul> | |
<h2>Complaints about lack of flexibility in Eclipse project structure</h2> | |
<p>The following complaints are representative, but not exhaustive. See <a href="#References">References</a> for | |
the related bug reports and newsgroup postings.</p> | |
<h3>Complaint 1: Unable to locate Java output folder elsewhere</h3> | |
<p>There is no way to locate a Java project's output folder other than somewhere | |
under the project subdirectory. There are several different reasons people | |
complain this is too constraining:</p> | |
<ul> | |
<li>It means that generated class files cannot be squirted into a particular location relative to other | |
files. For example, the class files need to be in specific location, such as | |
C:/tomcat/webapps/mytest/WEB-INF/classes/, so that they are seen by a test | |
web server. It is not feasible to locate all the files for the Java project | |
within the test server's directory. This means a separate step is required to copy the files from | |
the Java project output folder to the test server's directory.</li> | |
<li>It can lead to poor performance. The most important files in the project | |
are the source files, so it makes sense to locate these files on a network drive that | |
is backed up regularly. Locating the project's root directory on a network | |
drive provides a developer with protection against losing important work. | |
Unfortunately, this means that the class files in the output folder also end | |
up being stored on that network drive. Many class files are deleted and rewritten | |
each build, leading to increased network load and slower compile times. | |
Performance would be better if the output folder could be put on a | |
local disk drive, separate from irreplaceable project files.</li> | |
</ul> | |
<p>A related complaint is that there is only a single output folder per Java | |
project. It would be more flexible if it was also possible to associate output | |
folders with each Java source folder.</p> | |
<h3>Complaint 2: Unable to deal with Java source files laid out in pre-ordained | |
structures</h3> | |
<p> Many complaints begin with a statement like: "At my company, | |
the directories are structured in a certain way that can't be changed." A | |
pre-ordained layout for source files can come from any number of real-life | |
considerations. The most common one is that many companies have a | |
large pre-existing source code base stored in a company-wide code repository; | |
changing to a different layout would be a very expensive undertaking.</p> | |
<p>As the following examples illustrate, Eclipse cannot deal directly with | |
source files laid out in many pre-ordained | |
structures. This means that using Eclipse requires developers to work instead | |
with a copied and rearranged source file base.</p> | |
<p>Example 1:</p> | |
<p>The source files for the company's products are laid out in one | |
big directory that is version and configuration managed outside Eclipse:</p> | |
<p> | |
|- AllProducts<br> | |
|- Product1<br> | |
|- JavaSourceFiles<br> | |
|- Product2<br> | |
|- JavaSourceFiles<br> | |
</p> | |
<p>If a Java project is created to work on the files in the Product1 directory, | |
the project's output folder and Eclipse metadata files (.classpath and .project), | |
will end up somewhere under AllProducts. This pollutes the source tree with | |
files that do not belong there.</p> | |
<p>Example 2:</p> | |
<p>The Java source files for the company's products are all held in | |
a single package directory like this:</p> | |
<p> | |
|- AllJavaSourceFiles<br> | |
|- com<br> | |
|- xyz<br> | |
|- product1<br> | |
| |
|- P1Main.java<br> | |
|- product2<br> | |
| |
|- P2Main.java<br> | |
</p> | |
<p>If a Java project is created to work on Product 1, AllJavaSourceFiles will | |
need to be specified as a source folder. But this is unworkable because it means that all the source files for | |
Product 2 will also be included in the Java project and will get compiled along with | |
those of Product 1.</p> | |
<p>Example 3:</p> | |
<p>The Java source files for a product are laid out in | |
package directory like this:</p> | |
<p> | |
|- Product1<br> | |
|- JavaSourcesFiles<br> | |
|- com<br> | |
|- xyz<br> | |
| |
|- product1<br> | |
| |
|- P1Main.java<br> | |
|- tests<br> | |
|- com<br> | |
| |
|- xyz<br> | |
| |
|- product1<br> | |
| |
|- tests<br> | |
| |
|- | |
P1Test.java<br> | |
</p> | |
<p>If a Java project is created to work on Product 1, both Product1/JavaSourcesFiles | |
and Product1/JavaSourcesFiles/tests would need to be given as source folders. | |
Eclipse does not allow this (source folder are not allowed to overlap). If | |
Product1/JavaSourcesFiles/tests is not declared as a source folder, then the | |
Eclipse compiler expects P1Test.java to be in an incorrect package | |
("tests.com.xyz.product1.tests" rather than | |
("com.xyz.product1.tests"). Putting the tests in a separate Java | |
project does not work either.</p> | |
<p>Example 4: </p> | |
<p> The Java source files for two products require a common framework:</p> | |
<p>|- CommonFramework<br> | |
|- JavaSourceFiles<br> | |
|- Product1<br> | |
|- JavaSourceFiles<br> | |
|- Product2<br> | |
|- JavaSourceFiles<br> | |
</p> | |
<p>If a Java project is created to work on Product 1, both Product1/JavaSourcesFiles | |
and CommonFramework/JavaSourcesFiles need to be specified as source folders so | |
that all the code needed for Product 1 is compiled. This means that CommonFramework/JavaSourcesFiles is | |
included in the same project directory as Product1/JavaSourcesFiles. If a Java | |
project is created to work on Product 2, it would need its own copy of | |
CommonFramework/JavaSourcesFiles. If CommonFramework/JavaSourcesFiles are | |
instead placed in a separate Java project, there will be compilation ordering | |
problems when there are mutual references between the common code and the | |
product code.</p> | |
<p>Other examples could be constructed, but the above ones give the flavor of | |
just how inflexible Eclipse is when dealing with source files arranged in | |
perfectly reasonable ways. </p> | |
<h2>Analysis</h2> | |
<p>Note that although the complaints are coming from Java programmers using Java | |
projects, it is not unreasonable to suppose that similar problems could arise | |
when Eclipse is used for other kinds of development, such as C code or web | |
pages. This suggests that the problem should not be construed narrowly, as just a | |
problem just with JDT. The roots of the problem may lie deeper, in the Eclipse Platform | |
itself; resolving the problem may require reforming both.</p> | |
<p>The most obvious restrictions are that all of a project's files must be | |
contained under a single project root directory in the file system. Eclipse | |
projects are <b>single-rooted</b>. Since a Java project's source and output | |
folders are constrained to lie within the project, they thereby inherit | |
constraints from the Eclipse project.</p> | |
<p>Even if the above restrictions were not the problem, there are the further | |
restrictions that all files in the file system below the project root directory | |
are automatically included in the project, and that all Java source files below | |
a source folder are automatically included on the compile-time class path. In | |
other words, Eclipse projects are <b>all-inclusive</b>, as are the source | |
folders of Java projects. In Examples 2 and 3, the complaint is that there is no | |
way to selectively exclude files.</p> | |
<p>Example 4 illustrates a third angle to the problem: that there is no easy way | |
to share common Java source files between projects. In other words, Eclipse | |
projects are <b>non-overlapping</b>. Nor, as Example 3 illustrates, is it | |
possible to have overlapping source folders within a single Java project.</p> | |
<p>To summarize:</p> | |
<ul> | |
<li>With respect to the files in the local file system, an Eclipse project is | |
single-rooted, all-inclusive, and non-overlapping.</li> | |
<li>A Java project's source folders are all-inclusive and non-overlapping, and | |
constrained to lie within a single Eclipse project.</li> | |
<li>A Java project's output folder is constrained to lie within a Eclipse | |
project.</li> | |
</ul> | |
<h2><a name="References">References</a></h2> | |
<p>Eclipse bug reports touching on inflexible project structure:</p> | |
<ul> | |
<li><a href="http://dev.eclipse.org/bugs/show_bug.cgi?id=6664"> 6664 [resources] Sym-link-like feature</a></li> | |
<li><a href="http://dev.eclipse.org/bugs/show_bug.cgi?id=3074"> | |
3074: allow external libs onto the platform classpath?</a></li> | |
<li><a href="http://dev.eclipse.org/bugs/show_bug.cgi?id=6883"> | |
6883: Multiple projects using the same location</a></li> | |
<li><a href="http://dev.eclipse.org/bugs/show_bug.cgi?id=8450"> | |
8450: Project Hierarchy</a></li> | |
<li><a href="http://dev.eclipse.org/bugs/show_bug.cgi?id=8655"> | |
8655: DCR - Support for external class folders</a></li> | |
<li><a href="http://dev.eclipse.org/bugs/show_bug.cgi?id=8783"> | |
8783: Availability to add source directories outside project root</a></li> | |
<li><a href="http://dev.eclipse.org/bugs/show_bug.cgi?id=9508"> | |
9508: resources outside a projcet tree</a></li> | |
<li><a href="http://bugs.eclipse.org/bugs/show_bug.cgi?id=12259"> | |
12259: Need to exclude some specific src/ directories</a></li> | |
<li><a href="http://dev.eclipse.org/bugs/show_bug.cgi?id=15335"> | |
15335: Build output in phisical folder</a></li> | |
<li><a href="http://dev.eclipse.org/bugs/show_bug.cgi?id=18226"> | |
18226: Add button disabled on New Classpath Variable Entry dialog</a></li> | |
<li><a href="http://dev.eclipse.org/bugs/show_bug.cgi?id=19111"> | |
19111: different out folder/drive for class-files</a></li> | |
<li><a href="http://bugs.eclipse.org/bugs/show_bug.cgi?id=24123">24123: Support for multiple output dirs</a></li> | |
</ul> | |
<p>Eclipse newsgroup discussions touching on inflexible project structure:</p> | |
<ul> | |
<li><a href="http://dev.eclipse.org/newslists/news.eclipse.tools/msg10359.html"> | |
Request for Comment: Sym-Link/Shortcut Feature Request</a></li> | |
<li><a href="http://dev.eclipse.org/newslists/news.eclipse.tools/msg10527.html"> | |
Unfortunate requirement that source reside in project</a></li> | |
<li><a href="http://dev.eclipse.org/newslists/news.eclipse.tools/msg16443.html"> | |
Project Location Cannot Overlap?</a></li> | |
<li><a href="http://dev.eclipse.org/newslists/news.eclipse.tools/msg17457.html"> | |
Excluding some source directories</a></li> | |
<li><a href="http://dev.eclipse.org/newslists/news.eclipse.tools/msg18684.html"> | |
working with files _not_ in the project folder</a></li> | |
<li><a href="http://dev.eclipse.org/newslists/news.eclipse.tools/msg08082.html"> | |
Source folders</a></li> | |
<li><a href="http://dev.eclipse.org/newslists/news.eclipse.tools/msg19749.html"> | |
Rigid project directory structure?</a></li> | |
<li><a href="http://dev.eclipse.org/newslists/news.eclipse.tools/msg21223.html"> | |
Q: Setup project, classpath, etc.</a></li> | |
<li><a href="http://dev.eclipse.org/newslists/news.eclipse.tools/msg32082.html"> | |
File sharing between projects</a></li> | |
<li><a href="news://www.eclipse.org:119/am7voi$9it$1@rogue.oti.com"> | |
Source directory issue... need help!</a></li> | |
<li><a href="http://dev.eclipse.org/newslists/news.eclipse.tools/msg16371.html"> | |
build classes in seperate directory</a></li> | |
<li><a href="http://dev.eclipse.org/newslists/news.eclipse.tools/msg14088.html"> | |
How do I specify an external directory for classes?</a></li> | |
</ul> | |
</body> | |
</html> |