Skip to content

Developer Documentation

Jump to bottom
Michael Jastram edited this page Nov 19, 2015 · 10 revisions

Table of Contents

Setting up the development environment

To set up a development environment for the openETCS tool, perform the following steps:

  1. Download the Eclipse Modeling Tools (Luna SR2)
  2. Import the Eclipse projects from this git repository.
    A tutorial on how to configure Egit may be found here.
    1. From Menu File>Import... select Git>Project from Git
    2. Choose "Clone URI"
    3. Get the URL of your repository
    4. Choose a protocol (e.g. https or ssh)
    5. Choose the branch you want to clone and where the local copy will be set on your computer.
    6. Click Import existing project and select a project.
  3. Set the target platform. It's located in org.openetcs.releng.target/openETCS-Luna.target
The target platform defines what need to be build to create the openETCS product.
  1. To run openETCS as configured, use org.openetcs.releng.products/openETCS.product
    1. *Note:* A lot of components will be missing if run "as is". Therefore, follow these steps to run the product through Eclipse:
    2. Open openETCS.product and click "Launch an Eclipse application" from the "Overview" page.
    3. Just close it right away after it started.
    4. Now edit the Run configuration via "Run | Run Configurations..."
    5. Select the correct run configuration in the left pane: "Eclipse Application | openETCS.product"
    6. Select the tab "Plug-ins"
    7. In the "Launch with" dropdown, select "all workspace and enabled target plug-ins"
    8. That's it (launch with run). You have to do this only once.
To Build the OpenETCS product
  1. Install latest Maven
  2. Run Maven in the org.openetcs.releng.parent
     mvn clean verify

OpenETCS Project description

The openETCS core product definition is made of the following project

  • org.openetcs.releng.parent: use for the maven build
  • org.openetcs.releng.products: List of included features, branding, licencing ...
  • org.openetcs.releng.target: Definition of the target platform
  • org.openetcs.target.feature: Collection of features that should be included in the target platform
  • org.openetcs.core.feature : ??
  • org.openetcs.product: OpentETCS start up definition, splash screen ..
  • org.openetcs.intro: Welcome page definition

Project Name Convention

  • A project name will have the prefix org.openetcs.

Guidelines for plugin integration

A plugin should contain:

  • Feature and Use cases description
  • documentation
  • basic tests description
To include a new plugin and its unit test project into the build of openETCS product it is necessary to follow these steps:
  • Store the plugin and its unit test project in toolchain bundle
  • Update pom.xml file in org.openetcs.releng.parent project. Add the needed modules to execute the plugin and the unit tests projects. See the following example image for the documentation plugin.










  • Run mvn clean verify (Maven) in org.openets.releng.parent directory to export OpenETCS product and execute the unit tests.



Guidelines for license and credit information





A tool embeded into the toolchain must have an opensource  licence compatible with the the European 
Union Public Licence (EUPL), Version 1.1.



Note that using external tool into a unified GUI is not considered as a derivative work of the tool in used. Thus GPL tool may be included in the toolchain without having to change the toolchain license.



Extra care must be take when developing new part of the tool chain, for example as mentioned by @astante :
The LGPL is used for libraries that will be linked with a program. One example is the GNU Libc. If such a license would be GPL, then every C program compiled with gcc and which is linking against the libc would be derivative work, that must provide it source code. The LGPL basically grants the user to right to change the linked LGPL library with another version. If the program is dynamically linked, you can just distribute your binary. If your program is statically linked, the object files must be distributed, to allow the end user the change. A problem arise if library code is inlined or generated during compilation (e.g. C++ templates). For that reason, the GNU libstdc++ library is not under the LGPL but under GCC Runtime Library Exception.






License Template





The license should be stored as an html or a text file  in the root folder of each project, in a file named LICENSE.txt or .html.

/*
 * Copyright (c) 2014 [NAME OF THE OTIGINAL AUTHOR OR AUTHORS]
 *
 * The contents of this [TYPE OF ARTEFACT, e.g. file] are under the European 
 * Union Public Licence (EUPL), Version 1.1.
 * You may not use this file except in compliance with the License.
 * You may obtain a copy of the License at:
 *      https://joinup.ec.europa.eu/software/page/eupl/licence-eupl
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and 
 * limitations under the License.
 *
 * Contributor(s):
 *   [Name of Contributor(s)]
 */






License template for Eclipse new feature





For a new feature or plug-in in eclipse platform the following information should be provided in the feature.xml file:







    

  • Feature Description (optional url and text)
    • 

  • Copyright Notice (optional url and text)
    • 

  • License Agreement (shared license, local license, optional url and text)
    • 

  • Sites to visit
    • 



<?xml version="1.0" encoding="UTF-8"?>
<feature
      id="org.openetcs.[featureName].feature"
      label="[Short feature title]"
      version="0.1.0.qualifier">

   <description>
      [
          Feature description
      ]
   </description>

   <copyright>
      Copyright (c) [NAME OF THE OTIGINAL AUTHOR OR AUTHORS]
   </copyright>

   <license url="https://joinup.ec.europa.eu/system/files/EN/EUPL%20v.1.1%20-%20Licence.pdf">
      European Union Public Licence
                                     V.1.1
                      EUPL © the European Community 2007

This European Union Public Licence (the “EUPL”) applies to the Work or Software
(as defined below) which is provided under the terms of this Licence. Any use of the
Work, other than as authorised under this Licence is prohibited (to the extent such use
is covered by a right of the copyright holder of the Work).

The Original Work is provided under the terms of this Licence when the Licensor (as
defined below) has placed the following notice immediately following the copyright
notice for the Original Work:

                         Licensed under the EUPL V.1.1

or has expressed by any other mean his willingness to license under the EUPL.
   </license>

   <url>
      <discovery label="OpenETCS Project Site" url="http://www.openetcs.org"/>
      <discovery label="[Feature Name] Project Site" url="[Site to visit]
   </url>

 ...






Git Management







  • Each new plug-in should  (not already integrated) should have an associated issue  named: 


          [Plugin Name] Integration to the OpenETCS toolchain






  • The commit that performs the integration should close this issue 


          git commit -m "[message] closes #Number"





    

  • All bugs and feature request related to a plug-in should be referenced in the issue tracker.
    • 

  • All commit that fix one or more issue should refer to them.
    • 



              


          



  
          

            


            
Clone this wiki locally