Skip to content

Latest commit

 

History

History
162 lines (133 loc) · 9.86 KB

Developer Getting Started Guide.md

File metadata and controls

162 lines (133 loc) · 9.86 KB
Raw

Developer Getting Started Guide

This document provides the information required to create a fully functional BridgePoint development environment.

Preparation

  1. This is a link to git documentation that describes working with forks. BridgePoint development requires developers to have a working knowledge of git and git forks. Throughout this document we will refer to the repositories using the formula: https://github.com/"username"/"repository".git where "username" is your personal Github user name. (For example: https://github.com/keithbrown/bridgepoint.git)

  2. This document may be used in Linux, MAC, or Windows, but its examples use Linux. In Windows, cygwin is used to ease setup. Throughout this document we use ~ in the example path names. If you are building on Windows replace ~ with c: (or /cygdrive/c when using the cygwin shell).

  3. This document uses ~/git as the root folder for git repostiories, and it uses ~/workspace as the development workspace. You may substitute any folder you desire, but you must be consistent. WARNING!: If you are updating your development environment to 5.8.5 or greater start with a clean workspace.

  4. Optionally, a pre-configured development virtual machine (VirtualBox) is available for download. See intructions to download and setup here

  5. If you have any problems or questions, check the FAQ or post to the xtUML.org Forums for help.

Setup Instructions

Build Instructions

  • Clone the repositories:
git clone https://github.com/"username"/bridgepoint.git ~/git/bridgepoint
git clone https://github.com/"username"/bptest.git ~/git/bptest
git clone https://github.com/"username"/mc.git ~/git/mc
git clone https://github.com/"username"/pt_antlr.git ~/git/pt_antlr
git clone https://github.com/"username"/models.git ~/git/models
git clone https://github.com/"username"/packaging.git ~/git/packaging

  • There are two ways to configure the build:

    • Modify ~/git/bridgepoint/utilities/build/build_configuration.sh to account for your local paths. Also adjust the flag to indicate if you want to run all the JUnit tests during build or not.
    • Add environment variables to your user environment to override the variables in ~/git/bridgepoint/utilities/build/build_configuration.sh. Look inside build_configuration.sh to see which variables you can override.

  • Build BridgePoint: ~/git/bridgepoint/utilities/build/build_and_test_bp.sh

Congratulations! Your environment is now built and ready for BridgePoint development.

  • Launch BridgePoint (<BridgePoint installation folder>/bridgepoint for MAC it is Eclipse.app)

    • During startup, enter the the eclipse workspace specified in
      ~/git/bridgepoint/utilities/build/build_configuration.sh above.

  • Switch to the git repository perspective and add the repositories that were cloned above.

Debugging

  • Debugging the command-line build (this is done when there is a problem specific to the command-line build)
    • Open the BridgePoint UI
    • Set any breakpoints that are relevant to the issues
         - Restart the test(s) for the project with issues including the debug option:   ~/git/bridgepoint/utilities/build/build_project.sh [test plugin (example: org.xtuml.bp.core.test)] test -debug    - The tests will wait for a remote debugging session, create a new launch configuration in the UI using
    • Select Debug > Debug Configurations...
    • Right click on Remote Java Application and select New
    • Choose the test projet and click Debug
      • The maven build will continue once the remote debugger is fully connected
        • Any breakpoints set will now be hit as long as execution takes it through such a path
        • Debug just as one would if developing in the UI
        • Once the test run is complete with no failures or errors, Run the build again.
    • View the file located under the current directory at: target/site/surefire-report.html for results
    • If there are still problems repeat the debug process, otherwise continue to the next problem if one exists.
  • Debugging Issues From the Eclipse Launch Configurations (this is done when there is a test bug)
    • Select Debug > Debug Configurations..., and note the following:
    • Section Eclipse Application contains the launchers for the BridgePoint builds
    • The BP Application launchers are for Windows.
    • The x BP Application launchers are for Linux.
      • CLI launchers are for the command line interface.
    • Section JUnit Plug-in Test contains the individual launchers for the defined BridgePoint plug-in unit tests.
      • Section Launch Group has a member called BridgePoint Unit Tests, which will launch all of the JUint plug-in tests.
    • Select the appropriate test suite with problems under the JUnit Plug-in Test section
      • Select the Debug button to launch the test.
        • This will cause the selected test to be executed.
        • The builder will build BridgePoint, if necessary, and launch the build as the test target.
        • Examine any stops caused by breakpoints set and address the issue.
        • Once the test run is complete with no failures or errors, navigate to the owning test plug-in on the command line.
        • Run maven again for that test plugin. 
          ~/git/bridgepoint/utilities/build/build_project.sh [test plugin (example: org.xtuml.bp.core.test)] test

Building single projects on the command line

Any project can be built on the command line using the build_project.sh script:

~/git/bridgepoint/utilities/build/build_project.sh [plugin (example: org.xtuml.bp.core)]

The following options are available for building:

  • projectName
  • test
  • clean
  • -online
  • -debug

By default the projects are built offline from maven. This allows for a quicker build. Using the -online mode will allow maven to build online once again. This is helpful when an update is available that is desired.

Adding new unit tests

To add new tests to the BridgePoint testing environment see the HOWTO add unit tests... document.

Tips and Tricks

  1. The UI build can be triggered by enabling the Build builder on the org.xtuml.bp.releng.parent project. When that build is run the entire xtuml tool will be built. Note that testing will not occur with this build.
  • To test you can enable the Test builder on the org.xtuml.bp.releng.parent.tests project. This will build all test projects and run each test suite.

FAQ/Troubleshooting

  • If you have built before and pulled in new repository updates, then you might need to clean the bridgepoint repository.
# Clean bridgepoint repository
cd ~/git/bridgepoint
git clean -fdx -e build_configuration.sh
# Clean unit test repository
cd ~/git/bptest
git clean -fdx
  • Occasionally updates to the development environment will require using a clean workspace.
  • Check the Unit Testing section of BridgePoint FAQ