How to Install Castalia

Transcription

1 How to Install Castalia General Castalia is a simulator for WSN and similar networked embedded systems based on OMNeT++. Castalia is a modular and extendable simulator. If Castalia was only simulating a specific behaviour or distributed algorithm for WSN it would be of little use to the WSN community. Users are expected and assisted to create their own applications and protocols. That means users can change the code of certain modules or introduce new modules altogether. Since the users can considerably change the source code and rebuild the simulator many times (as contrasted to building the simulator once and just execute it) we provide some assistance for this mode of usage by automating the building process and alleviating the user from the need to manually edit various Makefiles. Because of Castalia s usage mode, the installation is slightly more complicated than the usual./config and make commands. There are 4 general steps in building Castalia: 1) edit configuration files (in standard installation you just edit the directory path that the source code resides), 2) generate a configuration file related to OMNeT, 3) run the provided script makemake that produces various Makefiles within the source code directory tree, and finally 4) type make to build Castalia. Following are detailed instructions about installing OMNeT and Castalia. Installing OMNeT++ Castalia is based on OMNeT++. Website: If you do not have OMNeT++ in your system, download the source code from the website. The version of OMNeT we have built and tested Castalia with, is 3.3p1. This is the version we recommend. Version 4.0 has not been tested and reportedly does not work with the current version of Castalia. We recommend a Linux/Unix system for a smoother installation process although OMNeT++ can be installed in Windows or in Cygwin under Windows. The instructions given henceforth refer to a Linux/Unix/Cygwin environment For Windows instructions or general OMNeT installation troubleshooting refer to Decompress the source file by typing tar -xvzf omnetpp-3.3p1-src.tgz 1

2 You will have a directory named omnetpp-3.3p1 where all the source code resides. In order to build OMNeT you do the following: Set environment variables by typing (assuming you are using bash as your shell) export PATH=$PATH:~/omnetpp-3.3p1/bin export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:~/omnetpp-3.3p1/lib Also add the above 2 commands at the end of your.bash_profile file. Then check configure.user to make sure it contains the settings you need: vi configure.user (or use an editor other that vi) Suggested changes: If you are planning to change the simulator code then it is a good idea to use CFLAGS that use the g option (fro example the g wall option) so that OMNeT is built with debug information. Otherwise you can stay with the current CFLAGS choice (optimized for speed). Since Castalia does not use any of the graphical user interfaces of OMNeT you do not have to compile for the GUI stuff (and thus saving yourself from complications that have to do with Tcl and BLT installation). Find the line NO_TCL=true in the configure.user file and uncomment it. Alternatively, you can leave the flag as is, so that you can use the generic GUI tools that OMNeT offers, with. Finally, change the flag WITH_PARSIM to no, because you might get compilation problems when it is set to yes, and this feature (parallel distributed simulation) is not really needed. Finally, OMNeT++ must be compiled with dynamic NED loading enabled, so make sure that WITH_NETBUILDER = yes. Then the usual GNU-related stuff:./configure make You are now done building OMNeT. Make sure that OMNeT++ is in the path (to test, try the command "which opp_makemake"). If you opted for setting NO_TCL=true then the building process will stop at the examples (first example is aloha which will not build as it requires Tcl/Tk). That is fine. 2

3 Installing Castalia Get the source code from Assume the file you downloaded is named Castalia-2.0.tgz.gz Untar and unzip the source code file by issuing the following command: tar xvzf Castalia-2.0.tgz.gz A new directory will be created, named Castalia-2.0/ If you acquired the tar file from a source other than Castalia s website make sure that you have the privileges/rights to read/write/execute (rwx) inside Castalia/ recursively. The procedure to build Castalia is the following: 1. Go to the Castalia/config directory and edit the Castalia.config file so that the line ROOT=$(HOME)/YOUR_PATH_TO_CASTALIA contains the right location of Castalia on your local disk. (e.g. ROOT=$(HOME)/research/Castalia-2.0/) 2. In the same directory, re-generate the omnetpp.config file by using the command: opp_makemake -f --genconfig omnetpp.config 3. Go to the Castalia/directory and type the command:./makemake Then wait for some time till the script ends and you see the message: Regenerating nedfiles.lst... Done 4. Now the appropriate Makefiles have been generated. From the directory Castalia/ type the usual build command: make Wait again for sometime until everything is built. Check the directory Castalia/bin for the generated binary/executable file CastaliaBin You have now successfully built Castalia. 3

4 Running a Test Simulation Go to the directory Castalia/Simulations/valuePropagation. It should include at least two files: omnetpp.ini and runvalprop. The latter is a script. Run the script:./runvalprop. You will see some output to your terminal's screen and then the simulation will end with the message: End run of OMNeT++ Simulation results (showing remaining node energy among other quantities) are written in the file Castalia-Primary-Output.txt for every node. Check if this file was created and what are its contents. If you would like to understand what the application is doing and what the output file means, read section 3.1 of Castalia s User Manual. At this stage you are ready to use Castalia. The Castalia User Manual is your guide. The first three chapters are the introductory ones. The rest of this installation guide is devoted to instructing you how to use Castalia with the Eclipse IDE. This is not essential for Castalia to work, it just guide you on how to use Eclipse, which is a powerful and helpful IDE. 4

5 Using Eclipse IDE to build/modify/extend Castalia sources Integrating Castalia into Eclipse is quite simple despite the extensive length of this section. Working with Eclipse will pay the developer back in the long term, by saving time. The descriptions that follow are very detailed. Many of the procedural steps will be very trivial for an advanced user. About half of the information in this chapter is dealing with how you install Java, Eclipse and the CDT plugin for Eclipse. This information could be omitted from this manual but for the sake of completeness and for the convenience of the prospective users of Castalia has been included. Since the information is very similar for Windows and Linux, this section covers both cases, marking Windows information in blue color fonts. What is Eclipse (1)? Eclipse [ is an open source platform-independent software framework for delivering what the project calls "rich-client applications", as opposed to "thin client" browser-based applications. So far this framework has typically been used to develop Integrated Development Environments (IDEs), such as the Java IDE called Java Development Toolkit (JDT) and compiler (ECJ) that comes as part of Eclipse (and which are also used to develop Eclipse itself). Eclipse is also a community of users, constantly extending the covered application areas. An example is the recently created Eclipse Modeling Project, covering most areas of Model Driven Engineering.Eclipse was originally developed by IBM as the successor to its VisualAge family of tools. Eclipse is now managed by the Eclipse Foundation, an independent not-for-profit consortium of software industry vendors. Many notable software tool vendors have embraced Eclipse as a future framework for their IDEs. (1) information is based on the wikipedia.org resource How can I use a Java-based IDE like Eclipse for the C++ based Castalia/Omnet++? One of the most successful Language IDE projects of eclipse is the C/C++ Development Tools Project (CDT) [website] is working towards providing a fully functional C and C++ Integrated Development Environment (IDE) for the Eclipse platform. 5

6 Why should I use an IDE and why should I specifically use Eclipse [full article]? An IDE saves you time (if you are making frequent/extensive changes to the code). It provides easy build, debug, code highlighting, code completion, integration with any C++ compiler and with the Make - GNU build system. Eclipse is a very active open source project with a huge community to support it. It has being tested in the market by very large commercial projects that use it. It provides many open source plug-ins, making development easier and more efficient. Eclipse works for both Windows and Linux How to install Eclipse? A. Instructions for Linux-based systems Step 1: Install Java Go to the download page of Sun Microsystems [Download Java link] and download the latest JDK (current version is JDK 6). Instead of installing the full JDK, you can only install the Java Runtime Environment 5. However, it is always a good thing for a developer, to have the Java (TM) compiler of Sun Microsystems installed on his/her machine. For that reason, JDK is a better option. Don't forget at the end of the installation to modify the PATH (path to JRE or JDK /bin directory), JAVA_HOME (path to installation directory of JRE or JDK) and CLASSPATH (add. ) environment variables. Step 2: Install Eclipse software (It does not include Java 5.0) Visit the download page of eclipse.org and get the latest version of Eclipse IDE SDK. Once you download eclipse-sdk linux-gtk.tar.gz file, move it into the directory that you wish to install Eclipse. Open a new konsole Change to the directory that the eclipse tar.gz file resides type the command : tar -zxvf eclipse-sdk linux-gtk.tar.gz You will then see that a new folder named eclipse has been created. In that folder you will find the eclipse application/executable. We recommend to create a shortcut on the desktop to simplify the launching of eclipse. Notice that Eclipse does not have an installation process. Once you have unzipped the file you are done. Step 3: Launch Eclipse Follow the steps in launching Eclipse [launching link]. The instructions are written for Windows OS but there is no difference for Linux environments. 6

7 Here is a link to an animated demonstration of the installation process: Do you face problems installing Eclipse? At [ you can find an EXCELLENT detailed guide with screen shots for installing Eclipse. How to install the C/C++ Development Tools Project (CDT) on Eclipse? The following installation directions are the same for both Linux -based and Windows systems. 5. Start Eclipse. 6. Go to Help -> Software Updates -> Find and Install Select "Callisto Discovery Site" and click "Finish" button. 8. A pop-up window opens with title: "Update Sit Mirrors. 9. Select a mirror that is closer to your location and press "Ok". 10. A new window pops up with title "Updates". Expand the "Callisto Discovery Site" node and see what are the components of the subtree under that node. 11. Select (place a check in the check box) the latest version of "Eclipse C/C++ Development Tools" under "C and C++ Development" (3.1.1 at the time of this writing). 12. Select the "Next" button. 13. The license agreement window pops-up. Read the license carefully and select the "I accept..." radio button at the bottom. 14. Click the "Finish" button. 15. It will warn you that the Eclipse CDT is an "unsigned feature". But you can just ignore that and select "Install All". 16. Wait until files are downloaded and installed on your computer. 17. Restart Eclipse. 18. Check that at the menu "File-->New-->Project" there the 2 new items: C and C Congratulations! CDT is installed and ready for use. Here is a link to an animated demonstration of the CDT installation process:: Do you face problems installing CDT? At [ you can find an excellent detailed guide with screen shots for installing CDT under both Windows and Linux opersating systems. Another good one can be found at 7

8 Castalia and Eclipse Using Eclipse to write new code or modify the existing code of Castalia will save you time and will make your life easier. We use Eclipse with CDT to write code for the simulator and we owe a big thanks to the community of Eclipse. We assume here that you have installed Eclipse, the C/C++ Development Tools, and OMNeT++ Now you are ready to create and configure your Castalia project in Eclipse. You have two alternatives to work with: (A) You can download the Windows/Linux Eclipse enabled versions of the source code of Castalia, which already contain the created Eclipse-projects. Please pay attention to the fact that there is no guarantee that the platform configuration of the project folders will work to any machine, or that they will work with Eclipse other than version (B) The second option is to create and configure a new C++ project for Castalia. We recommend this option (A) IMPORTING THE READY MADE PROJECT Download the Castalia tar.gz file from the Castalia web-page with the Eclipse/CDT support. Extract the file to the directory of your preference. You should see a new folder named Castalia. Change to /PATH_TO_CASTALIA/config directory and open the Castalia.config with an editor. Set the variable as follows: ROOT= /PATH_TO_CASTALIA where PATH_TO_CASTALIA is the file system directory path where the Castalia sources and scripts reside (e.g. /home/userx/eclipse/castalia). Change to /PATH_TO_CASTALIA directory. Linux users: open the eclipsemakemake.sh with an editor and change the line cd /home/administrator/developement/eclipse/castalia to cd /PATH_TO_CASTALIA Windows users: open the eclipsemakemake.bat with an editor and change the line cd C:\Developement\eclipse\Castalia to cd C:\PATH_TO_CASTALIA Open Eclipse IDE (if you are a Linux user please refer to the Step 1 of section (B) ). On the right side of the main window of Eclipse you will see a tab with the name Make Targets. Click on this tab and right-click on the green circle-target named makemake and select Edit Make target. Correct the absolute path of the custom build command to point to the correct location of the 8

9 eclipsemakemake.sh (Linux) or eclipsemakemake.bat (Windows). Hit on the Update button. See the step 9 of section (B) and change the paths for running correctly the test simulation that comes with Castalia-1.0. (B) CREATING A NEW PROJECT Step 1: Open Eclipse. If your OS is Linux-based then it is recommended to do the following trick so that you open Eclipse with access to the bash shell environment. Delete the default shortcut of Eclipse from your Desktop. Create a file with name runeclipse.sh somewhere at your home directory with the following contents: #!/bin/bash /PATH_TO_ECLIPSE_MAIN_FOLDER_ON_YOUR_SYSTEM/eclipse Attention: The path normally will be of the form xxxxxxx/eclipse/eclipse (for example /Custom-Programs/eclipse/eclipse). This file is a script that calls the executable of Eclipse under the bash shell. In addition you have to make sure that this file has execution rights (e.g. you can issue a command like chmod 755 runeclipse.sh ). Create a new shortcut to your Desktop pointing to the exact location of runeclipse.sh. If you are not satisfied with the icon of your shortcut, you can always choose the eclipse Application Icon in the properties of that file (depending on the X environment that you use e.g. Gnome/KDE ). Now, double-click the Shortcut and give Eclipse some time to initialize and start. Step 2: Choosing a workspace By default Eclipse asks you whether or not you want to use the default Workspace. It is on your personal preference the choice of that location. Workspace is nothing more than a folder that contains some meta-data/settings related to your projects and your system configuration. It is a good tactic to place all your projects inside a workspace. This is not however mandatory. You can have the project folders residing at various locations, but keep in mind that the workspace folder will contain configuration settings and indexes to them. Step 3: Create a new C++ Project Select File --> New --> Project..., Expand the Section C++ and select Standard Make C++ Project. Give a project name (e.g. CastaliaSim ), leave checked the Use Default location checkbox and hit Next. The next window is a multi-tabbed one. Make Builder Tab: If you run under windows you 'll have to unselect the Use default checkbox in the Build command section and provide the command name of the make 9

10 tool that you have installed. For example in MinGW/MSYS you have to use mingw32- make. I personally like to select the Stop on first build error option. C/C++ indexer Tab: It is recommended to disable the indexer (select the No indexer option) because the system becomes very slow if enabled. Use an indexer if your machine's hardware is powerful and primarly if your hard disk drive is quite fast (something like 7200RMP or even better RMP with SATA2 interface, very small average seek time <9ms and large cache). Hit Finish button. Eclipse will now generate a few things, and then ask you if you want to switch to the C/C++ Perspective. This is a good idea, so say yes. You have just created your Castalia project in Eclipse. Congratulations. Step 4: Moving the Sources of Castalia in the Project's directory. Change to the root directory of Castalia and Copy ALL the contents (bin, config, src...etc) directly into the directory that was created by Eclipse for your project. Step 5:Refresh the file view of Eclipse. Maximize the window of Eclipse and select on the left of the window the C/C++ Projects tab. Right-click on the the root project-item (e.g. CastaliaSim ) and select Refresh. All the changes that you did at the directory of the project are updated inside Eclipse. Step 6: Modify the PATH_TO_PROJECT/config/Castalia.config file Open with an editor (or even with Eclipse) the PATH_TO_CASTALIA_PROJECT/config/Castalia.config file and change the value of the ROOT variable to contain the correct path to the copy of Castalia inside the Eclipse project folder (e.g. ROOT=$(HOME)/Developement/eclipse/Castalia). Step 7: Create the Make targets Select on the left of the Eclipse's main window the C/C++ Projects tab. Right-click on the the root project-item (e.g. CastaliaSim ) and select Create Make Target.... Leave all the check-boxes selected except if you are a Windows user and so you have to give mingw32-make in the build command text box. Make 3 targets: all: type all at the Target Name and all at the Make Target clean: type clean at the Target Name and clean at the Make Target clean & all: type clean & all at the Target Name and clean all at the Make Target. Your targets are ready. You can see on the right of the main window of Eclipse at the tab named MakeTargets under your project's name (e.g. under CastaliaSim )the 3 greed circle images that look like targets. Every time you double click them is like calling the respective make command, for example if you double-click the all target, is like issuing the command make all at the root directory of Castalia. Step 8: Create the makemake script target This step is not necessary. It provides the ability to reproduce the Makefile files of Castalia from inside Eclipse instead of calling the makemake script from the 10

11 Konsole/command prompt. Perform this step if you want to work JUST with eclipse and to forget the black screen of your terminal. Follow the same directions as in Step 7 and create a new Target with name makemake and target name makemake as well. At the build command if you are a Linux user give PATH_TO_CASTALIA_PROJECT/eclipseMakemake.sh -f and if you are a windows user give PATH_TO_CASTALIA_PROJECT/eclipseMakemake.bat. Then hit the Create button. Create the eclipsemakemake.sh with the following contents: #!/bin/bash cd PATH_TO_CASTALIA_PROJECT/./makemake Attention: give execution rights to the eclipsemakemake.sh file. Step 9: Create a Run configuration for Castalia Follow from the menu bar of Castalia: Run --> Run... Right-Click on the C/C++ Local Application and select New Give the name CastaliaTestSimulation and at the C/C++ Application field of the Main tab select the bin/castaliabin executable (the executable CastaliaBin will be created after you first successfully build the all target). In the Arguments tab select as working directory the /test folder inside the project of Castalia (hit the Workspace button and navigate to the test directory). Generaly we suggest to test and run Castalia from the command prompt, rather from inside Eclipse. 11