1 # Building Jalview from Source
7 git clone http://source.jalview.org/git/jalview.git
12 java -jar build/libs/jalview-all-*-j11.jar
14 # and/or create launcher
17 cd ./build/getdown/files/11
18 java -jar getdown-launcher.jar . jalview
24 > To get set up using _only_ the Eclipse IDE (<https://www.eclipse.org/>) then please see the section [Setting up in Eclipse IDE](#setting-up-in-eclipse-ide)
26 The method here is described assumes using a command line. You can easily do this on linux or in a Terminal window in macOS. You can do it in Windows.
28 * Java 11 compliant JDK
29 * gradle 7.6.3 or above, but not gradle 8
32 > The versions and installation methods here are just suggestions (which we have tested
33 so are known to work). If you need or wish to use different implementations (particularly
34 you might need a bespoke JDK if you are on an exotic architecture) then the general
35 build instructions should work with any gradle 5+. You should be able to compile the
36 bytecode with any JDK Java 11+. The resulting bytecode (in particular the shadow jar)
37 should be runnable in any JRE Java 1.8+. Remember that because Jalview and the getdown launcher
38 are Java bytecode you can build on one system where you might have gradle, and run
39 on another where you don't (JRE 1.8+ required).
41 ### Java 11 compliant JDK
44 We recommend obtaining an OpenJDK JDK 11 (since 11 is the long term support release) from AdoptOpenJDK: <https://adoptopenjdk.net/?variant=openjdk11&jvmVariant=hotspot>, either the *Installer* or `.zip`/`.tar.gz` variants whichever you prefer (if you're not sure, choose the *Installer*).
46 >##### Alternative/CLI install of AdoptOpenJDK 11
48 >You can also install adoptopenjdk11 using either `brew` (macOS), `choco` (Windows)
49 (see the section on `gradle` and `git` for more informaiton on `brew` and `choco`)
50 or `yum` or `apt` (Linux):
52 >###### alternative for MacOS and Homebrew
54 >brew tap adoptopenjdk/openjdk
55 >brew cask install adoptopenjdk11
58 >###### alternative for Windows and Chocolatey
60 >choco install adoptopenjdk11
63 >###### alternative for Linux with yum/apt
65 >see <https://adoptopenjdk.net/installation.html#linux-pkg>
69 You should be able to install the latest (or sufficiently recent) versions of gradle and git using your OS package manager.
72 we recommend using `brew`, which can be installed following the instructions at <https://brew.sh/>.
73 After installing `brew`, open a Terminal window and type in (using an Administrator privileged user):
76 brew install gradle git
79 or if you aready have them installed but need to upgrade the version:
82 brew upgrade gradle git
87 we suggest using the **Chocolatey** package manager. See install instructions at <https://chocolatey.org/>, and you will just need
94 Alternatively, you could install a real `bash` shell and install both `gradle` and `git` through `apt-get`.
95 See <https://devblogs.microsoft.com/commandline/bash-on-ubuntu-on-windows-download-now-3/>
96 for how to install the ubuntu bash shell in Windows 10.
98 Another alternative would be to install them separately. For `gradle` follow the instructions at <https://gradle.org/install/>, and for `git` here are a couple of suggestions: Git for Windows <https://gitforwindows.org/>.
99 Getting the individual installs working together on the command line will be trickier
100 so we recommend using Chocolatey or bash.
104 this will depend on which distribution you're using.
106 ##### For *Debian* based distributions (e.g. Mint, Ubuntu, Debian)
110 sudo apt-get install gradle git
113 ##### for RPM-based distributions (e.g. Fedora, CentOS, RedHat)
117 sudo yum install gradle git
120 If you have some other version of linux you'll probably be able to work it out!
125 ## Downloading the Jalview source tree
127 This can be done with `git`.
128 On the command line, change directory to where you want to download Jalview's build-tree
129 top level directory. Then run
132 git clone http://source.jalview.org/git/jalview.git
135 You'll get some progress output and after a minute or two you should have the full
136 Jalview build-tree in the folder `jalview`.
138 ### What's in the source tree?
140 Jalview is a mature product with its codebase going back many years. As such it doesn't
141 have a folder structure that most new gradle projects would have, so you might not
142 find everything in the place you might expect. Here's a brief description of what
143 you might find in the main folders under the `jalview` tree.
145 Within the `jalview` folder you will find (of possible interest):
147 dir/ or file | contains
148 ---------------------|----------------------------------------------------------------------------------------------------------------
149 `bin/` | used by eclipse for compiled classes -- no need to touch this
150 `build/` | the gradle build dir
151 `classes/` | contains the compiled Java classes for the Jalview application
152 `dist/` | assembled `.jar` files needed to run Jalview application
153 `examples/` | example input files usable by Jalview
154 `getdown/` | the libraries used by the Javliew launcher (getdown)
155 `getdown/src/` | our modified source for `getdown`
156 `getdown/website/` | the assembled "download" folder used by getdown for downloads/upgrades
157 `getdown/files/` | the minimal fileset to launch the Jalview launcher, which can then download the rest of the Jalview application
158 `help/` | the help documents
159 `j8lib/` | libraries needed to run Jalview under Java 1.8
160 `j11lib/` | libraries needed to run Jalivew under Java 11
161 `resource/` | non-java resources used in the Jalview application
162 `src/` | the Jalview application source `.java` files
163 `test/` | Test class source files
164 `utils/` | helper applications used in the build process
165 `utils/install4j/` | files used by the packaging tool, install4j
166 `build.gradle` | the build file used by gradle
167 `gradle.properties` | configurable properties for the build process
168 `RELEASE` | propertyfile configuring JALVIEW_VERSION (from jalview.version) and the release branch (from jalview.release). An alternative file can be specified via JALVIEW_RELEASE_FILE property
170 Note that you need a Java 11 JDK to compile Jalview whether your target build is Java 1.8 or Java 11.
175 You will need to have the Java 11 `javac` in your path, or alternatively you can configure
176 gradle to know where this is by putting
179 org.gradle.java.home=/path_to_jdk_directory
181 in the `gradle.properties` file.
183 > *You may want to see some of the other properties you can change at the end of this document.*
185 ### Minimal Jalview Build
187 To compile the necessary class files, just run
192 to compile the classes into the `classes` folder.
193 You should now be able to run the Jalview application directly with
196 java -cp "classes:resources:help:j11lib/*" jalview.bin.Jalview
199 You can also run with an automatic large memory setting (which will set the maximum
200 memory heap of the Jalview JVM to 90% of your local physical memory) and docked icon setting
201 (if possible in your OS) with
204 java -cp "classes:resources:help:j11lib/*" jalview.bin.Launcher
207 >*You must use just "`j11lib/*`" and not "`j11lib/*.jar`" as this is a special Java
208 classpath argument wildcard interpreted by `java`, **not** a shell expansion wildcard interpreted
211 Note that `jalview.bin.Launcher` is a simplified launcher class that re-launches `jalview.bin.Jalview`
212 with the same JRE (*not* the same JVM instance), classpath and arguments, but with an automatically determined `-Xmx...`
213 memory setting if one hasn't been provided.
215 ### Jalview in a Jar File
217 To package the `classes`, `resources`, and `help` into one jar, you can run
222 which assembles the Jalview classes and resources into `dist/jalview.jar`
227 java -cp "dist/jalview.jar:j11lib/*" jalview.bin.Jalview
230 ### Distributed Jar Files
232 To simplify this, all required `.jar` files can be assembled into the `dist` folder
238 which puts all required jar files into `dist` so you can run with
241 java -cp "dist/*" jalview.bin.Jalview
244 ### Single *shadow* Jar File
246 The shadow jar file is a single `.jar` that contains all required classes and resources from `jalview.jar`
247 and all of the supporting libraries in `j11lib/*.jar` merged into one `.jar` archive
248 file. A default launching class (`MAIN-CLASS: jalview.bin.Launcher`) is specified in the `.jar`
249 manifest file (`META/MANIFEST.MF`) so a start class doesn't need to be specified.
251 Build the shadow jar file in `build/libs/jalview-all-VERSION-j11.jar` with
257 __NB__ `VERSION` will be replaced with a version number or "`DEVELOPMENT`" or "`TEST`" depending on how the branch is set up.
262 java -jar build/libs/jalview-all-VERSION-j11.jar
265 Because no arguments are required, most OSes will associate a `.jar` file with the
266 `java` application (if this has been installed through the OS and not just a local
267 unzip) as a `-jar` argument so you may find you can launch `jalview-all-VERSION-j11.jar`
268 just by double-clicking on it)!
270 > The `shadowJar` task is not a requirement for any other task, so to build the shadow
271 jar file you must specify the `shadowJar` task.
273 > The shadow jar file represents probably the simplest way to distribute the Jalview application to machines that already have a Java 11 installed,
274 although without the many and compelling benefits of the `getdown` launcher.
277 ### Building the `getdown` launcher
279 We have made significant customisations to the `getdown` launcher which you can find
280 in `getdown/src/getdown`.
282 > You don't need to build this afresh as the required `gradle-core.jar`
283 and `gradle-launcher.jar` files are already distributed in `j11lib` and `getdown/lib` but if you want to, then
284 you'll need a working Maven and also a Java 8 JDK. Ensure the Java 8 `javac` is forefront
288 >cd getdown/src/getdown
289 >mvn clean package -Dgetdown.host.whitelist="jalview.org,*.jalview.org"
291 > and you will find the required `.jar` files in `core/target/gradle-core-XXX.jar`
292 and `launcher/target/gradle-launcher-XXX.jar`. The `gradle-core.jar` should then be copied
293 to all three of the `j8lib`, `j11lib` and `getdown/lib` folders, whilst the `gradle-launcher.jar` only
294 needs to be copied to `getdown/lib`.
296 >The `mvn` command should ideally include the `-Dgetdown.host.whitelist=*.jalview.org` setting.
297 This, and the necessary file copying commands, can be found in `getdown/src/getdown/mvn_cmd`.
299 To assemble Jalview with `getdown` use the following gradle task:
305 This puts all the necessary files to launch Jalview with `getdown`
306 into `getdown/website/11/`. This could be treated as the reference folder
307 for `getdown`, which is where a getdown launcher will check to see if the Jalview application
308 files it has are up to date, and download if they aren't or it simply doesn't have
311 A minimal getdown-launcher can be found in `getdown/files/11/` which checks its up-to-date
312 status with (the absolute path to) `getdown/website/11/`.
314 This can be launched with
317 java -jar getdown/files/11/getdown-launcher.jar getdown/files/11/ jalview
320 > We've already met the `-jar file.jar` arguments. The next argument is the working folder for
321 getdown, and the final argument, "`jalview`", is a getdown application id (only "`jalview`"
327 There are substantial tests written for Jalview that use TestNG, which you can run with
333 These normally take around 5 - 10 minutes to complete and outputs its full results into
334 the `tests/` folder. A summary of results should appear in your console.
336 You can run different defined groups of tests with
339 gradle test -Ptestng_groups=Network
342 Available groups include Functional (default), Network, External.
344 #### Excluding some tests
346 Some of Jalview's Functional tests don't pass reliably in all environments. We tag these tests with a group like 'Not-bamboo' to mark them for exclusion when we run tests as part of continuous integration.
348 To exclude one or more groups of tests, add them as a comma separated list in testngExcludedGroups.
351 gradle test -Ptestng_excluded_groups=Not-bamboo
353 #### Viewing stdout and stderr for tests
355 By default, gradle doesn't report any of the output or error streams produced by tests. You can enable output by setting the following:
358 gradle test -Ptest_output=1
361 ### Installer packaging with *install4j*
363 Jalview is currently using *install4j* <https://www.ej-technologies.com/products/install4j/overview.html>
364 as its installer packaging tool.
366 If you have a licensed installation of *install4j* you can build Jalview installers
373 though you may need to fiddle with the `install4j` and `copyInstall4jTemplate` tasks
374 in `build.gradle` file to point to your installation of *install4j* and also to bundled
375 JREs if you want to bundle those into the installers.
377 If you want more details, get in touch on our development mailing list <jalview-dev@jalview.org>.
378 Sign up at <http://www.compbio.dundee.ac.uk/mailman/listinfo/jalview-dev>.
385 There are a lot of properties configured in `gradle.properties` which we strongly recommend
386 being left as they are unless you have a specific problem with the build process.
388 There are a few gradle properties you might want to set on the command line with the
389 `-P` flag when building a version of Jalview with specific requirements:
392 This changes the *target* java bytecode version
393 > NOTE that you will need to use a Java 11 (or greater) JDK Java compiler to build
394 Jalview for any byte-code target version.
396 Valid values are `11` and `1.8`.
401 gradle shadowJar -PJAVA_VERSION=1.8
404 When using `-PJAVA_VERSION=1.8` the libraries from `j8lib` (instead of `j11lib`) will be used in the compile
405 and runtime classpath and also used in the `makeDist` build step. Where a Java version of `11` is used in folder and file names, it will
406 instead use `1.8`. Also if you are building installer packages with *install4j* the
407 package builder will look for JRE 1.8 bundles to package in the installers.
409 > Note that continued development of Jalview will assume a Java 11+ runtime environment,
410 the 2.11.0 release will run under a Java 1.8 JRE with a few minor features disabled.
413 This changes the `appbase` setting in `getdown.txt` (`appbase` is where the getdown launcher
414 looks to see if there's an updated file) to point to a particular Jalview channel or some other appropriate
415 place to look for required files. If the selected channel type requires the getdown `appbase` to be a local
416 directory on the filesystem (instead of a website URL) then a modified version of the `getdown-launcher.jar` will
417 be used to allow this. The two versions of the `getdown-launcher.jar` can be found in `getdown/lib`.
418 Note that the DEVELOP and RELEASE channels will normally use a getdown-launcher.jar that *does not* allow the
419 `file://` scheme to be used in the appbase.
421 Some other variables used in the build process might also be set differently depending on the value of `CHANNEL`
422 to allow smooth operation of getdown in the given context.
424 There are several values of `CHANNEL` that can be chosen, with no choice leading to a default of `LOCAL`.
425 Here's what they're for and what they do:
427 * `LOCAL`: This is for running the compiled application from the development directory and used by default.
429 - `appbase` as `file://PATH/TO/YOUR/DEVELOPMENT/getdown/website/JAVA_VERSION`
430 (e.g. `file://home/user/git/jalview/getdown/website/11`)
431 - application subdir as `alt`
432 - Getdown launcher can use a `file://` scheme appbase.
433 - Compile jalview with `gradle getdown` or `gradle shadowJar`
434 - Run Jalview on the command line without using the installers with,
435 Using getdown, e.g. `java -jar ./getdown/files/11/getdown-launcher.jar ./getdown/files/11 jalview`
436 or using the shadowJar with, e.g. `java -jar ./build/libs/jalview-all-TEST-j11.jar`
437 * `BUILD`: This is for creating an appbase channel on the build server by an automatic or manually started build.
439 - `appbase` as `https://builds.jalview.org/browse/${bamboo_planKey}/latest/artifact/shared/getdown-channel/JAVA_VERSION`
440 Note that bamboo_planKey should be set by the build plan with `-Pbamboo_planKey=${bamboo.planKey}`
441 - application subdir as `alt`
442 - Getdown launcher cannot use a `file://` scheme appbase.
443 * `DEVELOP`: This is for creating a `develop` appbase channel on the main web server. This won't become live until the actual getdown artefact is synced to the web server.
445 - `appbase` as `http://www.jalview.org/getdown/develop/JAVA_VERSION`
446 - application subdir as `alt`
447 - Getdown launcher cannot use a `file://` scheme appbase.
448 * `SCRATCH-NAME`: This is for creating a temporary scratch appbase channel on the main web server. This won't become live until the actual getdown artefact is synced to the web server. This is meant for testing an over-the-air update without interfering with the live `release` or `develop` channels. The value of `NAME` can be any "word-character" [A-Za-z0-9\_]
450 - `appbase` as `http://www.jalview.org/getdown/SCRATCH-NAME/JAVA_VERSION`
451 - application subdir as `alt`
452 - Getdown launcher cannot use a `file://` scheme appbase.
453 * `TEST-LOCAL`: Like `SCRATCH` but with a specific `test-local` channel name and a local filesystem appbase. This is meant for testing an over-the-air update on the local filesystem. An extra property `LOCALDIR` must be given (e.g. `-PLOCALDIR=/home/user/tmp/test`)
455 - `appbase` as `file://${LOCALDIR}`
456 - application subdir as `alt`
457 - Getdown launcher can use a `file://` scheme appbase.
458 * `TEST-RELEASE`: Like `SCRATCH` but with a specific `test-release` channel name. This won't become live until the actual getdown artefact is synced to the web server. This is meant for testing an over-the-air update without interfering with the live `release` or `develop` channels.
460 - `appbase` as `http://www.jalview.org/getdown/test-release/JAVA_VERSION`
461 - application subdir as `alt`
462 - Getdown launcher cannot use a `file://` scheme appbase.
463 * `RELEASE`: This is for an actual release build, and will use an appbase on the main web server with the main `release` channel name. This won't become live until the actual getdown artefact is synced to the web server.
465 - `appbase` as `http://www.jalview.org/getdown/release/JAVA_VERSION`
466 - application subdir as `release`
467 - Getdown launcher cannot use a `file://` scheme appbase.
468 * `ARCHIVE`: This is a helper to create a channel for a specific release version, and will use an appbase on the main web server with a specific `archive/JALVIEW_VERSION` channel name. This won't become live until the actual getdown artefact is synced to the web server.
469 You must also specify an `ARCHIVEDIR` property that points to an earlier version of Jalview with a `dist` directory containing the required jar files. This should create a getdown structure and digest with the older jar files.
471 - `appbase` as `http://www.jalview.org/getdown/archive/JALVIEW_VERSION/JAVA_VERSION`
472 - application subdir as `alt`
473 - Getdown launcher cannot use a `file://` scheme appbase.
474 * `ARCHIVELOCAL`: Like `ARCHIVE` but with a local filesystem appbase for local testing.
475 You must also specify an `ARCHIVEDIR` property that points to an earlier version of Jalview with a `dist` directory containing the required jar files. This should create a getdown structure and digest with the older jar files.
477 - `appbase` as `file://PATH/TO/YOUR/DEVELOPMENT/getdown/website/JAVA_VERSION` (where the old jars will have been copied and digested)
478 - application subdir as `alt`
479 - Getdown launcher can use a `file://` scheme appbase.
483 gradle getdown -PCHANNEL=SCRATCH-my_test_version
486 **New `CHANNEL` appearance features 2020-12-10**
487 There are now differing cosmetics for different channels, including application icons, Getdown splashscreen,
488 About splashscreen, Installer backgrounds, application name. This is controlled by the files in
492 In `utils/channels` there are different directories for the different channels. Currently there are directories for
493 `default`, `develop`, `release`, `test-release`, `jalviewjs` and `jalviewjs-release`. If a specified `CHANNEL` is not one of `DEVELOP`, `RELEASE`, `TEST-RELEASE`, `JALVIEWJS`, `JALVIEWJS-RELEASE`
494 then it will use the `default` directory.
496 Inside the `utils/channels/<channelname>` directory are:
497 - a file `channel_gradle.properties`. This will be used by the `build.gradle` script (i.e. any gradle build) to *override* the values found in `gradle.properties`.
498 - an `images` directory used to store different images referred to in this channels's `channel_gradle.properties`.
499 - a `resources` directory which is merged into the javliew.jar's own resources directory. Importantly it contains a `channel.props` file and another `images` dir which contains properties and images used by the application (in `jalview.util.ChannelProperties`), such as icon files or banner images, and the `app_name` property used as the display name for the application (e.g. "Jalview Develop") inside the application code. Please see the `getProperty` and `getImage` methods in `jalview.bin.ChannelProperties` to access these channel based resources.
502 #### JALVIEW_VERSION and the RELEASE file
503 Any Jalview build will include the value of JALVIEW_VERSION in various places, including the 'About' and Jalview Desktop window title, and in filenames for the stand-alone executable jar. You can specify a custom version for a build via the JALVIEW_VERSION property, but for most situations, JALVIEW_VERSION will be automatically configured according to the value of the CHANNEL property, using the `jalview.version` property specified in the RELEASE file:
504 - `CHANNEL=RELEASE` will set version to jalview.version.
505 - `CHANNEL=TEST or DEVELOP` will append '-test' or '-develop' to jalview.version.
506 - `CHANNEL=JALVIEWJS` will use the `channel.props` found in `utils/channels/jalviewjs` but otherwise uses `LOCAL` settings.
507 - `CHANNEL=JALVIEWJS-RELEASE` uses a symbolic link to `utils/channels/jalviewjs` but otherwise uses `RELEASE` settings.
509 It is also possible to specify a custom location for the RELEASE file via an optional JALVIEW_RELEASE_FILE property.
511 #### `install4jMediaTypes`
512 If you are building *install4j* installers (requires *install4j* to be installed) then this property specifies a comma-separated
513 list of media types (i.e. platform specific installers) *install4j* should actually build.
515 Currently the valid values are
523 The default value is all of them.
527 gradle installers -PJAVA_VERSION=1.8 -Pinstall4jMediaTypes=macosArchive
530 To get an up-to-date list of possible values, you can run
533 perl -n -e 'm/^\s*<(\w+)[^>]*\bmediaFileName=/ && print "$1\n";' utils/install4j/install4j_template.install4j | sort -u
535 in the `jalview` root folder.
537 ## Enabling Code Coverage with OpenClover
539 Bytecode instrumentation tasks are enabled by specifying 'true' (or just a non-whitespace non-numeric word) in the 'clover' property. This adds the 'openclover' plugin to the build script's classpath, making it possible to track code execution during test which can be viewed as an HTML report published at build/reports/clover/index.html.
541 ```gradle -Pclover=true test cloverReport```
543 #### Troubleshooting report generation
545 The build forks a new JVM process to run the clover report generation tools (both XML and HTML reports are generated by default). The following properties can be used to specify additional options or adjust JVM memory settings. Default values for these options are:
547 ##### JVM Memory settings - increase if out of memory errors are reported
549 ```cloverReportJVMHeap = 2g```
551 ##### -Dfile.encoding=UTF-8 is an essential parameters for report generation. Add additional ones separated by a space.
553 ```cloverReportJVMArgs = -Dfile.encoding=UTF-8```
555 ##### Add -v to debug velocity html generation errors, or -d to track more detailed issues with the coverage database
557 ```cloverReportHTMLOptions = ```
559 ##### -v for verbose, -d for debug level messages (as above)
561 ```cloverReportXMLOptions = ```
564 _Note_ do not forget to include the -Dfile.encoding=UTF-8 option: this is essential for some platforms in order for Clover to correctly parse some Jalview source files that contain characters that are UTF-8 encoded.
566 ## Setting up in Eclipse IDE
568 ### Installing Eclipse IDE
570 We develop in Eclipse, and support settings to develop and save Jalview source code
571 in our preferred style. We also support running the Jalview application, debugging
572 and running tests with TestNG from within Eclipse.
574 To get Jalview set up as a project in Eclipse, we recommend using at least the 2020-03
575 version of Eclipse IDE for Java Developers which you can download from the Eclipse
576 website: <https://www.eclipse.org/downloads/>. Since Eclipse 2020-03 you are encouraged to use the Eclipse Installer (see the Eclipse Downloads page).
577 In the installer, when given a choice of packages for Eclipse you should choose the "Eclipse IDE for Enterprise Java Developers" package.
579 ![](./images/eclipse_installer.png "Eclipse Installer screenshot")
581 Once Eclipse is installed, we also recommend installing several plugins from the Eclipse Marketplace.
583 Some of these should already be installed with the Enterprise Java Developer package:
585 1. Buildship Gradle Integration 3.0 (or greater)
586 1. EclEmma Java Code Coverage
587 1. Egit - Git Integration for Eclipse
589 To install the others, launch Eclipse, and go to Help->Eclipse Marketplace...
591 Search for and install:
593 1. Groovy Development Tools 3.4.0 (or greater)
594 1. Checkstyle Plug-in (optional)
595 1. TestNG for Eclipse (optional -- only needed if you want to run tests from Eclipse)
597 > At time of writing, TestNG for Eclipse does not show up in the Eclipse Marketplace
598 as the latest released version does not install in Eclipse 2020-03.
599 However, you can install a working release of TestNG for Eclipse by going to
601 > Help->Install New Software...
605 > `TestNG Release - https://dl.bintray.com/testng-team/testng-eclipse-release`
607 > into the *Work with* box and click on the *Add...* button.
609 > Eclipse might pause for a bit with the word *Pending* in the table below at this point, but it will eventually list TestNG with
610 a selection box under the *Name* column.
612 > Select *TestNG* and carry on through the
613 install process to install the TestNG plugin.
615 After installing the plugins, check that Java 11 is set up in Eclipse as the default JRE (see section [Java 11 compliant JDK](#java-11-compliant-jdk)).
617 To do this go to Preferences (Eclipse->Preferences in macOS, File->Preferences
618 on Windows or Window->Preferences on Linux) and find
620 Java -> Installed JREs
622 If your Java 11 installation is not listed, click on
624 *Add* -> Standard VM -> *Next*
626 and enter the JRE home. You can browse to where it is installed. Give it a name (like "AdoptOpenJDK 11"). Select this JDK
627 as the default JRE and click on *Apply and Close*.
630 You can now import Jalview.
632 ### Importing Jalview as an Eclipse project
634 #### Importing an already downloaded git repo
636 If you have already downloaded Jalview using `git clone` then you can import this folder into Eclipse directly.
638 __Before importing the cloned git repo you must create the Eclipse project files.__ You can do this by either running
644 Unzipping the file `utils/eclipse/eclipse_startup_files.zip` in the base repo directory (`jalview`)
646 It is important to import
647 Jalview as a Gradle project (not as a Java project), so go to
653 Gradle->Existing Gradle Project
655 and then click on the *Next* button.
657 In the following options, it is the __Project Root Directory__ you should set to be the
658 `jalview` folder that git downloaded. Then you can click on the *Finish* button.
660 #### Using Eclipse IDE to download the git repo
662 If you don't have git as a command line tool or would prefer to work entirely within Eclipse IDE then
663 Eclipse's eGit plugin can set up a git repo of the jalview source. Go to
669 Git->Projects from Git
671 and then click on the *Next* button.
673 Then select Clone URI and click on *Next*.
675 In the next window (Source Git Repository) you should put the `git clone` URL in the text box labelled `URI`. If you have a Jalview developer account (with a username and password for the Jalview git repository) then you should enter
676 `https://source.jalview.org/git/jalview.git`.
677 If you do not have a Jalview developer account then you should enter
678 `http://source.jalview.org/git/jalview.git`.
679 You will not be able to push any of your changes back to the Jalview git repository. However you can still pull all branches of the Jalview source code to your computer and develop the code there.
680 > You can sign up for a Jalview developer account at <https://source.jalview.org/crucible/>
682 If you have a Jalview developer account, enter the username and password and decide if you want to use Eclipse's secure storage. If you don't have an account you can leave the Authentication section blank.
684 ![Eclipse eGit connection configuration](./images/eclipse_egit_connection.png)
686 Click on the *Next* button.
688 The next window (Branch Selection) gives a list of the many Jalview branches, which by default will be all checked. You probably only want to download one branch (you can always download others at a later time). This is likely to be the `develop` branch so you can click on the *Deselect All* button, find the `develop` branch (the filter text helps), select that, and then click on the *Next* button.
690 Choose a directory to your copy of the git repo in, and leave the other options as they are and click on the *Next* button. The next stage may take a minute or two as it checks out the selected branch(es) from the Jalview git repository.
692 When it has finished it is important to select __Import as general project__ and then click on *Next*.
693 > Ideally there would be an _Import as gradle project_ here but there isn't -- we'll sort that out later.
695 ![Eclipse eGit import choice](./images/eclipse_egit_import.png)
697 Click on the *Next* button.
699 You can change the project name here. By default it will show as __jalview__ which is fine unless you have another instance of the a Jalview project also called jalview, in which case you could change this project's name now to avoid a conflict within Eclipse.
703 However, we haven't finished...
705 You should now see, and be able to expand, the jalview project in the Project Explorer. We need to tell eclipse that this is a Gradle project, which will then allow the Eclipse Buildship plugin to automatically configure almost everything else!
707 Right click on the project name (jalview) in the Project Explorer and find Configure towards the bottom of this long context menu, then choose Add Gradle Nature.
709 ![Eclipse Add Gradle Nature](./images/eclipse_add_gradle_nature.png)
711 The project should now reconfigure itself using the `build.gradle` file to dynamically set various aspects of the project including classpath.
713 #### Additional views
715 Some views that are automatically added when Importing a Gradle Project are not added when simply Adding a Gradle Nature, but we can add these manually by clicking on
716 Window->Show View->Console
718 Window->Show View->Other...
719 Filter with the word "gradle" and choose both __Gradle Executions__ and __Gradle Tasks__ and then click on the *Open* button.
722 Okay, ready to code! Use of Eclipse is beyond the scope of this document, but you can find more information about developing jalview and our developer workflow in the google doc <https://docs.google.com/document/d/1lZo_pZRkazDBJGNachXr6qCVlw8ByuMYG6e9SZlPUlQ/edit?usp=sharing>
725 [Jalview Development Team](mailto:help@jalview.org)