Page History

h1. Checking out and building Felix with NetBeans

In this how-to we go overdescribe the process of checking out and then building Felix from source all from with in using the NetBeans IDE.

h2. Required Software:

# NetBeans 6.1 - You can get NetBeans [Here|http://download.netbeans.org/netbeans/6.1/final/]
# Subversion command -line client - NetBeans uses the subversionSubversion command -line client for its subversionSubversion integration. You can get the subversionSubversion command -line client from [hereTigris|http://subversion.tigris.org/] or if you are working on a Unix machine it will most likely be available in your osOS's package repository.
# NetBeans Maven plugin - You can install this from with inwithin NetBeans by selecting {{Tools->Plugins}} menu item, then choosechoosing the Maven plugin from the {{Available Plugins}} tab and presspressing the {{Install}} button on the bottom of the dialog. For a good introduction ofon what you can do with this plugin see [MavenBestPracticesthe [Maven Best Practices|http://wiki.netbeans.org/MavenBestPractices] page on the NetBeans wiki.
# Maven - You will also need ato locallocally install of mavenMaven to complete this how-to as well. You can download Maven findfrom maventhe [hereMaven web site|http://maven.apache.org/].
\\
\\
{note:title=Why do we need maven?}The NetBeans Maven plugin comes prepackagedpre-packaged with Maven so why do we need a locally localinstalled copy of Maven? The version of Maven that comes prepackaged with NetBeans is a 2.1-SNAPSHOOT which currently has issues building Felix so we need a locally installed copy of the current release version of Maven installed locally so we can use that instead.
{note}

h2. CheckChecking out Felix

*1)* From NetBeans' main menu select {{Versioning->Subversion->Checkout}} as shown in Figure1Figure 1.

{div:style=css|align=center}
{color:#4f81bd}Figure1Figure 1: NetBeans Subversion Menu{color}
!figure1.png!
{div}

*2)* Now we need to fill in the checkout dialog box. For this dialog box all we need to do is fill in the {{Repository URL}} (See below for a what this should be). Once you have set the Repository URL you can press the {{Next}} button. See Figure Figure22 for what the dialog should look like when you are done.
{noformat}Repository URL: http://svn.apache.org/repos/asf/felix/trunk{noformat} you are done.

{div:style=css|align=center}
{color:#4f81bd}Figure2Figure 2: NetBeans checkout dialog box{color}
!figure2.png!
{div}

*3)* In the next panel of the checkout dialog box we need to set where we want to put the source code as well as some parameters that will get passed to the subversion client. 

* Repository Folder(s) - This should be set for you, but if it is not it should be "felix/trunk"
* Repository Revision - Leave this one blank. *NOTE:* If you want to check out a particular version of felixFelix you can put the revision number here and that revision will be checked out. For our purposes here we want to get the latestslatest revision. 
* Skip "trunk" check box - Check this. This option means that the source code will be checked out into the root of the folder/directory that we supply.
* Local Folder - This is thewhere location that the source code will be checked out tolocally. You can press the browse button to select a directory. *NOTE:* If you need to create a sub -directory pick the parent then in the edit box add it to the path. It will be created for you during the check out. 
* Scan for NetBeans Projects after checkout check box - You can either uncheck thischeck or leaveuncheck itthis checkedbox. Either way NetBeans will not open any of the projects because there are approximately 183 projects in the Felix source tree. Later we will pick the specific project we need for compiling Felix. 

Once you have filled in the second panel of the checkout dialog press the "{{Finish"}} button at the bottom of the dialog. See Figure Figure33 for how the dialog should look. 

{div:style=css|align=center}
{color:#4f81bd}Figure3Figure 3: NetBeans checkout dialog box (panel 2){color}
!figure3.png!
{div}

*4)* It may take a while for the check outcheckout to complete. If you want to see what is happening, take a look at the output window at the bottom of the NetBeans window. If you don't see it select {{Window->Output->Output}} to make it display. You should see something like what is shown in Figure Figure44.

{div:style=css|align=center}
{color:#4f81bd}Figure4Figure 4: NetBeans output window{color}
!figure4.png!
{div}

*5)* If you left the "Scan for NetBeans Projects after checkout" check box checked you will see the dialog in Figure5Figure 5 when subversionSubversion finishedfinishes checking out Felix. For now just press the cancel{{Cancel}} button. 

{div:style=css|align=center}
{color:#4f81bd}Figure5Figure 5: NetBeans open project dialog{color}
!figure5.png!
{div}

*6)* This concludes the section on checking out the Felix source code.

h2. Building Felix

In this section we will be going over how to build Felix from within NetBeans. 

*1)* Setup external Maven in NetBeans

Before we can build Felix, we need to set setupup NetBeans so that it can use our external Maven instead of the one bundled with the Maven plugin. You do this in the NetBeans options dialog ({{Tools->Options}}). Select the "{{Miscellaneous"}} icon at the top of the dialog. Then select the "{{Maven 2"}} tab. What we want to do here is tell NetBeans where we installed Maven. You can press the "{{Browse"}} button to browse to the directory where you installed Maven. You can leave the rest of the options as they are. See Figure 6 for how this dialog looks and how Ito haveset it setupup.

{div:style=css|align=center}
{color:#4f81bd}Figure6Figure 6: NetBeans Maven option dialog{color}
!figure6.png!
{div}

*2)* Open the Felix project folder

NewNow we need to open the Felix build project folder. This will be the "{{pom}}" project. It is located in the directory where you checked out the source code. When you locate it select the project and press the "{{Open Project"}} button. See Figure 7 for how this looks.

{div:style=css|align=center}
{color:#4f81bd}Figure7Figure 7: NetBeans Open Project dialog{color}
!figure7.png!
{div}

When the project is opened your "Projects" pane should look something like Figure 8.

{div:style=css|align=center}
{color:#4f81bd}Figure8 : NetBeans Project pane{color}
!figure8.png!
{div}

*3)* Configure the Projectproject

We now need to change one aspect of the project configuration. So right click on the project and select the "{{Properties"}} menu item., Thenthen select "Actions"the {{Actions}} category. What we need to do here is check the "{{Use external Maven for build execution}}" check boxcheckbox. Once you have done this you can press the "{{OK"}} Button. See Figure 9 for how this should look.

{div:style=css|align=center}
{color:#4f81bd}Figure9Figure 9: NetBeans Project properties dialog{color}
!figure9.png!
{div}

*4)* Select a build profile

Felix is built in two phases. These two phases are controlled by Maven profiles so we want to set the profile that we want to build. You do this by right clicking on the project then select profiles{{Profiles->packaging-plugins}} to select the profile., Seesee Figure 10.

{div:style=css|align=center}
{color:#4f81bd}Figure10Figure 10: NetBeans Project profiles{color}
!figure10.png!
{div}

*5)* Build Felix plugins

Now that we have selected the correct profile all we have to do is build it. Right click on the project and select the "{{Clean and Build}}" menu item. You should see something like Figure 11 when the build is completedcomplete. *NOTE:* If you have not done this before it may take a little while, assince Maven will needneeds to download a bunch of bundlesplugins. 

{div:style=css|align=center}
{color:#4f81bd}Figure11Figure 11: pluginsPlugins build output{color}
!figure11.png!
{div}

*6)* Build Felix bundle

Now that we have built the plugins it is time to build the felixFelix bundle. Like in step 4, we Rightright click on the project and select profiles{{Profiles->packaging-plugins}} (to unselect it), then do it again but this time select profiles{{Profiles->packaging-bundle}}. Once you have done that you can "{{Clean and Build}}" the project. See Figure 12 for what you should see in the output window when the build completes. 

{note:title=Did you get a OutOfMemoryError during the bundle build?}
TheSometimes, the Felix bundle build some times will throwthrows this error. Just try to build it again and it should go away after you do it a couple of times as there will be less to build each time. Or if you want you can increase the memory available to Maven. I have found that setting the environment variable MAVEN_OPTS to "-Xmx1024m -Xms512m" would allowallows me to build Felix completely the first time though. It should be noted that if you change this you may need to shut down and restart NetBeans before Maven will see this environment variable as Maven inherits its environment variables from NetBeans and NetBeans will not get the new or updated variable until you restart it. 
{note}

{div:style=css|align=center}
{color:#4f81bd}Figure12Figure 12: bundleBundle build output{color}
!figure12.png!
{div}

h2. Conclusion 

If every thing went as expected then you should have a built and ready to run Felix installation in the "main" directory under the directory where you checked out Felix. You can now run Felix from the command line by changing to that directory and running this command:

{noformat}
java -jar bin/felix.jar
{noformat}

h2. Other documentation

You youmay mayalso want to read:

* [Integrating Felix with NetBeans|Integrating Felix with NetBeans] - A how-to style document that shows how to run Felix under NetBeans. 
* [Felix usage|Apache Felix Usage Documentation] - Go to the Felix usage page to learn how to launch the Felix framework. 

h2. How to get help

If you need any help or have questions about this document you can ask on the Felix Users Mailing list. See [Felix Mailing lists|mailinglists] for how to subscribe to the list.