After MyFaces 1.1.1 the build system has been moved from ANT to Maven2, all the information refers to MyFaces 0.x-1.1.1. For further information regarding building MyFaces under Eclipse for newer than the above mentioned version please consult the MyFaces Wiki Maven pages!!!!
Building Myfaces under the Eclipse IDE.
Installation of Subclipse
To build MyFaces from the source within Eclipse, you first have to get access to SVN. The recommended way is to use Subclipse as your Eclipse Plugin of choice.
You can install Subclipse by pointing your "Eclipse Software Update" menu towards the online install of Subclipse.
Open the software updates menu under Help->Software Updates->Find and Install. A dialog should pop up.
- Select "Search for New Features to Install"
At the next dialog, select new Update site and add http://subclipse.tigris.org/update as the update site and perform the update.
At least in Windows you should now have a working Eclipse Subclipse plugin. Under other operating systems you might have to compile your own libjavahl or use javasvn. Compiling the javahl layer is beyond the scope of this document. For more information on this topic, check out the document at the Subversion main site
If you cannot get javahl running on your machine or you cannot get satisfactory results, you can revert to Javasvn, an alternate pure java library which can replace javahl. The update site for Javasvn is http://tmate.org/svn/ and more information about this library can be found at that location.
Eclipse and the download of the sources
Once you have sucessfully installed Subclipse, you can point it towards the Subversion repository.
Open the new perspective Window->Perspective->Other ... Subversion Repository Exploring
In the SVN Repository View on the left hand side, click on the right mouse button and choose New->New Repository location
In the new dialog, enter as an URL: https://svn.apache.org/repos/asf/myfaces
- The user name and password can be left blank if you want read only anon access. Otherwise, enter your access data
- Press ok and confirm the dialogs regarding the keys. You should now have access to the SVN Myfaces repository
Once you have established contact to the repository, you are able to check out the sources of the current subfolder into a local project or generate a new project.
"Technical Note - The current folder seems to be empty, but on the server it is symlinked via the svn:external properties to other project folders. Therefore, a checkout of this folder will create a proper project on the local harddrive, although the server folder seems to be empty.
If you want to edit or build the sources, the main problem is that Eclipse, by default, does not have any support for web applications. There are however various commercial or non commerical web application plugins available (see below).
Building from Source
Once you have checked out the project you can use the integrated Ant to build MyFaces from Eclipse. (Don't worry! Using Ant from Eclipse is very easy and graphical. There is no need to wade through XML if using Eclipse.)
First, open the Ant view under Window->Show View->Ant->Ant. You should now have a working Ant view in Eclipse.
- Now click on the Ant symbol with a plus on the right hand side of it and select the build.xml file in the build dir. You should now have a build-file in your ant tree.
- First we have to download all the dependencies,
- open myfaces-realease build file,
- and start download dependencies
- then do a build all on it. You should end up with jars and wars in the various dist subdirs.
Creation of a new Webapp
Bad news for everybody, Eclipse itself does not come with any webapp support whatsoever. You either have to invest time or money to get the webapp support up and running. There are a handful of plugin projects which at least allow basic webapp support and a handful of plugin collections, most of them commercial which often means they are more sophisticated.
We recommend you use some of the more sophisticated free spinoffs of commercial plugins because those can give you a headstart with automatic JSF projects on the latest stable release of MyFaces. The cheapest ones in the commercial range with decent MyFaces support are MyEclipse IDE, which can be found there with relatively cheap subscription service, and Exadel (link), with a free base version and a moderately priced Pro version.
A free and open-source plugin solution is the Eclipse Web Tools Platform (WTP) project which extends the Eclipse platform with tools for developping J2EE web applications. It is in heavy development (milestone downloads available), but it includes everything you may need to develop a web application.
Another alternative for those who want to go the pure opensource route is the FacesIDE which supports MyFaces.
If you want to headstart without any plugins, I recommend using the example which comes with MyFaces for an entry point into the correct webapp structure.
Creation of patches
The preferred way of sending in patches, unless you have committer status is, to create a patch against the current codebase and send it in.
*The way to do that in Eclipse is following:
*Preparations/Checklist: You need to have a working Subclipse in your Eclipse installation. You need to have a valid checkout of the files you want to patch
*Editing and patching: Edit the files you want to fix and create new ones as you would do it normally. Also make sure that every file you have edited is under revision control by using "add to version control." Adding the files to version control makes them targets for the Subclipse patch system. Also make sure you have all the files updated to the latest revision. Now right click on the root folder of your patches (preferrably, the source root) and select team->create patch. A patch target selection dialog should open where you can select the target folder for the patch file. Once you have created the patch, check it quickly for being correct and having all the changes, and send it in over the developers mailing list, or the MyFaces Bug Database
Make sure to remove the leading directory information up-to-and-including your Myfaces Eclipse workspace directory.
Editing the Sources, Debugging, Creation of new Source
The easiest way to edit the sources is to edit the source and use ANT as your build system as described above. However there are other more convenient possibilities for editing and compiling MyFaces.
Eclipse can also connect several subprojects to one big project. It also can debug running servers. Unfortunately the subproject approach does not work with most existing webapp plugins, so a different approach has to be performed. More on that later.
Editing and debugging of the sources
- Preparations of an empty webapp
To prepare eclipse for this kind of editing, a blank myfaces project via the web plugin of choice has to be prepared.
The easiest way is to have the web plugin generate the project structure which should look similar to the following structure
*/src/java for the sources */WebContent/ for all the web content */WebContent/web.xml for the web.xml file */WebContent/WEB-INF/lib for the libs */WebContent/WEB-INF/classes for the classes
Now we have to expand an empty MyFaces web application. After a manual ant build is done on myfaces a blank project can be found under:
This resembles a blank project with one backing bean and one page. This structure now can be used in the libaries and config files of the blank project. It can be expanded with the jar tool or by the servlet container.
The libs of the webproject can be replaced with the ones of the blank project. The same can be done to the web.xml, and a blank faces-config can be created manually if not done already.
After those steps, the blank MyFaces project on the current codebase should be working with the plugin of choice. (Sidenote, the current blank.war uses servlet 2.3 if servlet spec 2.4 has to be used, the web.xml has to be adjusted manually)
Combining the Projects into one main project and MyFaces sources as subproject
Unfortunately the Eclipse project and subproject structure cannot be used in many web plugins for web projects because most of them rely on having the classes compiled into the WEB-INF/classes folder, which eclipse does not allow under the current state of the subproject functionality.
So a different step has to be performed....
The easiest way to get the debugging of the MyFaces classes working is to dump the sources to debug into the source folder of the current webapp project.
The jars already have to be in the WEB-INF/lib hierarchy....
The location of the sources is shown in the image below. The project itself is the debugging project, and the MyFaces sources which are marked are dumped from the MyFaces codebase into this project under the source folder.
- Another possible solution
If ripping out the sources into a separate project is a non option, then, probably checking out the entire MyFaces code into a subfolder for eclipse might be another option. Unfortunatly with the latest version of the subclipse plugin, the checkout into does not exist anymore, so probably a file based approach has to be performed. Either a checkout into a subdir is performed via another client or it is done by copy pasting the entire project into the other one and by deletion of the respective MyFaces subproject .project file (which no longer is needed). That way the build files still can be called, and the source folders of the myeclipse subfolder can be added to the source paths of your webapp project.
The easiest solution if checkout into does not work is to check the MyFaces sources out as a project, then delete the project from eclipse without deleting the contents on the filesystem (a dialog will pop up once you attempt to delete the project) and then move the entire MyFaces file hierarchy into your debugging project. And then after a refresh on the project, the MyFaces project should appear as suproject of your current project. The same probably can be done via the eclipse import funciontality.
The following image shows such a myfaces subfolder within a web project
After the moving or import is done, the source folders of the MyFaces sources can be marked as additional source folders for your current project and now editing and compiling can be done, and the subversion info still should be within the project.
The following screenshots will show such a setup, and how to setup the MyFaces source folders as additional sources folders within the Eclipse project.
- Editing and Debugging
Editing and debugging is dependent on your web application plugin. Most plugins allow for a transparent editing and debugging cycle. Others rely on a non transparent remote debugging facility. Either way, hotplugging can be used and the app server probably has to be restarted from time to time. Hotplugging cannot be applied to the currently edited and debugged class.
Editing and Debugging in MyEclipse, Exadel and FacesIDE
In MyEclipse and Exadel and probably also in the FacesIDE, you can checkout a project as JSF Project. If one of those plugins is used, the easiest way for editing and debugging probably is to use "checkout..as," and then chose webproject or JSF project as target project, depending on your plugin. That way, the entire needed webapp infrastructure is generated side by side to the checked out JSF code.
If that does not work, some plugins allow the creation of a webapp structure after the creation of a project (MyEclipse, for instance, allows this). An entire webapp project structure can be added to the checked-out MyFaces project so that direct editing and debugging within a web application scope from the directly checked out sources is possible.
Unfortunately, after extensive testing, there currently seems to be no way that the MyFaces project stucture can be added in a clean way under Exadel. The plugin is too rigid in its handling of the webapp structure.
*Note, MyFaces and Exadel were the only ones which could be tested. If anyone is reading this and has a different plugin, please add the info here as the approach described earlier, with dumping the project into the folder, seems to be the only one which seems to work.
*Also some more detailed information on the excellent but somewhat rough Exadel IDE have been added
Those two additions give advanced information on the editing and debugging of the MyFaces sourcebase within the limits of the respective plugin extensions.
*Additional Information on the build process can be found here
*Additional Information on how to use forrest for creating the documentation can be found here
* Further information on how to access the subversion repository can be found under here
Important Plugin Links
subclipse Subversion plugin Opensource
MyEclipse IDE Site Commercial
Exadel Site Commercial with a free basic edition
Nitrox JSF IDE plugin Commercial