<!-- 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 (&quot;.project&quot;) 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: &quot;At my company,
the directories are structured in a certain way that can't be changed.&quot; 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>
&nbsp;&nbsp;&nbsp;&nbsp;|- Product1<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; |- JavaSourceFiles<br>
&nbsp;&nbsp;&nbsp;&nbsp;|- Product2<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; |- 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>
&nbsp;&nbsp;&nbsp;&nbsp;|- com<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; |- xyz<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; |- product1<br>
&nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
|- P1Main.java<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; |- product2<br>
&nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
|- 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&nbsp;like this:</p>
<p>
|- Product1<br>
&nbsp;&nbsp;&nbsp;&nbsp;|- JavaSourcesFiles<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; |- com<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; |- xyz<br>
&nbsp;&nbsp;&nbsp;
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; |- product1<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
|- P1Main.java<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; |- tests<br>
&nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; |- com<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
|- xyz<br>
&nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
|- product1<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
|- tests<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; |-
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
(&quot;tests.com.xyz.product1.tests&quot; rather than
(&quot;com.xyz.product1.tests&quot;). Putting the tests in a separate Java
project does not work either.</p>
<p>Example 4:&nbsp;</p>
<p> The Java source files for two products require a common framework:</p>
<p>|- CommonFramework<br>
&nbsp;&nbsp;&nbsp; |- JavaSourceFiles<br>
|- Product1<br>
&nbsp;&nbsp;&nbsp; |- JavaSourceFiles<br>
|- Product2<br>
&nbsp;&nbsp;&nbsp; |- 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.&nbsp;</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>