Difference between revisions of "Repository HOWTO"

From AIRWiki
Jump to: navigation, search
(Created page with "=Contents of the repository= AIRLab stores the source code of the software developed in the Lab in [https://svn.ws.dei.polimi.it/showproject.plp?p=airlab this Subversion repos...")
 
m
Line 4: Line 4:
  
 
The repository is subdivided into two separate sections:
 
The repository is subdivided into two separate sections:
#'''generic_libraries''' containing software packages that implement single robot functionalities in the form of libraries for general use. Each library must be a stand-alone package with its own Makefile, to be compiled separately.
+
#'''generic_libraries''' containing software packages that implement single robot functionalities in the form of libraries for general use. Each library must be a stand-alone package with its own Makefile, to be compiled separately. A generic library is ''not'' intended to be used "as is". Instead, you have to set up one or more ROS nodes that use the library. The source code for a "generic" ROS node template of this kind may be provided within the library.
 
#'''specific_modules''', containing software packages that are dedicated to specific robots (or other devices). Each package can take one of the following forms:
 
#'''specific_modules''', containing software packages that are dedicated to specific robots (or other devices). Each package can take one of the following forms:
 
##A complete [[ROS_HOWTO | ROS package]] implementing all the functionalities of the device, able to operate on its own as a ROS system (including launchfiles);
 
##A complete [[ROS_HOWTO | ROS package]] implementing all the functionalities of the device, able to operate on its own as a ROS system (including launchfiles);
 
##One or more [[ROS_HOWTO | ROS nodes]] implementing one of the functionalities of the device, ready for integration into larger ROS systems but not able to operate on their own as ROS systems;
 
##One or more [[ROS_HOWTO | ROS nodes]] implementing one of the functionalities of the device, ready for integration into larger ROS systems but not able to operate on their own as ROS systems;
 
##a special-purpose ''software library'' which is dedicated to the device, the function of which is too specialized for inclusion in the ''generic_libraries'' section of the repository. In this case it is '''mandatory''' to provide, along with the library, a ''ROS wrapper'' in the form of one or more ROS nodes: the ROS wrapper is the '''only''' allowed method to access the library.
 
##a special-purpose ''software library'' which is dedicated to the device, the function of which is too specialized for inclusion in the ''generic_libraries'' section of the repository. In this case it is '''mandatory''' to provide, along with the library, a ''ROS wrapper'' in the form of one or more ROS nodes: the ROS wrapper is the '''only''' allowed method to access the library.
 
=Rules to use the repository=
 
Whoever develops software for AIRLab must comply with the following criteria for software design and inclusion in the Subversion repository.
 
 
#'''Everything must be sufficiently documented.'''
 
Software is considered "sufficiently documented" if the following condition is verified.
 
::Any person with generic experience in robotics and programming but no idea whatsoever of what the software does must be able, after reading only the files available within the software (including accompanying documents and comments at the head of source code files), to do all of the following:
 
::* understand what the software is for;
 
::* understand what each individual file belonging to the software is for;
 
::* understand how the functionalities of the software can be used (by other software);
 
::* compile the software.
 
#'''A valid test application must be provided.'''
 
A test application must be present in a separate directory (called ''test_application'') within the software. It must be possible to remove such directory without altering the functionalities of the software, and without damaging the possibility to compile the software. The test application is considered "acceptable" if the following condition is verified.
 
::Any person with generic experience in robotics and programming but no idea whatsoever of what the software does must be able, after reading only the documentation provided with the software, to do all of the following:
 
::* compile and run the test application;
 
::* configure the test application (if required);
 
::* understand the functioning of the test application and interpret its output;
 
::* verify, using only the test application, if ''every'' functionality of the software is correctly operating.
 
  
 
=Structure of the repository=
 
=Structure of the repository=
Line 33: Line 15:
 
*'''generic_libraries'''
 
*'''generic_libraries'''
 
**behavior
 
**behavior
**''brian''
+
***''brian''
 
**fuzzy
 
**fuzzy
 
***''fuzzy''
 
***''fuzzy''
Line 60: Line 42:
 
**''wheelchair''
 
**''wheelchair''
 
**''spikee''
 
**''spikee''
 +
 +
 +
 +
=Rules to use the repository=
 +
Whoever develops software for AIRLab must comply with the following criteria for software design and inclusion in the Subversion repository.
 +
 +
#'''Everything must be sufficiently documented.'''
 +
Software is considered "sufficiently documented" if the following condition is verified.
 +
::Any person with generic experience in robotics and programming but no idea whatsoever of what the software does must be able, after reading only the files available within the software (including accompanying documents and comments at the head of source code files), to do all of the following:
 +
::* understand what the software is for;
 +
::* understand what each individual file belonging to the software is for;
 +
::* understand how the functionalities of the software can be used (by other software);
 +
::* compile the software.
 +
#'''A valid test application must be provided.'''
 +
A test application must be present in a separate directory (called ''test_application'') within the software. It must be possible to remove such directory without altering the functionalities of the software, and without damaging the possibility to compile the software. The test application is considered "acceptable" if the following condition is verified.
 +
::Any person with generic experience in robotics and programming but no idea whatsoever of what the software does must be able, after reading only the documentation provided with the software, to do all of the following:
 +
::* compile and run the test application;
 +
::* configure the test application (if required);
 +
::* understand the functioning of the test application and interpret its output;
 +
::* verify, using only the test application, if ''every'' functionality of the software is correctly operating.

Revision as of 16:43, 3 April 2013

Contents of the repository

AIRLab stores the source code of the software developed in the Lab in this Subversion repository. In order to ease code reuse, usage of such repository must be done according to some rules. This page illustrates the rules.

The repository is subdivided into two separate sections:

  1. generic_libraries containing software packages that implement single robot functionalities in the form of libraries for general use. Each library must be a stand-alone package with its own Makefile, to be compiled separately. A generic library is not intended to be used "as is". Instead, you have to set up one or more ROS nodes that use the library. The source code for a "generic" ROS node template of this kind may be provided within the library.
  2. specific_modules, containing software packages that are dedicated to specific robots (or other devices). Each package can take one of the following forms:
    1. A complete ROS package implementing all the functionalities of the device, able to operate on its own as a ROS system (including launchfiles);
    2. One or more ROS nodes implementing one of the functionalities of the device, ready for integration into larger ROS systems but not able to operate on their own as ROS systems;
    3. a special-purpose software library which is dedicated to the device, the function of which is too specialized for inclusion in the generic_libraries section of the repository. In this case it is mandatory to provide, along with the library, a ROS wrapper in the form of one or more ROS nodes: the ROS wrapper is the only allowed method to access the library.

Structure of the repository

The following is a template for the structure of the AIRLab Subversion source code repository. Elements in italic are examples (i.e., actual software modules developed in AIRLab).

  • generic_libraries
    • behavior
      • brian
    • fuzzy
      • fuzzy
    • obstacle
    • motor_control
    • multi_robot
      • scare
    • odometry
    • planning
      • spike
    • play_media
    • pose
      • airlab_artoolkit
    • safety
      • airlab_remote
    • sensor
      • laser
        • airlab_hokuyo
      • sonar
        • airlab_sonar_board
      • vision
        • airlab_prosilica
  • specific_modules
    • triskar2
    • wheelchair
    • spikee


Rules to use the repository

Whoever develops software for AIRLab must comply with the following criteria for software design and inclusion in the Subversion repository.

  1. Everything must be sufficiently documented.

Software is considered "sufficiently documented" if the following condition is verified.

Any person with generic experience in robotics and programming but no idea whatsoever of what the software does must be able, after reading only the files available within the software (including accompanying documents and comments at the head of source code files), to do all of the following:
  • understand what the software is for;
  • understand what each individual file belonging to the software is for;
  • understand how the functionalities of the software can be used (by other software);
  • compile the software.
  1. A valid test application must be provided.

A test application must be present in a separate directory (called test_application) within the software. It must be possible to remove such directory without altering the functionalities of the software, and without damaging the possibility to compile the software. The test application is considered "acceptable" if the following condition is verified.

Any person with generic experience in robotics and programming but no idea whatsoever of what the software does must be able, after reading only the documentation provided with the software, to do all of the following:
  • compile and run the test application;
  • configure the test application (if required);
  • understand the functioning of the test application and interpret its output;
  • verify, using only the test application, if every functionality of the software is correctly operating.