| <!-- 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 follow-on document.<br><br> | |
| Last Modified: 15:15 September 23, 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> | |
| <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> | |
| </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> |