Difference between revisions of "ESAPI-BuildingWithEclipse"

From OWASP
Jump to: navigation, search
(Created page with '==Eclipse Setup== * Get the [http://www.eclipse.org/downloads/ Ganymede release of Eclipse] - We recommend the version for Java EE developers ** Simply unzip the contents wherev…')
 
m
Line 1: Line 1:
==Eclipse Setup==
+
Prerequisites:
  
* Get the [http://www.eclipse.org/downloads/ Ganymede release of Eclipse] - We recommend the version for Java EE developers
+
  - *JDK 1.5 or above installed* (Required for Maven Eclipse plugin to work
** Simply unzip the contents wherever you like. This 'installs' Eclipse.
+
  properly)
* Install [http://java.sun.com/javase/downloads/index.jsp Java JDK 5.0 or greater] if you don't have it yet.  Note: a ''JDK'' (not JRE) is required
+
  - *Eclipse IDE 3.3.x or above* (Can be downloaded from:
* Within Eclipse, download and install the [http://subclipse.tigris.org/install.html Eclipse Subversion (SVN) plugin] called Subclipse. 
+
  http://www.eclipse.org/downloads/)
** Skip step 12 (do not open the SVN perspective)
+
  - *Maven M2Eclipse plugin for Eclipse* (You can install the latest
* Within Eclipse, download and install the [http://m2eclipse.codehaus.org/ Eclipse Maven plugin].  At this time, we recommend using the latest stable development build (the second link on the page)
+
  version from within maven using the following update site from within
** Only install the Maven Integration Components
+
  Eclipse: http://m2eclipse.sonatype.org/update/)
* Connect to the SVN and download the ESAPI source.  Directions can be found [[ESAPI-Building#Subversion_Setup|here]]
+
  - *SVN Subclipse Plugin Eclipse* (Instructions on installing Subclipse
* Download the latest build of Maven from [http://maven.apache.org/download.html here]
+
  plugin can be found here:
* Download [http://owasp-esapi-java.googlecode.com/files/ESAPI_setup_resources.zip the ESAPI setup resources] and extract the files. Edit the included script file to match your directory structure.  Then run the script to add all ESAPI and Swingset dependencies to your Maven repository (enables building of ESAPI and Swingset). We recommend you run the script from the command line so that you can see the errors if any.  ''NOTE: the AntiSamy file mentioned in the batch file is also included in the archive''
+
  http://subclipse.tigris.org/servlets/ProjectProcess?pageID=p4wYuA)
** If you do not plan on building Swingset too, comment out any lines in the script that reference Swingset
+
** If the script loads and quickly closes or there are build errors, it is likely that at least one of the references to files/folders is not correct (Use "" if there is a blank space in the path). Or, try removing all the REM lines from the script if it is also getting added to the path.
+
* Close Eclipse
+
* If you do not launch Eclipse from a shortcut, create a shortcut for Eclipse
+
# Navigate to the directory where you installed Eclipse
+
# Right-Click Eclipse.exe and select ''Create Shortcut''
+
* Right-Click your Eclipse shortcut and select ''Properties''
+
* At the end of the line that says ''Target'', add ''-vm "x"'' where ''x'' is the location of a JDK (e.g., "C:\Program Files\Java\jdk1.6.0_13\bin").  This step is necessary for the Maven plugin to work
+
* Restart Eclipse using the edited shortcut.
+
* Follow the instructions below for Importing the ESAPI Source.
+
  
==Importing the ESAPI Source==
+
*Configuration:*
To import the ESAPI source code into your workspace, you can either download the source files in a zip file from [[::Category:OWASP_Enterprise_Security_API#Download_Now|here]] or download the latest trunk from the ESAPI SVN. 
+
  
'''The zip files containing the ESAPI source''' are official releases of the ESAPI.  They will be updated whenever major changes are made to the ESAPI, whether features are added/removed, or if ESAPI undergoes a major organizational change. If you are planning on using the ESAPI's reference implementations and want to see ESAPI's source, but do not want to build your own JAR, you might download the ESAPI source zip file (available [[::Category:OWASP_Enterprise_Security_API#Download_Now|here]]).
+
  - Create an Eclipse shortcut
 +
  - Right-Click your Eclipse shortcut and select *Properties*
 +
  - *At the end of the line that says Target, add -vm "x" where x is the
 +
  location of a JDK (e.g., "C:\Program Files\Java\jdk1.6.0_13\bin"). This step
 +
  is necessary for the Maven plugin to work*
 +
  - *Restart Eclipse using the edited shortcut.*
  
'''The ESAPI trunk SVN''' contains the most up-to-date development version of ESAPI.  The trunk may contain different code from the pre-zipped source.  It may contain new features or be organized differently.  The trunk is a development version of the ESAPI, meaning that contributors to the ESAPI project are actively editing this code, so while all contributors are encouraged to run all test cases on the code before committing it, developers using this code should run their own tests to be sure the code is fully functional.  In addition, because the trunk code is in development, documentation regarding the ESAPI, especially Javadocs, may not be entirely accurate.
+
*Importing the ESAPI Source from Google SVN:*
  
===Source Code From a .zip===
+
If you choose to use the ESAPI SVN code, follow the instructions
 
+
here<http://code.google.com/p/owasp-esapi-java/source/checkout>.
While there are a few ways to import the ESAPI project using a zip file of its source code, I recommend following these instructions.  For the moment, I'll assume you are using Eclipse as your IDE.  More tutorials may come in the future for other IDEs.
+
Unless you have been added to the ESAPI project as a contributor, please use
 
+
the bottom SVN checkout link on the Google Code page (non-SSL).
* Unzip file ESAPI source files to a directory of your choice.
+
* From the Eclipse toolbar, select ''File'' -> ''New'' -> ''Project'' -> ''Other''.
+
* In the ''Java'' folder, select ''Java Project from Existing Ant Buildfile'' and click Next.
+
* Name your project.
+
* Click ''Browse'' and navigate to the unzipped ESAPI source files.
+
* From the root directory (probably ESAPI_version) select ''build.xml''.
+
* Click ''Finish'' and you should be ready to edit ESAPI.
+
 
+
===OR===
+
 
+
===Subversion Setup===
+
 
+
If you choose to use the ESAPI SVN code, follow the instructions [http://code.google.com/p/owasp-esapi-java/source/checkout here]. Unless you have been added to the ESAPI project as a contributor, please use the bottom SVN checkout link on the Google Code page (non-SSL).
+
  
 
If you are using subclipse, as recommended, open Eclipse and:
 
If you are using subclipse, as recommended, open Eclipse and:
* Click ''File'' -> ''New'' -> ''Other....''.
 
* From the ''SVN Folder'' select '"Checkout Projects from SVN'' (this option will only be available if you have a SVN plugin installed) and hit ''Next >''.
 
* Click the ''Create a new repository location'' radio button.
 
* If you are not listed as a project contributor, insert ''http://owasp-esapi-java.googlecode.com/svn/trunk/'' as the URL.  If you are listed as a project contributor, check the Google Code page for the URL to use. (Note: if you are a contributor, when prompted for your SVN password, use your Google generated password, available from the Google Code Source page.)
 
* Once the directory structure appears in the window, click the URL at the top to download everything.  Then hit ''Next >''
 
* Select your desired project options.  For most people, the default options should be fine. When finished, click ''Next >''.
 
* Select your desired workspace options, then click ''Finish''.  The latest ESAPI source files will then be downloaded to your workspace.  This may take a few minutes.
 
  
==Project Setup==
+
  - Click *File* -> *New* -> *Other....*.
 +
  - From the *SVN Folder* select '"Checkout Projects from SVN* (this option
 +
  will only be available if you have a SVN plugin installed) and hit *Next
 +
  >*.*
 +
  - Click the *Create a new repository location* radio button.
 +
  - If you are not listed as a project contributor, insert *
 +
  http://owasp-esapi-java.googlecode.com/svn/trunk/* as the URL. If you are
 +
  listed as a project contributor, check the Google Code page for the URL to
 +
  use. (Note: if you are a contributor, when prompted for your SVN password,
 +
  use your Google generated password, available from the Google Code Source
 +
  page.)
 +
  - Once the directory structure appears in the window, click the URL at
 +
  the top to download everything. Then hit *Next >*
 +
  - Select your desired project options. For most people, the default
 +
  options should be fine. When finished, click *Next >*.
 +
  - Select your desired workspace options, then click *Finish*. The latest
 +
  ESAPI source files will then be downloaded to your workspace. This may take
 +
  a few minutes.
  
Some configuration may be necessary for ESAPI to compile and build on your system.
+
Building
 
+
ESAPI requires the Java JRE 5.0+
+
 
+
* Once Java 5.0+ is installed, open the ''Navigator view'' in Eclipse.  If this is currently hidden, from the toolbar click ''Window'' -> ''Show View'' -> ''Navigator''.
+
* Right-click on your ESAPI project in the Navigator, mouse over ''Maven'' and click ''Enable Dependency Management''
+
** ''Note:'' If Maven is not an option when you right-click on the project, be sure the Maven plugin for eclipse is installed, as described above.
+
** ''Note:'' If ''Enable Dependency Management'' is not an option, dependency management is probably already enabled, So this step can be skipped.
+
* ''Right-click on the ESAPI project root folder'' in the Navigator view and select ''Properties''.
+
* From the left column, select ''Java Build Path''.  Under the ''Libraries'' tab, be sure a JRE or JDK is listed next to ''JRE System Library''.  If there is a red X on next to the JRE, remove the current JRE and click ''Add Library'' and select an alternate JRE.  If you are having trouble figuring out what version the current JRE is, select ''Installed JREs'' and look at the location to which each version is mapped.
+
* The Libraries tab should list ''JRE System Library'' and ''Maven Dependencies''.  If anything else is listed, it is not necessary and should be removed.  Maven now handles all dependencies.
+
* If a red X appears next to ''Maven Dependencies'', click the arrow on the left to expand the tree.  If AntiSamy has an error, be sure the [[ESAPI-Building#Eclipse_Setup |script listed above]] ran without errors.
+
* From the left column, select ''Java Compiler''.  Be sure ''Compiler compliance level'', ''Generated .class files compatibility'', and ''Source compatibility'' are all set to ''1.5''. 
+
* Close the properties window.
+
* ''Right-click the ESAPI project root folder'' and select ''Refresh''.
+
* From the toolbar, select ''Project'' -> ''Clean..'' and select the ESAPI project.  Click ''OK''.
+
* If errors remain, select ''Maven'' again, then ''Update Dependencies''.
+
* ESAPI should now be compiled.
+
 
+
==Building==
+
  
 
Building ESAPI should be easy with the new Maven integration.
 
Building ESAPI should be easy with the new Maven integration.
  
 
Once your environment is set up, as specified above:
 
Once your environment is set up, as specified above:
# Right-Click your ESAPI project root folder
 
# Select ''Run As...''
 
# Select ''Run Configurations''
 
# Double Click "Maven Build" from the options on the left to create a new configuration.
 
# Name your configuration at the top.  This will be for building ESAPI without running JUnit tests.
 
# The "Base directory" should point to the root of your project
 
# The "Goals" field type "package"
 
# From the checkboxes below, check "Skip Tests"
 
# Any options not mentioned should be left as their default
 
# Click "Apply" to save your build configuration
 
# Click "Run" to run your configuration
 
 
''NOTE: There is a bug in Maven Eclipse plugin which does not allow native2ascii to run properly.''
 
 
To build project using Eclipse we need to point Maven plugin to use our own Maven installation instead of using the embedded.
 
 
This can be done as:
 
#In Eclipse Click Window-->Preferences-->Maven-->Installation-->click add and point to your Maven installation directory. Click ok.
 
#Goto Run Configuration and select Maven Runtime: External
 
 
''NOTE: Jars created through building are located in the directory called "target". ''
 
 
==Running Test Cases==
 
 
* From the ''Navigator'' view, select test/org/owasp/esapi/AllTests.java
 
* ''Right-click'' -> ''Run As'' -> ''Run Configurations...''
 
* Choose the JUnit configuration
 
* Select the ''Arguments'' tab and enter a VM argument
 
** -Dorg.owasp.esapi.resources="<path to your esapi project>/test/testresources"
 
* run tests and verify that they all pass
 
 
==Running Demo App==
 
  
The ESAPI Demo application has been named ''The ESAPI Swingset''. More information about Swingset is available [http://www.owasp.org/index.php/ESAPI_Swingset here].
+
  1. Right-Click your ESAPI project root folder
 +
  2. Select *Run As...*
 +
  3. Select *Run Configurations*
 +
  4. Double Click "Maven Build" from the options on the left to create a
 +
  new configuration.
 +
  5. Name your configuration at the top. This will be for building ESAPI
 +
  without running JUnit tests.
 +
  6. The "Base directory" should point to the root of your project
 +
  7. The "Goals" field type "package"
 +
  8. From the checkboxes below, check "Skip Tests"
 +
  9. Any options not mentioned should be left as their default
 +
  10. Click "Apply" to save your build configuration
 +
  11. Click "Run" to run your configuration
  
__NOTOC__
+
NOTE: Jars created through building are located in the directory called
 +
"target".
  
 
[[Category:OWASP Enterprise Security API]]
 
[[Category:OWASP Enterprise Security API]]

Revision as of 17:33, 7 November 2009

Prerequisites:

  - *JDK 1.5 or above installed* (Required for Maven Eclipse plugin to work
  properly)
  - *Eclipse IDE 3.3.x or above* (Can be downloaded from:
  http://www.eclipse.org/downloads/)
  - *Maven M2Eclipse plugin for Eclipse* (You can install the latest
  version from within maven using the following update site from within
  Eclipse: http://m2eclipse.sonatype.org/update/)
  - *SVN Subclipse Plugin Eclipse* (Instructions on installing Subclipse
  plugin can be found here:
  http://subclipse.tigris.org/servlets/ProjectProcess?pageID=p4wYuA)
  • Configuration:*
  - Create an Eclipse shortcut
  - Right-Click your Eclipse shortcut and select *Properties*
  - *At the end of the line that says Target, add -vm "x" where x is the
  location of a JDK (e.g., "C:\Program Files\Java\jdk1.6.0_13\bin"). This step
  is necessary for the Maven plugin to work*
  - *Restart Eclipse using the edited shortcut.*
  • Importing the ESAPI Source from Google SVN:*

If you choose to use the ESAPI SVN code, follow the instructions here<http://code.google.com/p/owasp-esapi-java/source/checkout>. Unless you have been added to the ESAPI project as a contributor, please use the bottom SVN checkout link on the Google Code page (non-SSL).

If you are using subclipse, as recommended, open Eclipse and:

  - Click *File* -> *New* -> *Other....*.
  - From the *SVN Folder* select '"Checkout Projects from SVN* (this option
  will only be available if you have a SVN plugin installed) and hit *Next
  >*.*
  - Click the *Create a new repository location* radio button.
  - If you are not listed as a project contributor, insert *
  http://owasp-esapi-java.googlecode.com/svn/trunk/* as the URL. If you are
  listed as a project contributor, check the Google Code page for the URL to
  use. (Note: if you are a contributor, when prompted for your SVN password,
  use your Google generated password, available from the Google Code Source
  page.)
  - Once the directory structure appears in the window, click the URL at
  the top to download everything. Then hit *Next >*
  - Select your desired project options. For most people, the default
  options should be fine. When finished, click *Next >*.
  - Select your desired workspace options, then click *Finish*. The latest
  ESAPI source files will then be downloaded to your workspace. This may take
  a few minutes.

Building

Building ESAPI should be easy with the new Maven integration.

Once your environment is set up, as specified above:

  1. Right-Click your ESAPI project root folder
  2. Select *Run As...*
  3. Select *Run Configurations*
  4. Double Click "Maven Build" from the options on the left to create a
  new configuration.
  5. Name your configuration at the top. This will be for building ESAPI
  without running JUnit tests.
  6. The "Base directory" should point to the root of your project
  7. The "Goals" field type "package"
  8. From the checkboxes below, check "Skip Tests"
  9. Any options not mentioned should be left as their default
  10. Click "Apply" to save your build configuration
  11. Click "Run" to run your configuration

NOTE: Jars created through building are located in the directory called "target".