src/site/apt/getting-started.apt

   1                 ------
   2                 Setting up a Taxonomic Editor development environment
   3                 ------
   4                 n.hoffmann
   5                 ------
   6
   7
   8 Setting up a Taxonomic Editor development environment
   9
  10         This document describes all steps necessary to create a development environment to develop the EDIT Taxonomic Editor. If you are looking for
  11         instructions on how to install the EDIT Taxonomic Editor please consult the {{{./manual.html} manual}}.
  12
  13         <Table of Contents>
  14
  15 %{toc|section=0|fromDepth=2|toDepth=3}
  16
  17 * Requirements
  18
  19         The current version of the EDIT Taxonomic Editor is developed using the Eclipse IDE for RCP developers.
  20
  21
  22 * Checking out the sources
  23
  24         Use git to check out the sources from the EDIT repository to a location on your development machine.
  25
  26 ---
  27 $ git clone https://dev.e-taxonomy.eu/git/taxeditor.git
  28 $ git clone ssh://git@dev.e-taxonomy.eu/var/git/taxeditor.git
  29 ---
  30
  31         This will leave you with a directory <<<taxeditor/>>> containing everything that is needed. We will have a look at the contents later on.
  32
  33 * Setting up eclipse
  34
  35         * Start up eclipse and open a workspace.
  36
  37         * Open up the Import Wizard via <File -\> Import...> from the menu
  38
  39         * Choose <General -\> Existing projects into Workspace > and click next.
  40
  41         * Check <Select Root Directory> and browse to the <<<taxeditor/>>> directory. After confirming the directory selection dialog, the <Projects> list should contain a number of projects all starting with
  42         <<<eu.etaxonomy.taxeditor>>> which should be checked for import.
  43
  44         * Click <Select All> to finish the wizard and import the projects into your workspace.
  45
  46         You should now be able to see the taxeditor projects in your workspace.
  47
  48 * Dependencies
  49
  50         The Taxonomic Editor uses <maven 3> for convenient configuration and automation of common tasks,
  51         such as resolving dependencies and automating builds.
  52
  53         We have two modules that use maven for dependency resolution: cdmlibrary and the molecular module.
  54
  55         The <<<latest snapshot branch>>> of the Taxonomic Editor is programmed against the latest
  56         SNAPSHOT version of the cdmlibrary. Because that dependency will change quickly, we
  57         do not include it with the other dependencies but rather install it with maven.
  58
  59         In order to do that you have to run <<<mvn validate>>> in your <<<taxeditor/eu.etaxonomy.taxeditor.cdmlib>>> and <<<taxeditor/eu.etaxonomy.taxeditor.molecular.lib>>> directory.
  60
  61 ---
  62 $ cd taxeditor/eu.etaxonomy.taxeditor.cdmlib/
  63 $ mvn validate
  64 $ cd taxeditor/eu.etaxonomy.taxeditor.molecular.lib/
  65 $ mvn validate
  66 ---
  67
  68     The maven pom.xml provides a special profile which you may want to use if you are developing the cdmlib at the same time. This profile, named <<<local-repository>>>, causes maven to always use the local maven repository, so the latest changes to the cdmlib which have been installed locally by <<<mvn install>>>  will be used. In order to use this profile you would execute the validate gloal differently:
  69
  70  ---
  71  $ mvn -P local-repository  -Dlocalrepo=/home/${youUserName}/.m2/repository validate
  72  ---
  73
  74         This will take some time, as maven will download the required dependencies.
  75
  76
  77         After maven has finished follow these steps:
  78
  79         The UI is implemented using a fixed version of SWT. So please follow the steps to correctly set the  {{{https://dev.e-taxonomy.eu/redmine/projects/edit/wiki/TaxonomicEditorDevelopersGuide#Target-RCP-Environment}Target-RCP-Environment}}
  80
  81         To get rid of the errors, you have to update the classpaths of all plugin projects. To do this right-click any of the <taxeditor-*> projects and choose <PDE Tools -\> Update Classpath...>. Select All plugins except taxeditor.webapp  and confirm. After a rebuild of your entire workspace all errors should be gone and you are ready to go.
  82
  83         <<Note>>: If you have also checked out the cdmlib sources you may have to run <<<mvn install>>> on the cdmlib project beforehand to update the cdmlib jars in your local maven repository.
  84
  85
  86
  87 * Bundle overview
  88
  89         Let's have a quick look at some important projects:
  90
  91 ** <eu.etaxonomy.taxeditor.store>
  92
  93         This package communicates with cdmlib-service directly, offering all services, basic operations on cdm data as well as import export functionality. Database and user management is also contained in this package.
  94
  95 ** <eu.etaxonomy.taxeditor.navigation>
  96
  97         The <Taxon Navigator> as well as the <Search> view are located in this plugin.
  98
  99 ** <eu.etaxonomy.taxeditor.editor>
 100
 101         Everything that has to do with editing taxa or specimens or data that is connected to those resides in this plugin. This includes the <Name Editor>, the <Specimen Editor>, the <Details View>,
 102         the <Supplemental View>, the <Descriptive Data View> as well as the <Media View>. All interface elements that are used in the <taxeditor-bulkeditor> plugin are
 103         also located here.
 104
 105 ** <eu.etaxonomy.taxeditor.bulkeditor>
 106
 107         The different bulkeditors are in this plugin.
 108
 109 ** <eu.etaxonomy.taxeditor.molecular>
 110
 111         This plugin provides editors and views for working with phylogenetic data like single reads and consensus sequences. This includes the <Alignment Editor>, the <Pherogram View> and export functionality.
 112
 113 ** <eu.etaxonomy.taxeditor.molecular.lib>
 114
 115         Manages the external dependencies for the molecular plugin.
 116
 117 ** <eu.etaxonomy.taxeditor.webapp>
 118
 119         Provides all remoting facilities i.e. manages the internal CDM Server to connect to remote data sources.
 120
 121 ** <eu.etaxonomy.taxeditor.printpublisher>
 122
 123         This plugin is a frontend and GUI for the <cdmlib-print> module. Please see the {{{http://wp5.e-taxonomy.eu/printpublisher/}according documentation}} for further information.
 124
 125 ** <eu.etaxonomy.taxeditor.application>
 126
 127         This plugin bundles all the previous plugins into an application and configures the look and feel.
 128
 129 ** <eu.etaxonomy.taxeditor.cdmlib>
 130
 131         As said before, <cdmlib> dependecies reside in this plugin. Please also note that this plugin does not contain any sourcecode.
 132
 133 ** <eu.etaxonomy.taxeditor.feature.platform>
 134
 135         A feature containing all dependencies for the eclipse platform.
 136
 137 ** <eu.etaxonomy.taxeditor>
 138
 139         The product configuration for the standalone application.
 140
 141 ** <eu.etaxonomy.taxeditor.test>
 142
 143         Automated GUI Tests for the Taxonomic Editor that can be run with {{{http://eclipse.org/swtbot/}SWTBot}}.
 144
 145 * Creating a launch configuration
 146
 147         To start the Taxonomic Editor from your newly created development environment you need to create a launch configuration.
 148
 149         * Expand <eu.etaxonomy.taxeditor> and open <<<eu.etaxonomy.taxeditor.product>>>
 150
 151         * In the <Testing> section (down left) click on <Launch an Eclipse application in Debug mode>
 152
 153         The Taxonomic Editor should launch. Note: You might want to tweak the launch configuration, e.g. increase the memory.
 154
 155 * Where do I go from here?
 156
 157         Please read the {{{http://dev.e-taxonomy.eu/trac/wiki/TaxonomicEditorDev}wiki}} for how-to's and code examples.