TODO: Improve this documentation
Jira | ||||||
---|---|---|---|---|---|---|
|
Table of Contents |
---|
Start here if you are setting up a brand new development environment, or want to reconfigure your environment from scratch.
Requirements:
The instructions below assume you already have available:
A recent version of IntelliJ. These steps have been validated on IntelliJ 2020.2.2
JDK 1.8 installed and configured in IntelliJ
A local git clone of the apache/beam repository in your home directory ("~/beam")
- ChromeDriver installed and running (chromedriver --port=4444)
- Flutter installed
- Dart installed (version >=3.0.2 <4.0.0)
- The script local-env-setup.sh (Located at the root of the project)ran before importing the project
To set up your IntelliJ project:
- Launch the New Project wizard by
...
- closing your project File |
...
- Close Project.
...
In the New Project wizard, select Empty Project and click Next.
- Then click Open from the splash page to open a new project (Depending on what version of IntelliJ you may need to find an option to "Import project" instead)
- Select the settings.gradle.kts in the root of your beam git repo
You shouldn't need to modify the project settings. But you should double check on the Java SDK version. File → Project Structure Project → Settings
...
This will create the initial project and bring up the Project Structure settings.
In the Project pane, set the Project SDK to "1.8", and select Apply.
In the Modules pane, click the + and select Import Module. Select your beam repository ("~/beam") and select OK.
In the Import Module wizard, select Import module from external model, then select Gradle. Then select Next.
On the next screen, ensure that Create separate module per source set and Use default gradle wrapper (recommended) are selected, and keep the rest of the default values. Then select Finish.
In the Problems pane, ensure there are no issues listed, then select Apply and OK.
Note: If the 1.8 SDK is not displayed, Download Java 8 and extract it (to any location) from the tar.gz option on the Oracle website.
Then add it under Platform Settings → SDKs-> + icon. (Removing other SDKs if you don't need them will help eliminate potential issues, but isn't required).
(Also set it up so that java -version uses this SDK on the command line. By setting up your PATH and JAVA_HOME properly to refer to the same location (And remove other java installation files, if necessary))
Double check these settings (but they shouldn't need to change) This will close the wizard and cause IntelliJ to begin syncing project structure in the background. Continue configuring the IDE while the project syncs:
Open File | Settings... In left pane, navigate to Build, Execution, Deployment | Build Tools | Gradle | Runner. Select Delegate IDE build/run actions to gradle. Then , and Run tests using: Gradle Test Runner. Then select Apply and OK.
Open View | Tool Windows | Gradle to open the Gradle pane.
...
You may also want to setup a specialized environment for the Beam modules you're working on:
Children Display
Previous documentation
The documentation below needs to be rechecked and reorganized. This is a work-in-progress. Jira server ASF JIRA serverId 5aa69414-a9e9-3523-82ec-879b028fb15b key BEAM-5764
Create a working Gradle module
(as of IntelliJ 2018.1.6)
- Create an empty IntelliJ project outside of the Beam source tree.
- Under File > Project Structure > Project, select a Project SDK.
- Under File > Project Structure > Modules, click the + sign to add a module and select “Import Module”.
- Select the directory containing the Beam source tree.
- Tick the “Import module from external model” button and select Gradle from the list.
- Tick the following boxes.
- Create separate module per source set
- Use default gradle wrapper
- Delegate build actions to Gradle by going to FIle > Settings/Preferences > Build, Execution, Deployment > Build Tools > Gradle > Runner and checking “Delegate IDE build/run actions to gradle”.
This should result in a working Gradle project. Build the project by executing the “build” task in the root Gradle module.
Checkstyle
IntelliJ supports checkstyle within the IDE using the Checkstyle-IDEA plugin.
Note: Older versions of IntelliJ may not support the Checkstyle file used by Beam.
- Install the “Checkstyle-IDEA” plugin from the IntelliJ plugin repository
- Configure the plugin by going to Settings -> Other Settings -> Checkstyle
- Set Checkstyle version to the same as in
/build_rules.gradle
(e.g. 8.7) - Set the “Scan Scope” to “Only Java sources (including tests)”
- In the “Configuration File” pane, add a new configuration using the plus icon:
- Set the “Description” to “Beam”
- Select “Use a local Checkstyle file”, and point it to
sdks/java/build-tools/src/main/resources/beam/checkstyle.xml
within your repository - Check the box for “Store relative to project location”, and click “Next”
- Configure the
checkstyle.suppressions.file
property value tosuppressions.xml
, and click “Next”, then “Finish”
- Select “Beam” as the only active configuration file, and click “Apply” and “OK”
- Checkstyle will now give warnings in the editor for any Checkstyle violations
You can also scan an entire module by opening the Checkstyle tools window and clicking the “Check Module” button. The scan should report no errors.
Note: Selecting “Check Project” may report some errors from the archetype modules as they are not configured for Checkstyle validation.
Code Style
Uniform formatting for Java and Groovy code is automated by the build through the Spotless Gradle plugin. Instead of relying on the IDE, now you can run ./gradlew spotlessApply
to reformat changes prior to commit.
If you want to autoformat in the same way while you are developing, use the Google Java Format plugin.
Code Insight Feature Problems
...
Make sure to set the formatting options. Otherwise IntelliJ will make unnecessary changes.
File → Settings → Editor → Code Style → Java → Tabs and Indents
Make sure the settings match below:
Also disable "*" style imports
File → Settings → Editor → Code Style → Java → Imports
Set Class count to use import with '*'; to 999
Set Names count to use static import with '*'; to 999
Issues when building:
When building the project with IntelliJ, you may encounter some issues, here is the fix for each issue:
Flutter finished with non-zero exit value 1:
When you get this issue, you should make sure that ChromeDriver is installed and running with the command chromedriver --port=4444 and duplicate or rename the file config.example.dart to config.g.dart in the folder playground/frontend/lib.
If you want to see exactly what cause the issue, you can ran just the task that failed. For this example, you could ran the task as the following: ./gradlew integrationTest_standalone_change_example_sdk_run and see the error message.
If you got as an error message the following, then you should only rename the file config.example.dart to config.g.dart
If you got this error message, then you should run ChromeDriver with the following command chromedriver --port=4444
Info | ||
---|---|---|
| ||
Note: You should keep ChromeDriver running until the build is finished. |
Cannot find symbol class Module:
if you got this error, you can try following solutions:
- Make sure to set the language as the following screen shot (The class Module is only available starting from Java 9+)
- Clean & rebuild the project
Try invalidating the IntelliJ cache and restarting the IDE, using
File > Invalidate caches/ restart
Delete the .idea & .gradle project and rebuild or reimport the project
Can't resolve generated AutoValue classes AutoValue_*:
To fix this issue, you should enable annotation processing in IntelliJ. For that, you will need to go
File → Settings → Build, Execution, Deployment → Compiler → Annotation Processors
And check "Enable annotation processing" as in the following image.
After that, you will need to run the build of that specific module. If for example, you want to work on "ElasticsearchIO", you will need to open gradle sidebar,
beam → Tasks → sdks → io → elasticsearch
...
In IntelliJ 2016 and higher: go to Help → Edit Custom Properties → Paste the following inside the properties file:
Code Block | ||
---|---|---|
| ||
#---------------------------------------------------------------------
# Maximum file size (kilobytes) IDE should provide code assistance for.
# The larger file is the slower its editor works and higher overall system memory requirements are
# if code assistance is enabled. Remove this property or set to very large number if you need
# code assistance for any files available regardless their size.
#---------------------------------------------------------------------
idea.max.intellisense.filesize=2500 |
...