Difference between revisions of "AirBAT Instructions"

Revision as of 01:04, 27 March 2009

AirBAT is a repository containing software developed in projects related to the BioSignal Analysis area.

Becoming a member

AirBAT is based on Subversion; you can find some help in configuring Subversion in the Configuring Subversion page.

Students who need to work with AirBAT should:

1. Register an account on DEI Savane.
2. Ask to become member of the AirBAT project:
   • Login and go to the "My Group" page (link in the top left corner).
   • Search for "AirBAT" and request membership. Please state clearly who you are and what you are working on, so the administrators can identify and authorize you.
3. Create and upload a personal Ssh key on Savane (see Configuring Subversion).
4. Read the Using Subversion paget and the other sections below, which contain important information.
5. Wait until your membership is approved (this may take from one minute to about one day, depending on the load of the administrators).
6. Check out the repository and start working (if you have read the documentation, you should know what "check out" means and how to do it).

1-2 days may pass after the uploading of Ssh key before it becomes effective and you can start using the repository. This depends on how the server is setup, so please be patient.

Structure

This is a very brief overview of the directory hierarchy of the repository. The root contains these directories:

• AffectiveComputing: software for analysis of biological signals for BioSignal Analysis
• Robot: software used for the control of the robots built to generate different level of stress in users
• bci: software for analysis of EEG used for Brain-Computer Interfaces. There are a common directory and a directory for each person.
  • common: contains files and programs that could be useful to others, e.g., Matlab functions to load data. The subdirectory java contains (as you guessed) Java software, while the subdirectory matlab contains Matlab scripts and functions.
  • There are also directories for each person (or group) working on BCI, named after the persons. The stuff in these directories is "private", i.e., only the owner should modify things there and they may contain work in progress, programs still badly documented or incomplete... These directories are not secret and not intended to be so. Moreover, they are also writable by other users, as the repository doesn't enforce any such policy; but it is slightly rude to modify files on which others are working.
• lurch: software used for the Lurch project.

Rules

The project depends on the collaborative effort of people; these rules are not strict laws enforced by the AirBAT police, but guidelines to make an effective use of the tools. In summary, you can break them, but you have to have a good reason to do that :-). If you think that some policy could be made better, please tell your advisor or co-advisor.

Please note that this section has been written by Bernardo Dal Seno, but no one has said that any rule is bad yet

Subversion should be used only for source files; so, no executables, object files (.o, .obj), archives (e.g., .jar, .zip) and other binary files. The reason for the repository is to keep track of versions and share your work with other people; computer-generated files are no good for this.

Makefiles or project files are definitely source files, as they contain directions for the compiler. So please add them to the repository. If you are in doubt about which files are used, try to copy the files on another machine and see which files are needed in order to correctly edit and compile the project. See #Project Files for some known files.

If your project needs some external file or library, don't add it to the repository, but say so in a README and put a link to where to find the library. The repository remains cleaner, it is clearer what is your contribution, and it is easier to upgrade to a new version of the external library.

If you want to share binaries, e.g., the executable of the latest version of your project, the best place is probably your project page on this Wiki.

Versioned and unversioned files can live side-by-side in the local copy on your PC. That means, for example, that you can compile source files in your local copy, just avoid adding whole directories if they contain binary files; Subversion commands are recursive by default, so add individual files instead. Using the local copy as your working space and checking in frequently (e.g., every day) is the most effective way to exploit the power of version control systems. Don't be afraid to mistakes; everything in the repository history can be retrieved, so irreparable losses are not possible. Whatever you don't check in, though, can be lost. Check in frequently! (or should I tell you how some people have lost 1-month worth of work?)

For the bci hierarchy, where a common directory exists, some additional care is needed before committing: you don't want to commit a broken function that you have not yet debugged, as your fellows working on a different project could be hurt (or you may be hurt, if they revert your changes). You have two options: either you postpone committing until you have finished debugging (but you lose the advantages of the version control system), or you use branching. For branching, do a copy with the Subversion copy command (svn cp from the command line) from the common directory to your own, and use the copy until you are finished changing. After the debugging is complete, you do a final commit, and then you can import your changes with the merge command; don't just overwrite the old copy in common, unless you are sure nobody changed it after the branching.

Project Files

Here the project files used by some IDEs are reported. Please help to make the list longer and more accurate. (The parts in italic are supposed to be substituted by actual names.)

Eclipse (Java projects)

project_dir / .classpath

project_dir / .project

Borland C++

project_dir / project_name.bdsproj