Computer Labs 2013/2014 - 1st Semester
Lab 0: LCOM Development environment

1. Objectives

The objectives of this lab are threefold. First to introduce you to Redmine, a project management tool. Second, to create a project on Redmine for your LCOM group. Third to introduce you to the development environment that will be used throughout this course.

This is not a programming lab, although you'll be asked to write a short program in order to achieve the third goal mentioned above.

Essentially, you have to do the following:

1. Create a Redmine project for your group
2. Develop a short program of your choice on Minix and test it

2.1 Class Preparation

This lab class is not very demanding. Nevertheless, it will be more productive if you do some homework before. In particular, I suggest that you watch the following Redmine tutorials on YouTube:

Redmine Intro - 1 - Logging In

Just to get an idea of Redmine. Details in FEUP are different, as detailed below.

Redmine Intro - 2 - Managing Users

Very useful, as you'll have to add members to the project in a very similar way

Redmine Intro - 3 - Repositories

Just to get an idea of Redmine. Details in FEUP are different, as detailed below.

Redmine - Guided Tour

Overview of some redmine features useful for tracking a project's activity. You don't have to use them, but you may wish to play with them.

You should also read the overview of the development environment in LCOM, so that you can more easily use it during the lab class.

Redmine is a Web-based project management tool. Although it can be used for the management of general projects it is specially suited for the management of software projects.

Most Redmine's functionality is provided by modules that you can enable/disable as needed on a per project basis. You can even temporarily disable a module and later reenable it, without loss of the data that module kept for your project.

In LCOM you are required to use the following two Redmine modules:

Repository

This is the main functionality we are interested in. In FEUP, by enabling this module you link your project to a Subversion (SVN) repository, which can be used to keep track of your source code. We will introduce the capabilities of SVN in a later lab, for now it suffices to say that it enables you to keep several versions of your source code, so that you can easily try new ideas and undo them if they do not work as expected.

Documentation

This is a module that allows to manage a project documentation. You will have to use it for the documentation (Proposal, Specification and Final Report) of your final integration project.

As for the other modules, e.g. Issues or Wiki, you are not required to use them, but we recommend that you take advantage of this opportunity to explore the capabilities of a Project Management Tool. Please check the 4th YouTube video listed above for an overview of the use of some of those modules in the management of SW projects.

3.0 Logging in Linux

In the I304 lab, the development environment for LCOM is installed in Linux under user lcom, whose password is lcom1234.

Although Redmine is a Web-based application, and therefore you can perform all the steps in this Section from any Web client, if you wish to use the I304 computers you must first login Linux as user lcom.

Once logged in, you can fire-up a web-browser and point it to https://redmine.fe.up.pt/.

IMP.- Every time you login in the lcom account of the lab's computers, its disk area is restored to a cleaned up state. This is done to ensure that if its contents is damaged for some reason, it will be recovered the next time you login. There are however at least two issues with this solutions. First, the login may take a while (about a minute) as the account is restored. Second, if for some reason you logout without saving your changes, these will be lost. In one of the future classes, we will discuss the use of the SVN repository to reduce possible damages in this event.

In order to use Redmine in FEUP, you must register first. This is done automatically when you log in for the first time in https://redmine.fe.up.pt/, by clicking on the Sign in on the top right of the wellcome page of FEUP's Redmine and entering your SIGARRA's credentials (username and password).

If the login is successful, the web browser will show a form that you will need to fill in with your personal data, in particular your given name, your family name(s) and email address. The names you provide are essential as they are used for adding members to a project, as described below. If you have an uncommon name please enter it, even if you seldom use it: it makes it easier to search for you.

Throughout this semester each group will use a single Redmine Project. This Project will be used not only for the final integration project but also for each of the lab classes. Thus, your first task is to create a Redmine project for your group.

Note: Project creation needs to be done by only one group member. There must be only one Redmine project per group. Therefore only one group member needs to follow the remaining instructions in this Section.

IMPORTANT Please follow the instructions in this section very carefully. This is very important to ensure that we will find your submissions where we expect them to be. If not, we will not be able to grade them and therefore you will get no credit for your work. This may look too harsh, but there are more than 70 groups in the course and if each group decided to place its submission where it pleased it, we would waste a lot of time just to get a copy of your submitted work. We need you to help us make a productive use of our time; you will also benefit from it. Thanks.

In order to create your group's project, once you are logged in FEUP's Remine, select the Projects link at the top left of the Web page.

Once on the Projects-page, select the New project link on the top right of the white region of the page.

This will show the New Project form:

Name

This is the name of your project. For the sake of uniformity your project's name must be LCOM1314-TnGxy where

n

is the section number (número da turma)

xy

is a two digit group number, e.g. 01 or 10. (This may look picky, but by using a two digit group number we can more easily sort the groups by their number.) The number of your group should be chosen according to the I304 computer you are using, as shown in the lab plan below. Please be careful to avoid "stealing" the number of a neighbor group. If another group used "your" group number, Redmine will complain, and you should ask the groups around you if they are using your group number, and if so, you should use the number that group should have used.

Identifier

This is an internal identifier that is also used in the URL of the SVN repository. For the sake of uniformity, this must be identical to the project name, but in lower case. E.g. if the name of the group determined by the above rules is LCOM1314-T1G03 then the identifier must be lcom1314-t1g03.
IMP. the project identifier is unique and it cannot be modified after the project has been created. Be extra careful when entering this field, and double check that you are following the rules stated.

Please leave the Public box unchecked: this ensures that only project members have access to your project. This is important to prevent other students to take unfair advantage of your hard work. It is your responsibility to prevent this from happening, and we may penalize your grade if another group submits your code as theirs.

Furthermore you must select the Repository module, by checking the respective box. This is critical so that the SVN repository is automatically created together with the project.

To avoid mistakes, I suggest that you leave the other boxes with their default values. As already mentioned, you can enable/disable them later, if needed.

You can now click on the "Create" button, to create your Redmine project. The project will be created immediately, but the creation of the SVN repository may take a few minutes as it is done by a script that is run periodically in the background. In any case, you won't need to use the repository until the next week. So you need not wait: you can check if the repository was correctly created after the next task, i.e. adding the project members.

3.3 Adding Project Members

Whoever created the Redmine project will be automatically added as a project member in the role of Manager. If you are the manager, you should now add the other project members, and specify their roles.

The role of a member is used for access control and determines which operations the group member may perform. Redmine supports 3 roles, whose main capabilities of interest are as shown in the following table:

A project member may have more than one role.

Your project will have mainly two types of members:

Group members

These are the members of your LCOM group. You can assign all the group members the Manager and Developer roles.

Course instructors

These are all course instructors, not only the instructor of your class section, as we will distribute the grading tasks among us. Therefore, we all must have read access to your project, and thus you should assign us the Reporter role.

In order to add members to the group you have to select the Settings tab of your newly created project. It looks like this:

Inside that tab you need to select the Members tab, which will bring a page like the following:

At this point you should add one member at a time. In order to select a member you should enter one or more names that member provided when (s)he registered on Redmine (see Section 3.1) or their email addresses. By selecting carefully that name, you should get a sufficiently short list to scan. Once you have found the desired user, check the corresponding box and select their roles by checking the appropriate boxe(s). (You must specify at least one role. Failing to do that, may block further access to Redmine in the same browser session.) Finally, you must click on the Add button to add that user as a member with the chosen role(s).

The name of the instructors of the course are as follows (in bold, the suggested search names):

• Bruno Laranjo dos Santos (dee12013)
• Diogo Varajão (dee12010)
• Filipe Amaro Coelho (pro08008)
• Tiago Marques (pro11013)
• Pedro Ferreira do Souto (pfs)

As already mentioned, you can also search for an instructor (or any other user) by their email addresses, which areshown between parenthesis.

3.4 Checking the SVN Repository

Adding the group members should have taken more than enough time for the SVN repository to be created. Therefore, you can check now if everything is working as expected. To do that select the Settings tab of your project again.

Inside that tab you need to select the Repositories tab, which will bring a page like the following:

That is, your project should have a Subversion repository configured with the following URL: https://svn.fe.up.pt/repos/lcom1314-tngxy, where the last component lcom1314-tngxy is the identifier you should have given to your project.

If you find no Repositories tab, and you created your project more than 15 minutes ago, go to the Modules tab of the Settings tab of the project to check if the Repository module has been selected. If not, check it again, and check if the repository was created a few minutes later.

If after several attempts, the Repositories tab has not been created, you may have to visit CICA's helpdesk so that they fix the problem for you.

If you find a Repositories tab, but the URL is not as specified, check the identifier you have chosen for your project. If it is not as specified above, you made a mistake in the input of the project identifier. Please follow the instructions in Annex 1 to fix this.

You should also check the name of your project. If it is not as specified above, please follow the instructions in Annex 2 to correct the name of your project.

4. Starting the VMware Player with Minix 3.1.8

Most of your development will be performed using the Minix image on a virtual machine (VM) rather than the Minix image on disk. In the remaining of this handout we will describe how you can develop a program in the image on the VM. Therefore, whenever we mention Minix we mean the Minix 3.1.8 image on the VM.

If you have not read the short introduction on LCOM's development environment, now is a good time to do it.

If you are using the lab's computers, the VM is available in Linux under user lcom. Therefore, first you must login as user lcom. Its password is lcom1234.

Once logged in, you can start the VMWare player. Just select Unity's Dash, on the top of the left vertical panel, Unity's Launcher.

You should get a window like the following, with the icon of the most recently used applications, including VMware Player and Eclipse. If the application you are looking for does not show up, you can type its name in the search box.

To start the VMWare Player just click on its icon. A VMware Player's window should appear on the screen:

Now, to start the VM with Minix, select the File menu on top, and then select the "Open a Virtual Machine" option. This will display the folders with a VM (each folder has only one VM).

Select the only available folder, this will display its content.

Now click the "Open" button. Finally, in VMware Player's window, click on the "Play virtual machine" button.

This should start the VM with Minix 3.1.8 installed that you will use to run your programs. You may get a succession of warnings like the following that you can safely ignore (click on hte OK button, if needed).

Eventually, you will get Minix's bootloader menu, which looks like this:

You need not do anything. It will start booting Minix in a few seconds. And after a few other seconds you will get, Minix's login screen.

As described in the introduction to LCOM's development environment, in Minix there are two accounts lcom and root, both of which with password lcom. The Minix installation has only a command line interface (CLI), and you can login directly on the VMwarePlayer window, as you would on a computer terminal. But before, as indicated by the message at the bottom of VMware Player window, you need to place the mouse cursor on that window and press Ctrl+G so that the keyboard input is forwarded to the VM. An alternative is to click the mouse's left button, but it does not always work. To get the keyboard/mouse input forwarde to Linux, you will have to press Ctrl+Alt, as displayed in a message at the bottom of VMware Player's window.

Pressing Ctrl+G and Ctrl+Alt to go back and forward between Minix and Linux is somewhat inconvenient. Thus, you may wish to use ssh on a Linux terminal instead. This is described in more detail in the introduction to LCOM's development environment already mentioned.

Either way, to edit the source files of your programs, you may wish to use a modern integrated development environment (IDE) like Eclipse with the Remote System Explorer (RSE) plugin. This is described in the next section.

Note: Do not power off the VM, as you'll need it to use the RSE plugin.

5. Using Eclipse's Remote System Explorer Plugin

Eclipse's RSE plugin is described in its User Guide as follows:

Basically, the RSE plugin allows you to edit files that are stored on a remote system. In LCOM, in the computers of the I304 lab, you will run it (or better Eclipse) on Linux and use it to edit files on the Minix installation running on the VMware Player. You can use it also to run the compiler and to run the compiled programs, although I prefer to use ssh on a Linux terminal for that. Of course, your preferences may be different.

5.1 Running Eclipse on Linux

To run the RSE plugin, you need to start Eclipse. Again, you can find Eclipse using Unity's Dash on Ubuntu Linux, following the steps described above to run the VMware Player.

Eclipse will start immediately in the RSE perspective, which is already configured to connect to Minix 3 on the VMWare Player.

5.2 Using the RSE plugin to work on Minix

You can use the RSE view on the left to browse lcom's user space on Minix, labeled My Home, or the Minix root file system, labeled Root. The lcom's user space on Minix contains only a few hidden files and they will not be shown, therefore My Home appears empty. (It is possible to change this behavior, but there is no need in LCOM to see hidden files.) The following snapshot shows the content's of Minx's root directory.

By clicking on My Home with the mouse's right button, Eclipse will show up a menu. By clicking the New entry, a submenu that allows you to create a new file or a new folder is shown. I suggest that you create first a directory (folder) named lab0 for this lab. The RSE view will show the new directory under My Home

Now, move to that directory and create a new file, with name hello.c. A file with this name will now appear in the RSE view under the lab0 folder. To edit it, double click with the mouse's left button. This will show an empty canvas in the middle of the Eclipse window. You can now write an "Hello World" program.

To compile and run the new program you need a CLI (shell) on Minix. There are at least 4 alternatives to get one:

1. The Minix console on VMwarePlayer
2. A remote shell on a Linux terminal, by using ssh
3. A remote terminal using Eclipse's RSE
4. A remote shell using Eclipse's RSE

The latter behaves in an unusual way. Therefore, if you wish to use Eclipse's RSE, select the Ssh Terminals under the minix connection. You will get an remote terminal inside Eclipse's window, as shown:

You can use several remote shells simultaneously, one per Linux terminal. These shells can be used together with the remote terminal available via RSE.

Anyway, to compile an run your program, on the CLI of your choice, just execute the following commands:

You may wish to try using multiple remote terminals/shells. For example, use one to compile your program, and another to run it.

Note: The Minix 3 image also has a couple of text-based editors, including vim, a somewhat sophisticated editor (although I'm not a vim user and do not now which features are supported in Minix's version), and nano, a simple and easy to use editor. You can use them directly from Minix CLI either on the VMwarePlayer or by running ssh on a Linux terminal or even on RSE ssh terminals (do not try to run them on RSE's ssh shell.) My advice is that you stick to Eclipse's default editor.

This all for today, folks. But if you wish, you can try to set up LCOM's development environment on your own laptop.

6. Setting Up LCOM's Development Environment

Essentially, LCOM's development environment consists of:

1. Minix 3.1.8 running on a VM
2. Eclipse with the C development tools (CDT) and the RSE plugin

In the I304 lab this environment is setup in Linux, but you can set it up in Windows or in MacOS as well. (Either directly on these OSs, or by running a VM with Linux.) Furthermore, we are using VMware Player as VM, although in previous years some students have also used the VirtualBox, especially under MacOS, as there is no VMware Player for MacOS, and VMware Fusion is not free.

The Windows Virtual PC from Microsoft may also be an alternative under Windows, but according to the Wikipedia this is already two years old, which may mean that either this is a superb program or that Microsoft has lost interest in this product. (Pick your choice.)

Thus, the steps you need to set up LCOM's development environment are as follows:

1. Download and install a VM (both VMwarePlayer and VirtualBox were used successfully in the past) for your OS.
2. Download the my VMwares's image with Minix 3.1.8 (I've changed the kernel slightly, the standard Minix 3.1.8 will not work for LCOM's labs)
3. Import the VMware's image with Minix 3.1.8 to the VM you chose
4. Download and install Eclipse with the C Development Tools (CDT) and the RSE plugin. These tools/plugin can be installed by selecting the "Install New Software" option of the Help drop down menu in Eclipse. If you are installing on Linux, it may be more convenient to install the appropriate SW packages of your Linux distribution.
5. Configure the RSE plugin to connect to the Minix image on the VM

Have fun!

If you made a mistake and the project identifier you entered does not follow the rules we have specified, it is still possible fix things by creating a new project: as stated above, a project identifier cannot be changed, once assigned.

If you made a mistake only on the project identifier, that is the project name is correct, you need first to change the name of the first project you created, e.g. by appending the string "-OLD" to that name, as described below. This is because although you can change a project's name, it must be unique.

If you made a mistake on the project name as well, you can "forget" about that project an all you have to do is to create a new one, with the right name and identifier, by following exactly the instructions provided in Section 3.2.

Fixing a wrong project name is easy. All you have to do is to select the Settings tab, and then the Information tab and finally edit the Name text-box, and change it to the correct name.

To make you changes effective, just click on the Save button.