Traffic 3.1 Getting Started

Transcription

1 Traffic 3.1 Getting Started Semester Thesis By: Supervised by: Matthias Loeu Michela Pedroni Prof. Bertrand Meyer Student Number:

2 Abstract Since 2003 the Chair of Software Engineering at the ETH Zurich teaches Introduction to Programming for their first semester students following the ideas of the Inverted Curriculum. It builds around a large piece of software which includes a tool called Traffic which is still quite complicated for the average first semester student. My work gives the students some help in getting started with Traffic as well as instructions and tools to create and run new applications which use the Traffic software. This report covers the scope of my work and the achieved results as well as the problems I have encountered and possible future work that can be done based on my results.

3 Table of Contents 1 Introduction Objectives Getting Started Guide Installation and Configuration Run example applications Create application from scratch Integration with the rest Traffic Application Creator Problems Future Work Conclusion References Appendices Appendix A... 7

4 1 Introduction Since 2003 the Chair of Software Engineering at the ETH Zurich teaches Introduction to Programming for their first semester students following the ideas of the Inverted Curriculum. It builds around a large piece of software which includes a tool called Traffic [1]. The Traffic library has undergone many changes since then, however the documentation is sparse and frequently relies on an old version of Traffic. Despite many simplifications, Traffic has grown very complex and it can be a tedious task for a first semester student (who may have never programmed before) to download & install the various components of Traffic and to create, configure, build, and run his first application using Traffic. The goal of this project was to provide the first semester students with a simple means of creating an application which uses Traffic. 1.1 Objectives The objective of the project was to create a user guide/how to for students to install and run applications using Traffic. Additionally, a software tool/wizard now automates the application creation procedure. 2 Getting Started 2.1 Guide Installation and Configuration Since my own experience with Traffic is a bit dated, my first task was to get acquainted with the current version of Traffic. That meant downloading, installing and running the software packages with only limited help. At the same time, I began writing the guide, which at that time was only a simple text document with notes as to what is to be done. From the notes it was possible to install Traffic on other computers without much problems, every time refining my notes adding more comments, removing obsolete ones and rearranging some sections. At a very late stage, I made a lot of screenshots to aid the process. This portion of the guide is partly based on the existing documentation [2] Run example applications I felt it would be handy to have a guide ready for someone who just wants something on the screen fast and does not want to go trough the pain of figuring out what to do. Additionally, I am aware that this is quite easy but since I did run example applications and also had taken notes in the process I figured why not. This section of the guide is pretty short, but informative anyway Create application from scratch Here lies the meat of my work. I first studied the internal workings of a few touch applications and Flat Hunt. They are fundamentally different the only common thing they have is probably the reliance of Traffic. I used Flat Hunt as a basis to write the first part of this section of the guide: Including the Traffic library into a new application. I first thought it would be very complicated, having some

5 bad experiences from previous versions of EiffelStudio [3] and Traffic. It still is a quite tedious task, but luckily does not involve opening a configuration file and manually editing it. Creating a Touch application is a whole other matter. First, I was to write the including the Traffic library again with minor modifications here and there (to account for the fact that those are quite different applications). Halfway trough the process I decided against it, mostly because large parts are the same anyway. Instead I have put the instructions on how to include the Traffic library in its own section at the beginning of this chapter. The third and last part of this section deals with the creation of other applications which use Traffic. It still is in a rough form, because of time constraints and the fact that the applications which are created here are very different. For example it is not known whether the first scene to be displayed is in fact the Traffic -screen or another one. See also section 3 of this report Integration with the rest As noted before, I started writing the guide in a simple text file. However the rest of the documentation is done using custom XML files which in turn did not have much documentation attached to them; so it was a game of figuring out how to write things in the format required. This was a very tedious and boring task, but it has to be done in order to be consistent with the other Traffic documentation and not to confuse the audience. 2.2 Traffic Application Creator The whole process of including Traffic in an Eiffel application is deterministic and always the same therefore right from the beginning it was clear that I had to write a software tool to support creating Traffic applications. Again, due to time constraints the tool only creates Touch applications. It is, however, easily extendable and prepared to create other application types. The root class is TRAFFIC_APP_CREATOR. It does not do much, only create the main window, which is appropriately named MAIN_WINDOW. This class and its _IMP were

6 originally created by EiffelBuild. The implementation was not changed in any way (so one can use EiffelBuild to extend the application and just import that file here). MAIN_WINDOW holds most of the logic which deals with the user interface, such as pressing buttons and such. The logic of what to do in order to create a Touch application is in TOUCH_APP. It takes the user input from MAIN_WINDOW and describes what to do with it. Essentially I have created a sample Touch application with markers in the files to replace with the user supplied values, which the class REPLACER does for me. 3 Problems The most notable problem I have encountered is the lack of time. I started this project more than half a year ago and wanted to finish two months ago. Therefore, some sections of the guide are a bit shorter than what was intended and the application creator is very simplistic in design. A further problem was the lack of documentation. The XML files do not have a definition attached to them, one has to guess how to make a paragraph, or how to make some text appear in boldface (or mark it as important). Those XML files are not very flexible, I found that for example you can not use the next / previous buttons to go to different places in the document hierarchy. So the whole guide is essentially a flat document split up into multiple pages/files. There is no templating engine per se in Eiffel Studio. I just found various templates lying around, but ultimately nothing useful. So I had to write a custom engine which luckily was not too hard. It however used some extra time, time which I did not have. 4 Future Work There is a lot of work which still needs to be done: Finish writing / fleshing out the section about how to create a new Traffic application. Extend the Traffic Application Creator to automatically start EiffelStudio after creating a new application. Extend the Traffic Application Creator to generate more types of Traffic applications. Do some testing with students in order to find out if and how the guide and the Traffic Application Creator helps. Rewrite the guide in order to reflect the needs of the students which would have to be determined by the bullet point above. Rewrite the guide in order to reflect the changes made to Traffic in a future release. Write some other guides detailing other aspects of Traffic. 5 Conclusion I have very much enjoyed working with this project. Although there were some problems, eventually everything got fixed and the end result is impressive. Until now I have not worked by my self for a project this large only in teams where we shared previous knowledge with each other. While working alone I discovered that one can achieve some great things even without (much) support from colleagues.

7 Considering what has been done, the project can be considered a success. 6 References [1] [2] [3] 7 Appendices 7.1 Appendix A Appendix A contains a copy of the guide.

8 file://localhost/d:/traffic_doc/guide/index.html Page :31:07 Getting Started Guide INDEX >> GUIDE >> Overview Table of Contents Introduction Intended Audience Installation and Configuration EiffelStudio EiffelMedia Traffic Run example applications Create application from scratch The Traffic library Touch application Touch application by hand Touch application with the Traffic Application Creator New Traffic Application Changes to Traffic INDEX >> GUIDE >> Overview Copyright 2006, Matthias Loeu mailto:mloeu@inf.ethz.ch Last Updated: $Date: :22: (Thu, 14 Dec 2006) $

9 file://localhost/d:/traffic_doc/guide/introduction.html Page :32:02 Getting Started Guide INDEX >> GUIDE >> introduction Introduction Since 2003 the Chair of Software Engineering at the ETH Zurich teaches Introduction to Programming for their first semester students following the ideas of the Inverted Curriculum. It builds around a large piece of software which includes a tool called Traffic. Traffic consists of the Traffic library, as well as some example applications. In this guide I will try to explain how to get your first Traffic example application running and help you create your own Traffic application. Intended Audience INDEX >> GUIDE >> introduction Copyright 2006, Matthias Loeu mailto:mloeu@inf.ethz.ch Last Updated: $Date: :22: (Thu, 14 Dec 2006) $

10 file://localhost/d:/traffic_doc/guide/introduction_audience.html Page :32:09 Getting Started Guide INDEX >> GUIDE >> introduction_audience Intended Audience This guide is intended for students without previous programming knowledge and for those which have not seen Traffic yet. This guide is quite elaborate, so it should also fit for those without much experience using computers. The operating system I am using is Windows XP (32 bit). The exact procedure for other operating systems although similar may differ. INDEX >> GUIDE >> introduction_audience Copyright 2006, Matthias Loeu mailto:mloeu@inf.ethz.ch Last Updated: $Date: :22: (Thu, 14 Dec 2006) $

11 file://localhost/d:/traffic_doc/guide/installation.html Page :32:17 Getting Started Guide INDEX >> GUIDE >> installation Installation and configuration Obviously, the first thing you need to do is to get your copy of Traffic. Traffic itself depends on other software, which you will also have to get a copy of. These are EiffelStudio and EiffelMedia. Please note that the current version of Traffic (Version 3.1) depends on certain versions of that software EiffelStudio 5.7 and EiffelMedia to be specific, it may work on other versions, but I wouldn't count on it. EiffelStudio EiffelMedia Traffic INDEX >> GUIDE >> installation Copyright 2006, Matthias Loeu mailto:mloeu@inf.ethz.ch Last Updated: $Date: :22: (Thu, 14 Dec 2006) $

12 file://localhost/d:/traffic_doc/guide/installation_eiffelstudio.html Page :32:30 Getting Started Guide INDEX >> GUIDE >> installation_eiffelstudio EiffelStudio Traffic is written in a programming language called Eiffel. Although you can write programs with a simple text editor, I strongly recommend against it. EiffelStudio is an Integrated development Environment, which allows you to create, compile, and run applications. As a prerequisite and although not required, I recommend you to install the Microsoft.NET Framework if you don't have it already. You can locate EiffelStudio on the Eiffel Software page or directly on this page: eiffelsoftware.origo.ethz.ch/downloads/builds/. You will have to choose the correct version to download according the operating system you use. I will use the Windows version (Eiffel57_gpl_ windows.msi) and the whole guide will be based on said operating system. Run the EiffelStudio installer as a system administrator and follow the instructions on screen. While installing EiffelStudio you will at one point have to choose which C Compiler you want to use (either Borland Compiler or Microsoft Visual Studio Compiler). It does not matter which one you choose I chose the former but you have to remember which one.

13 file://localhost/d:/traffic_doc/guide/installation_eiffelstudio.html Page :32:30 You have to precompile the Eiffel libraries. If you don't, you will have to do it later. For Traffic, only the Base library is required, however I recommend that you precompile everything (as shown). Get yourself a cup of coffee - precompililation takes quite some time. INDEX >> GUIDE >> installation_eiffelstudio Copyright 2006, Matthias Loeu mailto:mloeu@inf.ethz.ch Last Updated: $Date: :22: (Thu, 14 Dec 2006) $

14 file://localhost/d:/traffic_doc/guide/installation_eiffelmedia.html Page :32:43 Getting Started Guide INDEX >> GUIDE >> installation_eiffelmedia EiffelMedia As with most other modern software, Traffic has some pretty graphics. These are not possible without the EiffelMedia library. If you want to know more about EiffelMedia, please visit the homepage: You will need EiffelMedia 0.8.1, which is available here: There are two versions, depending on your compiler you use for EiffelStudio (see above) you have to download the correct version: em_bcb_0.8.1.exe for the Borland compiler em_msc_0.8.1.exe for the Microsoft compiler Run the installer as a system administrator and follow the on screen instructions. Logoff/logon or restart your computer. Otherwise it will not work! INDEX >> GUIDE >> installation_eiffelmedia

15 file://localhost/d:/traffic_doc/guide/installation_eiffelmedia.html Page :32:43 Copyright 2006, Matthias Loeu mailto:mloeu@inf.ethz.ch Last Updated: $Date: :22: (Thu, 14 Dec 2006) $

16 file://localhost/d:/traffic_doc/guide/installation_traffic.html Page :32:55 Getting Started Guide INDEX >> GUIDE >> installation_traffic Traffic From now on you don't need administrator privileges any more. You can download Traffic from For this guide I will choose traffic_3_1_801_1.zip. Traffic comes in a zip-file and does not need to be installed. Just unpack it to your project folder or any other place you have write and executable permission: 1. Right-click the zip file and choose Extract all 2. Follow the instructions given in the Extraction Wizard

17 file://localhost/d:/traffic_doc/guide/installation_traffic.html Page :32:55 3. You will now have created a folder named traffic_3_1_801. Inside, you will find the (online) documentation, some sample applications and the library itself. 4. Now you're basically done. You can finally start building and running your first application with traffic! INDEX >> GUIDE >> installation_traffic Copyright 2006, Matthias Loeu mailto:mloeu@inf.ethz.ch Last Updated: $Date: :22: (Thu, 14 Dec 2006) $

18 file://localhost/d:/traffic_doc/guide/example.html Page :33:03 Getting Started Guide INDEX >> GUIDE >> example Run example applications Traffic comes with some included applications such as Flat Hunt. They are located in the respective directory under traffic/example. Some of the directories do not contain an application but common files that are used by the applications. These are buildings, image, map and objects. These applications show some of the capabilities of traffic. They all need to be compiled first to run. 1. Start EiffelStudio. 2. In the start dialog choose "Add Project". If the dialog does not appear, click on "File ->New Project...".

19 file://localhost/d:/traffic_doc/guide/example.html Page :33:03 3. This will open a file dialog that lets you choose the *.ecf file of the application you whish to compile. Browse to the directory where the application is located (e.g. D:\traffic\example\flat_hunt), choose the *.ecf file (flat_hunt.ecf) and click on Open. 4. Back in the start dialog, select your project click on "Open". 5. Alternatively, open the folder containing the application you want to start and dobule-click the *.ecf file. This will start EiffelStudio with the wizard.

20 file://localhost/d:/traffic_doc/guide/example.html Page :33:03 6. This will start the compilation of the application. Before doing so you may need to change the Location, however this shouldn't be the case. 7. Go get a coffee. Depending on your computer you may wait a while or an even longer while Once the project is compiled you can execute (debug) it by clicking on the "Debug" button in EiffelStudio or by hitting F5. INDEX >> GUIDE >> example Copyright 2006, Matthias Loeu mailto:mloeu@inf.ethz.ch Last Updated: $Date: :22: (Thu, 14 Dec 2006) $

21 file://localhost/d:/traffic_doc/guide/new.html Page :33:13 Getting Started Guide INDEX >> GUIDE >> new Create application from scratch The easiest way to create a new application is not to actually create one. You can copy an existing application to a new folder and modify it until you get what you want. However some of them may carry a lot of luggage which you don't need, and sometimes it is best to just start with a clean slate. The Traffic library Touch application Touch application by hand Touch application with the Traffic Application Creator New Traffic Application INDEX >> GUIDE >> new Copyright 2006, Matthias Loeu mailto:mloeu@inf.ethz.ch Last Updated: $Date: :22: (Thu, 14 Dec 2006) $

22 file://localhost/d:/traffic_doc/guide/new_traffic.html Page :33:25 Getting Started Guide INDEX >> GUIDE >> new_traffic The Traffic library 1. Start EiffelStudio 2. In the start dialog, in the section Create project choose Basic application (no graphics library included) and click Create. 3. On the next screen, you can choose the name of your application as well as the directory in which all the files are located, if you're done, click OK. 1. I recommend to set the System name, Root cluster and Root class the same, to the name of your application. Unless of course you want to create a Touch Application (see below). The Root feature should remain make.

23 file://localhost/d:/traffic_doc/guide/new_traffic.html Page :33:25 2. Choose the location of your application. I recommend not to set it somewhere inside the Traffic folder as that may lead to some confusion. 4. If you have checked Compile project, EiffelStudio will compile your application, if not click on the Compile button or F7 on your keyboard.

24 file://localhost/d:/traffic_doc/guide/new_traffic.html Page :33:25 5. Open your project settings (the button left of Compile ).

25 file://localhost/d:/traffic_doc/guide/new_traffic.html Page :33:25 6. Click on the Add library button (or press Ctrl-L), select gobo and click OK. This will include the gobo library (part of EiffelMedia) to your application. 7. Now include EiffelMedia itself: Click on Add library, then on Browse. Browse to the location where you have installed EiffelMedia, in the subfolder library there is em.ecf.

26 file://localhost/d:/traffic_doc/guide/new_traffic.html Page :33:25 Select that file and click OK, and again OK. 8. Repeat the above step with Traffic. In the library subfolder select traffic.ecf. 9. Again, compile your application. This will take a while, so go make yourself a cup of tea.

27 file://localhost/d:/traffic_doc/guide/new_traffic.html Page :33:25 Now your application is ready to use the Traffic library. If you run your application you may notice that nothing happens. This is because you didn't actually tell your program what to do, only what it is and where it can find the stuff it needs. INDEX >> GUIDE >> new_traffic Copyright 2006, Matthias Loeu mailto:mloeu@inf.ethz.ch Last Updated: $Date: :22: (Thu, 14 Dec 2006) $

28 file://localhost/d:/traffic_doc/guide/new_touch.html Page :33:33 Getting Started Guide INDEX >> GUIDE >> new_touch Touch application In the textbook A Touch Of Class there are some example applications. The Touch library contains some simplifications so that Traffic does not overwhelm you. Please skip this section if you don't want to use Touch. You can either do everything by hand, the advantage beeing getting a glimpse of how everything connects and works together. Or you can use the provided application to create a Touch application. The application just asks a few things like the name of yor application and does everything by itself. Touch application by hand Touch application with the Traffic Application Creator INDEX >> GUIDE >> new_touch Copyright 2006, Matthias Loeu mailto:mloeu@inf.ethz.ch Last Updated: $Date: :22: (Thu, 14 Dec 2006) $

29 file://localhost/d:/traffic_doc/guide/new_touch_hand.html Page :33:41 Getting Started Guide INDEX >> GUIDE >> new_touch_hand Touch application by hand A Touch application relies (initially) on three classes: a root class, an application class (which is also your root class), a scene class and a class which contains what you want to do. 1. Your class which contains what you want to do should be the same as your system name. In this guide I will call this class the main class. (Of course you can name your classes whatever you want, but for the sake of consistency you should stick to what is given.) For now, you don't have to do anything here. 2. The second class is your root class. Name it NAME_3D_APPLICATION, where NAME is the name of your application and is the same as your root class. In my case it says SAMPLE_3D_APPLICATION. This class will contain the main application code. 3. The third class will be NAME_3D_SCENE. In my case, SAMPLE_3D_SCENE. Eiffel Media, and thus Traffic renders the stuff in scenes, like for example on a DVD. Usually there is a scene for the menu, a scene for the loading -screen, one for the traffic view and so on. Here we will use only one scene to display the 3d map and the toolbars. First, create a new application, then add the Traffic library as described in the section above. Now create the two additional classes as described above. 1. Now we have to include Touch. Go to your project settings, click Add library, click Browse and browse to the location where you have unpacked Traffic. Go to the subfolder library, touch and select touch.ecf. Re-compile your application.

30 file://localhost/d:/traffic_doc/guide/new_touch_hand.html Page :33:41 2. Add the two additional classes described above. They are SAMPLE and SAMPLE_3D_ SCENE here.

31 file://localhost/d:/traffic_doc/guide/new_touch_hand.html Page :33:41 3. Go back to your main class ( SAMPLE ). Now let it inherit from TOURISM. 4. Add the feature explore_on_click. For now it may do nothing.

32 Page 4 5. Go to your root class. Let this class inherit from TOUCH_3D_APPLICATION. Here you have to create two features: 1. The first feature is set_first_scene. Here you have to tell your application which scene is the first one. Since we only have one, there isn't much to choose from, right? 2. 1.The second feature is set_application_specifics. Here you can set the Window title among other things. You have to set the Window title and the application id! If your application is not located in the examples folder inside the Traffic library as I recommend, you also have to set the window icon. file://localhost/d:/traffic_doc/guide/new_touch_hand.html :33:41

33 Page 5 6. Go to your scene class. This class will inherit from TOUCH_3D_SCENE. Additionally, you have to redefine initialize_scene and set the creation feature to make_component_ scene. 7. Create a variable of class main class, in my case SAMPLE. 8. Since we want to redefine initialize_scene, we have to provide the code ourselves: 1. Add this feature. 2. Add the line Precursor. This will execute everything that was previously defined (here in TOUCH_ 3D_SCENE). 3. Create the main class. 4. Add the following lines to hardwire the code in your main class with the scene. file://localhost/d:/traffic_doc/guide/new_touch_hand.html :33:41

34 file://localhost/d:/traffic_doc/guide/new_touch_hand.html Page :33:41 9. Recompile your application. It should not produce any errors. 10. Now try to run your application. It should work...

35 file://localhost/d:/traffic_doc/guide/new_touch_hand.html Page :33:41 INDEX >> GUIDE >> new_touch_hand Copyright 2006, Matthias Loeu mailto:mloeu@inf.ethz.ch Last Updated: $Date: :22: (Thu, 14 Dec 2006) $

36 file://localhost/d:/traffic_doc/guide/new_touch_app.html Page :33:52 Getting Started Guide INDEX >> GUIDE >> new_touch_app Touch application with the Traffic Application Creator This application provides you with everything you need to start your own Touch application. It thus may replace the previous section, however if you do decide to read it, it gives you some insight on how a Touch application works. Please note that you have to make the necessary changes to Traffic if you want to run your Touch application outside the "Traffic/example" folder. Otherwise you will be restricted to said folder. (The existing Touch applications also have this limitation.) 1. Start the Traffic Application Creator. 2. Set the name of your application, as well as the directory it should reside and the directory where you have put Traffic. 3. Click "Generate" and everything else is done for you. When the Application Creator is finished, a message will appear. 4. Go to the directory where your application is. There should be four files there. Double-click on the ".ecf" file to launch EiffelStudio, compile, and run your new application. INDEX >> GUIDE >> new_touch_app Copyright 2006, Matthias Loeu mailto:mloeu@inf.ethz.ch Last Updated: $Date: :22: (Thu, 14 Dec 2006) $

37 file://localhost/d:/traffic_doc/guide/new_app.html Page :34:04 Getting Started Guide INDEX >> GUIDE >> new_app New Traffic Application First, include libraries. See above. 1. root class: inherit em_application, traffic_3d_constants 2. create new class for scene, inherit from em_component_scene 3. in root_class: init video subsystem, set scene, launch 4. in scene: make_component_scene 5. should work now, displays nothing though 6. add widgets to scene... INDEX >> GUIDE >> new_app Copyright 2006, Matthias Loeu mailto:mloeu@inf.ethz.ch Last Updated: $Date: :22: (Thu, 14 Dec 2006) $

38 file://localhost/d:/traffic_doc/guide/changes.html Page :34:14 Getting Started Guide INDEX >> GUIDE >> changes Changes to Traffic There are some bugs in the release version (3.1) of Traffic. Most of the bugs don't affect the user directly. Two however I have to point out since your application might not work: This bug is fixed in the developement version of Traffic and thus presumably also in any future release. If you create a Touch application and save it somewhere outside the "/ traffic/example" folder your application crashes because an icon is missing/not where it thinks it is. There are various solutions/workarounds to this problem: (you need only apply ONE of the points listed below!) In TOUCH_3D_APPLICATION: remove line 43 (set_window_icon...) Make a copy of the icon at the location stated on line 43 in the class TOUCH_3D_APPLICATION, relative to where your application is. Again, if you create a Touch application outside the example folder of the Traffic application your application crashes because it searches for some images which are not at the expected place any more. I don't know of a good solution, a workaround is to either copy the "buildings" folder to where your application is or to change lines 54, 61, 120 and 128 of the class TRAFFIC_3D_BUILDING_FANCY_FACTORY to reflect the path changes. For example, if the Traffic library is on "D:\traffic", you have to replace the two dots ".." with "D:\traffic\example" on all of the lines stated above. There are a few other similiar bugs. If you are unsure why your application crashes, try placing it in the "example" folder in the Traffic library. INDEX >> GUIDE >> changes Copyright 2006, Matthias Loeu mailto:mloeu@inf.ethz.ch Last Updated: $Date: :22: (Thu, 14 Dec 2006) $