wiki/howto/ignore-missing-gwt-sdk-warning.png
... ...
Binary files /dev/null and b/wiki/howto/ignore-missing-gwt-sdk-warning.png differ
wiki/howto/ignore-package-not-exported-warning.png
... ...
Binary files /dev/null and b/wiki/howto/ignore-package-not-exported-warning.png differ
wiki/howto/onboarding.md
... ...
@@ -1,17 +1,5 @@
1 1
# OnBoarding Information
2 2
3
-<!--
4
-This Markdown document is designed to work with Gollum not with GitHub. Internal links to chapters have the following syntax in for Gollum:
5
-
6
-Chapter Hierachy:
7
-# chapter
8
-## new chapter
9
-### chapter to reference
10
-## another chapter
11
-
12
-[linkText](#chapter_new-subchapter_chapter-to-reference)
13
- -->
14
-
15 3
This document describes the onboarding process for a new team member (developer)
16 4
17 5
First of all, make sure you've looked at [http://www.amazon.de/Patterns-Elements-Reusable-Object-Oriented-Software/dp/0201633612](http://www.amazon.de/Patterns-Elements-Reusable-Object-Oriented-Software/dp/0201633612). That's a great book, and knowing at least some of it will help you a great deal finding your way around our solution.
... ...
@@ -43,26 +31,25 @@ First of all, make sure you've looked at [http://www.amazon.de/Patterns-Elements
43 31
### Installations
44 32
45 33
1. JDK >= 11, it is required by Eclipse and therefore should be referenced in the environment variable `JAVA_HOME`. As an alternative to the environment variable Eclipse can be configured to use a different version of Java see [here](https://stackoverflow.com/questions/18469170/how-to-run-eclipse-with-different-java-version) for further instructions.
46
-2. Eclipse IDE for Eclipse Committers, version 4.24.0 ["2022-06"](https://www.eclipse.org/downloads/packages/release/2022-06/r/eclipse-ide-eclipse-committers)
47
-3. JDK 1.8 (Java SE 8), ideal is the SAPJVM 1.8: Go to [https://tools.eu1.hana.ondemand.com/#cloud](https://tools.eu1.hana.ondemand.com/#cloud), scroll down to `SAP JVM` select your operating System, extract the downloaded .zip into desired location (e.g. Windows `C:\Program Files\Java`
48
-4. Git (e.g. Git for Windows v2.18), [http://git-scm.com](http://git-scm.com) / [https://git-for-windows.github.io](https://git-for-windows.github.io)
49
-5. Configure git (see [Git repository configuration essentials](#onboarding-information_sap-sailing-analytics-development-setup_git-repository-configuration-essentials))
50
-6. MongoDB (at least Release 4.4), download: [https://www.mongodb.com/](https://www.mongodb.com/)
51
-7. RabbitMQ, download from [http://www.rabbitmq.com](http://www.rabbitmq.com). Requires Erlang to be installed. RabbitMQ installer will assist in installing Erlang. Some sources report that there may be trouble with the latest versions of RabbitMQ. In some cases, McAffee seems to block the installation of the latest version on SAP hardware; in other cases connection problems to the newest versions have been reported. We know that version 3.6.8 works well. [https://github.com/rabbitmq/rabbitmq-server/releases/tag/rabbitmq_v3_6_8](https://github.com/rabbitmq/rabbitmq-server/releases/tag/rabbitmq_v3_6_8)
52
-8. Maven 3.1.1 (or higher), [http://maven.apache.org](http://maven.apache.org)
34
+2. Eclipse IDE for Eclipse Committers, version 4.15.0 ["2021-03"](https://www.eclipse.org/downloads/packages/release/2021-03/r/eclipse-ide-eclipse-committers)
35
+3. JDK 1.8 (Java SE 8), ideal is the SAPJVM 1.8: Go to [https://tools.eu1.hana.ondemand.com/#cloud](https://tools.eu1.hana.ondemand.com/#cloud), scroll down to `SAP JVM` select your operating System, extract the downloaded .zip into desired location (e.g. Windows `C:\Program Files\Java`), then open Eclipse and navigate to Window → Preferences → Java → Installed JREs and add the 1.8 VM.
36
+4. Install the eclipse plugins (see [Automatic Eclipse plugin installation](#onboarding-information_sap-sailing-analytics-development-setup_automatic-eclipse-plugin-installation))
37
+5. Configure Eclipse (see [Tuning the Eclipse Installation](#onboarding-information_sap-sailing-analytics-development-setup_tuning-the-eclipse-installation))
38
+6. Git (e.g. Git for Windows v2.18), [http://git-scm.com](http://git-scm.com) / [https://git-for-windows.github.io](https://git-for-windows.github.io)
39
+7. Configure git (see [Git repository configuration essentials](#onboarding-information_sap-sailing-analytics-development-setup_git-repository-configuration-essentials))
40
+8. MongoDB (at least Release 4.4), download: [https://www.mongodb.com/](https://www.mongodb.com/)
41
+9. RabbitMQ, download from [http://www.rabbitmq.com](http://www.rabbitmq.com). Requires Erlang to be installed. RabbitMQ installer will assist in installing Erlang. Some sources report that there may be trouble with the latest versions of RabbitMQ. In some cases, McAffee seems to block the installation of the latest version on SAP hardware; in other cases connection problems to the newest versions have been reported. We know that version 3.6.8 works well. [https://github.com/rabbitmq/rabbitmq-server/releases/tag/rabbitmq_v3_6_8](https://github.com/rabbitmq/rabbitmq-server/releases/tag/rabbitmq_v3_6_8)
42
+10. Maven 3.1.1 (or higher), [http://maven.apache.org](http://maven.apache.org)
53 43
A setup guide for windows can be found on this webpage: [https://maven.apache.org/guides/getting-started/windows-prerequisites.html](https://maven.apache.org/guides/getting-started/windows-prerequisites.html)
54
-9. GWT SDK 2.9.0 ([http://www.gwtproject.org/download.html](http://www.gwtproject.org/download.html))
44
+11. GWT SDK 2.9.0 ([http://www.gwtproject.org/download.html](http://www.gwtproject.org/download.html))
55 45
Download the gwt sdk and extract it to a location of your preference (e.g. windows `C:\Program Files\gwt`)
56
-10. Standalone Android SDK (see section "Additional steps required for Android projects"). OPTIONALLY: You may additionally install Android Studio ([https://developer.android.com/tools/studio/index.html](https://developer.android.com/tools/studio/index.html)) or IntelliJ IDEA ([https://www.jetbrains.com/idea/download/](https://www.jetbrains.com/idea/download/)).
46
+12. Standalone Android SDK (see section "Additional steps required for Android projects"). OPTIONALLY: You may additionally install Android Studio ([https://developer.android.com/tools/studio/index.html](https://developer.android.com/tools/studio/index.html)) or IntelliJ IDEA ([https://www.jetbrains.com/idea/download/](https://www.jetbrains.com/idea/download/)).
57 47
Make sure that the environment variable `ANDROID_HOME` is set (e.g. Windows C:\Users\\**'user'**\AppData\Local\Android\Sdk )
58
-11. Get the content of the git repository
48
+13. Get the content of the git repository
59 49
Clone the repository to your local file system from `ssh://[SAP-User]@git.wdf.sap.corp:29418/SAPSail/sapsailingcapture.git` or `ssh://trac@sapsailing.com/home/trac/git` User "trac" has all public ssh keys.
60
-
61
-12. Install the eclipse plugins (see [Automatic Eclipse plugin installation](#onboarding-information_sap-sailing-analytics-development-setup_automatic-eclipse-plugin-installation))
62
-12. Configure Eclipse (see [Tuning the Eclipse Installation](#onboarding-information_sap-sailing-analytics-development-setup_tuning-the-eclipse-installation))
63
-13. Configure Maven to use the correct JRE by following the instructions in the paragraph [maven-setup](#onboarding-information_sap-sailing-analytics-development-setup_maven-setup)
64
-14. Follow the instructions in the [development setup](#onboarding-information_sap-sailing-analytics-development-setup_sap-sailing-analytics-development-setup) to build the project.
65
-15. The steps for building the project for a deployment can be found in the [Build for deployment](#onboarding-information_sap-sailing-analytics-development-setup_build-for-deployment) section. This is not needed in the daily development workflow and should only be run when needed.
50
+14. Configure Maven to use the correct JRE by following the instructions in the paragraph [maven-setup](#onboarding-information_sap-sailing-analytics-development-setup_maven-setup)
51
+15. Follow the instructions in the [development setup](#onboarding-information_sap-sailing-analytics-development-setup_sap-sailing-analytics-development-setup) to build the project.
52
+16. The steps for building the project for a deployment can be found in the [Build for deployment](#onboarding-information_sap-sailing-analytics-development-setup_build-for-deployment) section. This is not needed in the daily development workflow and should only be run when needed.
66 53
67 54
### Further optional but recommended installations
68 55
... ...
@@ -72,27 +59,17 @@ First of all, make sure you've looked at [http://www.amazon.de/Patterns-Elements
72 59
3. kdiff3 (git tool)
73 60
4. Firebug (javascript & .css debugging, included in Firefox Developer Tools in newer versions of Firefox by default)
74 61
62
+### Automatic Eclipse plugin installation
75 63
64
+The necessary Eclipse plugins described above can be automatically be installed into a newly unzipped version of ["2021-03"](https://www.eclipse.org/downloads/packages/release/2021-03/r/eclipse-ide-eclipse-committers) by using the script "./configuration/installPluginsForEclipse2021-03.sh". In addition, the script applies some updates to plugins packaged with Eclipse itself. To start the plugin installation, run the following command using your Eclipse installation directory as command line parameter for the script:
76 65
77
-### Git repository configuration essentials
78
-
79
-The project has some configuration of line endings for specific file types in ".gitattributes". To make this work as intended, you need to ensure that the git attribute "core.autocrlf" is set to "false". This can be done by navigating to your local repository in a Bash/Git Bash/Cygwin instance and executing the command `git config core.autocrlf false`.
80
-
81
-If you are first time git user, don't forget to specify your user metadata. Use the commands `git config user.name "My Name"` and `git config user.email my.email@sap.com` to tell git your name and email address.
82
-
83
-Depending on the location of your local repository, it's filepaths might be too long for the default settings to handle. Excecute the command `git config --system core.longpaths true` to enable your system wide git installation to handle long file paths.
84
-
85
-### Maven Setup
86
-
87
-Copy the settings.xml **and** the toolchains.xml from the top-level git folder to your ~/.m2 directory. Adjust the proxy settings in settings.xml accordingly (suggested settings for corporate network inside). Set the paths inside of toolchains.xml to your JDKs depending on where you installed them (this is like setting the compiler for your IDE, but for Maven; This makes it possible to build with the same Maven configuration on every system). Make sure the mvn executable you installed above is in your path.
88
-
89
-### Automatic Eclipse plugin installation
66
+ ./installPluginsForEclipse2021-03.sh "/some/path/on/my/computer/eclipse"
90 67
91
-The necessary Eclipse plugins described above can be automatically be installed into a newly unzipped version of ["2022-06"](https://www.eclipse.org/downloads/packages/release/2022-06/r/eclipse-ide-eclipse-committers) by using the `./configuration/pluginsForEclipse2022-06.p2f` file. To install the plugins open Eclipse and install Software Items from File. (File ⇒ Import ⇒ Install ⇒ Install Software from File). The description file is located at `/configuration/pluginsForEclipse2022-06.p2f`. Skip the installation details and Accept the licence agreements. While Eclipse is installing the plugins in the background a pop-up will appear where you need to trust all plugins. Be aware that the installation may take several minutes depending on your Internet connection.
68
+Be aware that with this script it's not possible to update the plugins to newer versions. Instead, you can install a new version by unpacking the base package and executing the script.
92 69
93
-Be also aware that with this p2f-file it's not possible to update the plugins to newer versions.
70
+Be aware hat the installation may take several minutes depending on your Internet connection. When the script finished running, please check that no errors occurred (the installation process only logs warnings/errors but doesn't fail).
94 71
95
-The p2f-file includes the following plugins for your convenience:
72
+The script will install the following plugins for your convenience:
96 73
97 74
- GWT Plugin ([https://github.com/gwt-plugins/gwt-eclipse-plugin](https://github.com/gwt-plugins/gwt-eclipse-plugin))
98 75
- GWT SDM Debug Bridge ([http://sdbg.github.io/](http://sdbg.github.io/))
... ...
@@ -102,32 +79,60 @@ The p2f-file includes the following plugins for your convenience:
102 79
- UMLet ([https://www.umlet.com/](https://www.umlet.com/))
103 80
- various updates to preinstalled plugins
104 81
82
+#### On Windows
83
+
84
+You need a Git Bash or Cygwin shell to run the script. The default path of Eclipse on Windows is: `C:/Users/'user'/eclipse//committers-2021-03/eclipse`
85
+
86
+#### On Mac OS:
87
+
88
+- Before running the script, start eclipse and install **GWT Plugin** manually from repository [http://storage.googleapis.com/gwt-eclipse-plugin/v3/release](http://storage.googleapis.com/gwt-eclipse-plugin/v3/release)
89
+- It's not sufficient to provide the path to the app, instead you need to get the path to the directory inside of the app package hosting the "eclipse" binary (.../Eclipse.app/Contents/MacOS).
90
+
105 91
### Tuning the Eclipse Installation
106 92
107 93
Out of the box, two settings in Eclipse avoid a clean workspace. Go to Window - Preferences and change the following two settings:
108 94
109
-- In "General ⇒ Content Types" select on CSS (Text ⇒ CSS) and add \*.gss in the lower file association list to get limited syntax highlighting and content assist in GSS files
110
-- In "General ⇒ Editors ⇒ TextEditors" check Insert Spaces for Tabs
111
-- In "GWT ⇒ Errors/Warnings" set "Missing SDK" to "Ignore"
112
-- In "GWT ⇒ GWT Settings ⇒ Add..." add the GWT SDK
113
-- In "Java ⇒ Build Path ⇒ Classpath Variables" create a new classpath variable called `ANDROID_HOME`. Set its value to the installation location of your Android SDK, e.g., `C:\Users\'user'\AppData\Local\Android\Sdk` or `/usr/local/android-sdk-linux`.
114
-- In "Java ⇒ Code Style ⇒ FormatterImport" import the CodeFormatter.xml from $GIT_HOME/java
115
-- In "Java ⇒ Compiler" set the Compiler compliance level to 1.8
116
-- In "Java ⇒ Installed JREs" add the Java 8 sdk and activate it.
117
-- In "Java ⇒ Installed JREs ⇒ Execution Environments" make sure that the Java 8 JRE is selected for JavaSE-1.8 (if the jre is not listed open and close the preference Window once)
118
-- In "Web ⇒ Client-side JavaScript ⇒ Formatter" import the CodeFormatter_JavaScript.xml for JavaScript from $GIT_HOME/java to ensure correct formatting of JavaScript Native Interface (JSNI) implementations.
119
-- In "Web ⇒ HTML Files ⇒ Editor" activate indent using Spaces
120
-- In "XML(Wild Web Developer) ⇒ Validation & Resolution ⇒ Enable Validation" Disable the Checkbox
121
-- Install Eclipse eGit (optional)
95
+- Set the "Missing GWT SDK" warning to "Ignore". See screenshot below.
96
+
97
+![](ignore-missing-gwt-sdk-warning.png)
98
+
99
+- Set the "Plug-in does not export all packages" warning to "Ignore". See screenshot below.
100
+
101
+![](ignore-package-not-exported-warning.png)
102
+
103
+### Git repository configuration essentials
104
+
105
+The project has some configuration of line endings for specific file types in ".gitattributes". To make this work as intended, you need to ensure that the git attribute "core.autocrlf" is set to "false". This can be done by navigating to your local repository in a Bash/Git Bash/Cygwin instance and executing the command `git config core.autocrlf false`.
122 106
107
+If you are first time git user, don't forget to specify your user metadata. Use the commands `git config user.name "My Name"` and `git config user.email my.email@sap.com` to tell git your name and email address.
108
+
109
+Depending on the location of your local repository, it's filepaths might be too long for the default settings to handle. Excecute the command `git config --system core.longpaths true` to enable your system wide git installation to handle long file paths.
110
+
111
+### Maven Setup
112
+
113
+Copy the settings.xml **and** the toolchains.xml from the top-level git folder to your ~/.m2 directory. Adjust the proxy settings in settings.xml accordingly (suggested settings for corporate network inside). Set the paths inside of toolchains.xml to your JDKs depending on where you installed them (this is like setting the compiler for your IDE, but for Maven; This makes it possible to build with the same Maven configuration on every system). Make sure the mvn executable you installed above is in your path.
123 114
124 115
### Steps to build and run the Race Analysis Suite
125 116
126 117
1. Check out the 'master' branch from the git repository. The 'master' branch is the main development branch. Please check that you start your work on this branch.
127 118
2. Setup and configure Eclipse
119
+
120
+ - Make absolutely sure to import CodeFormatter.xml (from $GIT_HOME/java) into your Eclipse preferences (Window ⇒ Preferences ⇒ Java ⇒ Code Style ⇒ Formatter)
121
+ - It is also strongly recommended to import CodeFormatter_JavaScript.xml (from $GIT_HOME/java) into your Eclipse preferences (Window ⇒ Preferences ⇒ Web ⇒ Client-side JavaScript ⇒ Formatter) to ensure correct formatting of JavaScript Native Interface (JSNI) implementations.
122
+ - In Eclipse go to "Window ⇒ Preferences ⇒ Java ⇒ Build Path ⇒ Classpath Variables" and create a new classpath variable called `ANDROID_HOME`. Set its value to the installation location of your Android SDK, e.g., `C:\Users\'user'\AppData\Local\Android\Sdk` or `/usr/local/android-sdk-linux`.
123
+ - Add the SDK in Eclipse (Preferences ⇒ GWT ⇒ GWT Settings ⇒ Add...)
124
+ - In "Window ⇒ Preferences ⇒ GWT ⇒ Errors/Warnings, set "Missing SDK" to "Ignore" (If not done earlier, see: Tuning the Eclipse Installation)
125
+ - In "Window ⇒ Preferences ⇒ General ⇒ Editors ⇒ TextEditors" check Insert Spaces for Tabs
126
+ - In "Window ⇒ Preferences ⇒ Web ⇒ HTML Files ⇒ Editor" indent using Spaces
127
+ - In "Window ⇒ Preferences ⇒ General ⇒ Content Types" select on the right side CSS, now add in the lower file association list \*.gss to get limited syntax highlighting and content assist in GSS files
128
+ - In "Window ⇒ Preferences ⇒ XML(Wild Web Developer) ⇒ Validation & Resolution ⇒ Enable Validation" Disable the Checkbox
129
+ - Install Eclipse debugger for GWT SuperDevMode
130
+ - Install Eclipse eGit (optional)
131
+ - Check that JDK 1.8 is available and has been set for compilation in Eclipse
132
+ - Check that JDK 1.8 has been matched to JavaSE-1.8 ("Window ⇒ Preferences ⇒ Java ⇒ Installed JREs ⇒ Execution Environments ⇒ JavaSE-1.8)
128 133
- Import all Race Analysis projects from the `java/` subdirectory of the git main folder (make sure to import via the wizard [but without smart import] "Import ⇒ General ⇒ Projects from Folder or Archive" in Eclipse, and additionally make sure to scan for nested projects!)
129 134
- Import all projects from the `mobile/` subdirectory of the git main folder; this in particular contains the race committee app projects
130
- - In "Window ⇒ Preferences ⇒ Plug-in Development ⇒ Target Platform" set the Eclipse target platform to `Race Analysis Target` (located in com.sap.sailing.targetplatform/definitions//race-analysis-p2-remote.target)
135
+ - Set the Eclipse target platform to race-analysis-p2-remote.target (located in com.sap.sailing.targetplatform/definitions) Window ⇒ Preferences ⇒ Plug-in Development ⇒ Target Platform select `Race Analysis Target`
131 136
- Wait until the target platform has been resolved completely
132 137
- Rebuild all projects
133 138