CD++ User Guide

Version 0.6 Beta

Deluxe

Carleton University

Systems and Computer Engineering Department

August 14 2003

Table Of Contents

1.0 Preface 2

2.0 Introduction 3

2.1 What is CD++ Builder 3

2.2 Change Log 3

2.3 Known Bugs 3

2.4 CD++ Interfaces 3

3.0 Major Functions 5

3.1 CD++ in a Nutshell 5

3.2 Coupling Syntax Editors 5

3.3 Specialized Functions 5

3.3.1 XML Support 5

3.3.2 C++ Support 5

4.0 External Files of CD++ 6

4.1 Coupling Files 6

4.2 C++ Files 6

4.3 Misc Files 6

5.0 Using CD++ Builder 7

5.1 Creating a new project 7

5.2 Opening an existing project 7

5.3 Opening an existing CD++ example 7

5.4 Creating and Editing files 7

5.5 Adding Files to your projects 8

5.6 Using the Navigator 8

5.7 Using the task list 8

5.8 Using the Outliner 9

5.9 Importing/Exporting maml files 9

5.10 Compiling a project 9

5.11 Simulating a project 9

6.0 Reference Documents 10

6.1 CD++ Builder Requirements FAQ 10

6.2 Existing Software Documentation 10

1.0 Preface

This version, CD++ Builder 0.4 beta, is the first beta test version to be released. Although there are many other CD++ tools we want to feature in this product, an early test version is necessary to gain a better perspective of what the client want and improve comfort levels of the plugin. This version is not a stable release that should be used to develop serious or large CD++ projects. If this product is used in any pertinent project please keep a back up copy of your files in case of unknown bugs or until a final stable build is released. Another note is that is that CD++ Builder plugin is compliant with Eclipse 2.X and has been tested on Eclipse 2.X. Compatibility with previous versions or newer versions have NOT been tested yet until our test phase is complete. Beta test users are encouraged to document any problems or comments that they have with this tool. If there are features that you want or feel that should be in CD++ Builder feel free to document it and send it to us. I hope you this the beta version of CD++ Builder as we anticipate your feedback.

Good Luck!

The CD++ Development Team

2.0 Introduction

2.1 What is CD++ Builder

CD++ Builder plugin is a tool for the Eclipse platform that provides the user with a CD++ project development environment to create, edit or view CD++ simulation projects. The tool, implemented with the Eclipse workbench, will provide an IDE where the user can create, open and save projects. It will enable editing of any CD++ related files and support for developing multiple projects. Notes and tasks can be kept within the workbench for reference as will as CD++'s own simulation tools.

2.2 Change Log

Version 0.6

- Fixed compiling bug which cause no compilation

- Fixed Progress Bar bug when no file/project is selected

- New Simu GUI

- Compilation Progress bar

-Version 0.5

- generic console added

- More parameters included for simulation button

- simulation output added to console

- fixed makefile/generalmakefile bug. No longer need to include

makefile1 and generalmakefile in projects

- updated Perspective with new items

- added indicator if no project is selected for simulation and make/build

-Version 0.4

- Automated Makefile builder for CD++

- Make/compile functionality supported

- Simulate functionality supported

- fixed XML Conversion to support multiple containers

- XML conversion supports foreign syntax/keywords

- CD++ Perspective

-Version 0.3

-C++ support added

-Version 0.2

- “New Project” functionality

- fixed refresh bug in XML convert

- improved coupling ADT structuring

-Version 0.1

-syntax coloring for coupling model editing

-XML conversion(reading and writing)

2.3 Known Bugs

- Coupling Syntax Editor is sensitive

- no known output for the make button

- coupling editor provides coloring for only general keywords

- Folders with space “sometimes” corrupts your current project

2.4 CD++ Interfaces

Eclipse is a workbench used for any sort of software development. It is an open-source IDE for anything or nothing in particular. Since you can develop plugins for the Eclipse workbench, you can combine your desired functionality of your plugin with the features of Eclipse. Task menus, notes, error logs, multiple project operations and even drag and drop functionality are included into Eclipse. You can even mold eclipse to your liking to fit your developing needs. The CD++ Builder packages all the potential tools that can be used in a CD++ project from the existing CD++ toolbox and the Eclipse workbench. A default perspective for CD++ builder is given to support the CD++ environment. This includes 5 components:

The Navigator Panel - This component enables you to see multiple projects you have open and their contents.

The Editor panel – This component enables a user to see the contents of a selected file. It is programmed to open the default editor for that particular file should it be a .ma file(ma editor) or a cpp file(CDTs' C++ Editor)

The Task list/Console panel – A section where you can write down planned tasks for your particular project. The console will display any errors you have encountered while running a CD++ function and output from CD++ tools

The Outline panel – A component that outlines the functions and objects in the selected class file. This portion is only implemented for C++ files currently

CD++ tools buttons – Only two CD++ tools are implemented right now. The automated makefile generator and the simulate tool. The automated makefile generator button, will first automatically create a unique makefile for your project and then use it to compile your project. The simulation button will then be able to simulate what you have compiled.

Further explanation of these components are outlined in section 4.0

3.0 Major Functions

3.1 The Builder in a Nutshell

The CD++ Builder is essentially a front-end to CD++, which is a toolkit for discrete-events and Cell DEVS modeling and simulation. CD++ Builder uses Eclipse and its platform plugin development to provide an easy and simple environment to use the CD++ toolkit. Features such as a coupling editor, C++ editing support, importing and exporting data, and an graphical user interface for the CD++ tools are featured in the plugin. However, Eclipse has many of it's own tools to make any user comfortable to developing anything on it's workbench. Many other features such as multiple project views, drag and drop files and much more is integrated into CD++ as well.

3.2 The Coupling Editor

A key aspect in the CD++ Builder environment, the Coupling Editor provides a user to be able to manipulate coupling modeling files. The editor provides a syntax coloring scheme which colors keywords, variables and comments. Basic editor functions are provided as well such as CUA compliant keyboard commands or copy and pasting functionality. A new feature to the CD++ toolbox, this tool will enhance developers intuition for a CD++ project.

3.3 Specialized Functions

3.3.1 XML Support

The Coupling Editor provides a functionality of supporting XML type files which are modeled in coupling model fashion. The XML extension provided for these types of files are “.maml”. When saving a coupling model file, a MAML file is created and saved concurrently. This file provides generic coupling information. MAML files can be exported into a project as well. If desired, a MAML can be converted back into a modeling file for editing.

3.3.2 C++ Support

To develop discrete-events and Cell DEVS models for simulation. CD++ uses C++ to create it's models. C++ support is essential and is provided in full. A syntax coloring scheme is used which separates and colors everything like any commercial C++ IDE. Built in syntax checking is also featured which underlines any piece of code that does not comply to the compiler.

4.0 External Files of CD++ Builder

Coupling Files

Coupling files are stored in .ma format. They can be created, opened and edited in the CD++ Builder environment. Standard syntax coloring for coupling model files are supported as well as basic editor functions. The save format of the files are .ma but also a .maml file is created to export the modeling information to a universal XML file. This file enables the Builder to support other applications in the world of CD++ Simulation

C++ Support

A C++ support package is included in the CD++ Builder tool since modeling is done in C++. Any C++ related files such as source and header files can be opened in the editor panel for editing. These files will also show it's properties in the outliner. They can be created, edit and opened in the CD++ Builder environment.

Misc CD++ Files

Files such as the log file and events file are supported in CD++ but under a normal text editor. They can be included in a project but the editor is not specialized to these types of files. They can do basic creating, opening and editing of these files.

5.0 Using CD++ Builder

5.1 Creating a new project

Creating a new CD++ Builder project can be done in two ways. The first way is that you can click on the “File” tab at the top of the Eclipse window. From there you can select “new” then click on “project”. The other method which will get you to this exact same point, is to click on the icon on the top left tool bar that looks like a window with a magic wand near it. This will bring up a new project wizard panel, where you can create different projects. Selecting the “Other” section on the left side of the panel will bring up possible projects on the right side. Here we select “CD++ Builder”. This will bring us to the CD++ Builder Project Wizard. Following the steps, we first input the authors name, and then the project name. We can select finish at this point to finalize our project or click next to reference it to existing projects inside your workspace.

5.2 Opening an existing project

To open an existing project into your workspace, you have to import it by using the import wizard. This wizard is located by selecting “File” then “import” on the top window bar in Eclipse. The import wizard screen should show up. Select the “Existing Project Into Workspace” and click on the “next” button. The next screen should prompt you to select the folder in which the existing project is located. Once you have selected where the project is, you may click on the “finish” button to import the project.

5.3 Opening an existing CD++ example

To open an existing CD++ example will be a little bit tricky till further versions are released. First you should create a new project as described in section 4.1. This project is blank, and what we intend to do is to add all the required CD++ files into the project for running, compiling or even modifying the example. You must download the desired example which is usually packaged in a zip file and CD++ itself. Both these files must now be extracted into the directory of your current project( Note – Your projects are normally located in \Your_Eclipse_Root_Directory\workspace\Your_Project_Folder\ ). Extract the CD++ program first in to the directory and then extract the example overwriting all. The CD++ example project is ready for whatever you may desire.

5.4 Creating and Editing files

Creating and editing files in eclipse is easier than it seems. To create a file you must go to “File” menu and select the “New” and then “File”. This will bring us to a new file wizard which will ask us information on what type of new file it is and where it shall be created. Highlight the project of where you want the file created and then enter it's name in the bottom panel. Before you click on finish you must enter the extension of the file you are creating. For example if you are creating a C++ file that does DEVS modeling, you must end the file in “xxx.cpp” or if you are creating a coupling file connect your models together, then you must end the file in “xxx.ma”. As soon as you select finish, the file is created and already opened in the editor panel.

Eclipse has a “smart editing” functionality that will open the appropriate editor in the editor panel. When you select any file in your project for viewing or editing, it opens it in the editor panel to the affiliated editor. C++ files will be opened in CDT(Eclipse' C++ Editor), coupling files will be opened in the coupling syntax editor and even log files are text files will be opened in a basic text editor. If you edit a file you can simply hit the save button in the top left corner, if you feel you made a mistake, you can close the file and select “no” to not save it at all.

5.5 Adding Files to your projects

Adding files to your project can be done in multiple ways. You can drag and drop files from any window outside of eclipse into your project which automatically copies that file into the project. Another method is to add them to your project folder using any sort of explorer. The final method is to use the importing function of Eclipse. You must select “File” on the top window bar and then “import” which will bring up an importing panel. Here we can select “file system” and then next, where we specify the directory of the files you want to add. Then by checking off the files you want to import, Eclipse will copy them into your project folder as soon as you click on “finish”.

5.6 Using the Navigator

The Navigator (the panel on the right side), is a simple component that enables you to view an index of all the files in your project. It also lets you view an index of many other projects, even of different types whether or not it is a CD++ project. You can move or copy files from project to project. The navigator can also close projects down that you may not want to view or use, but keeps a closed folder in case you may want to reopen it again.

5.7 Using the task list

The task list which is on the bottom of Eclipse is used to help organize any notes you have on your project. You can use it to leave notes on any files' line of code or even a reminder for a task you want to do later. It is weaved together with any of the editors supported in eclipse to place task markers on any line of code. This can be done by opening any file and right clicking on the far left bar of the editor panel and selecting “add task”. Here you can enter the description of the task and its priority level. When you click on “ok” You can see on the task list that your task has been added. Double clicking on this task will automatically open up the file and bring you to the line of code. To add a generic task that is may not be code based. You can right click on the task list and select “new task” This will prompt you with the similar panel as above asking you for the description and priority.

5.8 Using the Outliner

The outline is solely used for C++ files. When you have opened a C++ file and it is the active part in the editor. The outliner outlines all the variables, functions and dependencies of that particular class. This can be used for quick referencing by double clicking on a function or variable it will bring you immediately to its location in the source code.

5.9 Importing/Exporting maml files

As mentioned in section 3.0, maml files are a representation of coupling files in XML format. Exporting a “.ma” file into maml format is done automatically every time you save your “.ma” file. The saving feature writes a maml file with the same name as the ma file in maml format. This is automatically added to your project.

Importing maml files can be simplistic as well. When you have a maml file in your project, right clicking it and selecting convert to ma, will create a coupling file implementation of the maml file. This coupling file is written and created in your project and should appear in the projects' contents

5.10 Compiling a project

To compile a CD++ project you can click on the “Build” button( a button that has a some working tools on it). This button will automatically create a makefile for you that is unique for your project and then it runs the make command on the makefile. This compiles the project and creates the simu executable for simulation. (Note – you must be in the current project of the project you want to compile.)

5.11 Simulating a project

To simulate a project, you can click on the simu button( a button that has a fist on it). This will bring up a panel where you can specify your coupling file, events file and much more depending if you enable it or not. If you know the name of your files that are in your directory you can type them in. If you would like to choose from a list of files, you can select the “...” button which will present you with a list of all the file types. By clicking proceed, the simulation will start and send all the information to the bottom component of the panel. Clicking on the output text and moving up and down with the up and down keys, will let you review the simulation and it's results. If your coupling file and/or events file is non existent or corrupted, the program will send an error pop up window to tell you. (Note – you must be in the current project of the project you want to simulate.)

6.0 Reference Document

6.1 CD++ Builder Requirements FAQ

<insert link to a revised version of the Req Doc>

6.2 Existing Software Documentation

The CD++ Builder plugin is based off the CD++ tool, information and documentation on the tool can be found at:

http://www.sce.carleton.ca/faculty/wainer/wbgraf/index.html