-
Notifications
You must be signed in to change notification settings - Fork 124
SettingUpDevEnvForMMSContributors
- summary Setting up development environment for MMS Contributors
- labels MMS,Mobicents,TeleStax,MediaServer,MGCP,Eclipse,Debug,test,JSR309,Media,Server,Control
This page describes how to setup a development environment with Eclipse in order to test and debug MMS. It is intended for MMS developers, enthusiasts and contributors who like to look under the hood and tune the engine.
The first step is naturally to pull the MMS source code from the git repository:
Let's assume the root directory of the local git clone of MMS is
After performing the directory contents should looks something like this:
The next step is to install a recent version of Eclipse for Java EE Developers. It is available for download from http://www.eclipse.org/downloads/.
After installing Eclipse, the About dialog should look similar to the following image:
https://raw.githubusercontent.com/wiki/RestComm/mediaserver/images/EclipseJavaEEAbout.png
MMS uses Maven for project build and dependency management.
The M2E plugin for Eclipse allows Maven project management within Eclipse. M2E is already pre-installed with Eclipse Indigo for Java Developers. At this time it does not ship with Eclipse for Java EE Developers, but that might change. Check your plug-in repository in Eclipse to see if M2E is already present. If not, you can download and install from: http://www.eclipse.org/m2e/.
The next step is to import the MMS maven modules from the local git clone to the Eclipse workspace. Go to File > Import > Existing Maven Projects:
https://raw.githubusercontent.com/wiki/RestComm/mediaserver/images/EclipseMaven2Import.png
The next screen should look similar to:
https://raw.githubusercontent.com/wiki/RestComm/mediaserver/images/EclipseMaven2ImportPage2.png
Finish the rest of the wizard with its default options.
Make sure that you have JDK 1.6 or later installed on your machine. Otherwise you will see compile errors in the MMS code. It is possible that your Eclipse by default picked up an older version of the JVM, which results in compile errors in Eclipse. To resolve that, go to Eclipse Preferences > Java > Compiler and set the Compiler compliance level to 1.6. The dialog should look similar to the following screenshot:
If you have projects that need to use an older version of the JDK, you can also set the compiler compliance level just for the MMS maven projects.
To build the full MMS code base, you would need to setup a Maven build target. Go to Run > Run Configuration... Select Maven Build type and create a new configuration. Now setup the Maven parameters in the Main tab. The configuration screen should look like this:
https://raw.githubusercontent.com/wiki/RestComm/mediaserver/images/EclipseMavenBuildTarget.png
You can now build and package MMS by running this new target. Be patient. The build cleans up everything, compiles from scratch, packages and runs all unit tests. It takes a few minutes, but it is well worth the wait. Its better to invest a little extra time in thinking the code changes through before and while running the full build, rather than looking for a quick shortcut to build the project.
Alternatively you can build MMS from the command line like so:
https://raw.githubusercontent.com/wiki/RestComm/mediaserver/images/CommandLineMavenBuildTarget.png
The next step is to prepare Eclipse for running and debugging MMS. Go to Run > Debug Configuration... Select Java Application in the list of debug target types and press the New button to create a new configuration of the Java Application type. You can name it "MMS Main" or something else that makes sense to you. There are two important tabs to setup in the new configuration. In the Main tab, select project from your Eclipse workspace. Then set the main class to . The screen should look like this:
https://raw.githubusercontent.com/wiki/RestComm/mediaserver/images/EclipseDebugConfig1.png
Then populate the VM arguments field in the (x)=Arguments tab. A reasonable default value is:
The screen should look like this:
https://raw.githubusercontent.com/wiki/RestComm/mediaserver/images/EclipseDebugConfig2.png
Now we have come along far enough to be able to run and debug MMS. To start MMS in debug mode and test that it works, let's setup a breakpoint in its main class. If all is well, after setting the breakpoint and starting a debug target, you should see a screen similar to:
https://raw.githubusercontent.com/wiki/RestComm/mediaserver/images/EclipseMMSBreakpoint.png
As MMS is inherently multi threaded you may want to select Suspend VM in Breakpoint options instead of the default Suspend Thread setting.
You can also start MMS from the command line if you prefer:
https://raw.githubusercontent.com/wiki/RestComm/mediaserver/images/StartMMSCommandLine.png
In order to debug an already running MMS server, you need to enable remote debugging from the MMS run script and properly setup Debug Configurations in eclipse:
1. Edit $MMS_HOME/bin/run.sh by uncommenting the following line
#JAVA_OPTS="$JAVA_OPTS -Xrunjdwp:transport=dt_socket,address=8787,server=y,suspend=n"
Notice that this means you will have to attach the debugger to port 8787
2. Open eclipse and load the Mobicents MS project. Make sure the version loaded in eclipse is the same as the one you're running!
3. In eclipse go to Run > Debug Configurations > Remote Java Application.
4. Then double-click and create new. Select the address and port (8787) you want to listen to and chose the modules you want to debug.
MMS is fully compliant with JSR 309 - Media Server Control API. You can verify yourself by running the full JSR 309 test suite. First start MMS. Then from the command line, go to the JSR 309 TCK directory and run the ant junit target like so:
To run a single JSR 309 test from the command line, you can use this example:
It is sometimes helpful to run a single test from Eclipse in order to step through either the test or the MMS code or both. For that, you would need to setup a new Run/Debug Configuration target of type JUnit test. It would look like this:
https://raw.githubusercontent.com/wiki/RestComm/mediaserver/images/JSR309JunitEclipse.png
Hopefully this document was able to speed up the setup time for folks eager to get their hands on MMS and see what it is made of. Contributions to MMS and proposals for improvements to this document are most welcome!