doc/building.html

   1 <html>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
   3 <html xmlns="http://www.w3.org/1999/xhtml">
   4   <head>
   5     <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
   6     <meta http-equiv="Content-Style-Type" content="text/css" />
   7     <meta name="generator" content="flexmark" />
   8   <title>Building Jalview from Source</title>
   9     <style type="text/css">code{white-space: pre;}</style>
  10 <style>
  11 @font-face {
  12   font-family: octicons-link;
  13   src: url(data:font/woff;charset=utf-8;base64,d09GRgABAAAAAAZwABAAAAAACFQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAABEU0lHAAAGaAAAAAgAAAAIAAAAAUdTVUIAAAZcAAAACgAAAAoAAQAAT1MvMgAAAyQAAABJAAAAYFYEU3RjbWFwAAADcAAAAEUAAACAAJThvmN2dCAAAATkAAAABAAAAAQAAAAAZnBnbQAAA7gAAACyAAABCUM+8IhnYXNwAAAGTAAAABAAAAAQABoAI2dseWYAAAFsAAABPAAAAZwcEq9taGVhZAAAAsgAAAA0AAAANgh4a91oaGVhAAADCAAAABoAAAAkCA8DRGhtdHgAAAL8AAAADAAAAAwGAACfbG9jYQAAAsAAAAAIAAAACABiATBtYXhwAAACqAAAABgAAAAgAA8ASm5hbWUAAAToAAABQgAAAlXu73sOcG9zdAAABiwAAAAeAAAAME3QpOBwcmVwAAAEbAAAAHYAAAB/aFGpk3jaTY6xa8JAGMW/O62BDi0tJLYQincXEypYIiGJjSgHniQ6umTsUEyLm5BV6NDBP8Tpts6F0v+k/0an2i+itHDw3v2+9+DBKTzsJNnWJNTgHEy4BgG3EMI9DCEDOGEXzDADU5hBKMIgNPZqoD3SilVaXZCER3/I7AtxEJLtzzuZfI+VVkprxTlXShWKb3TBecG11rwoNlmmn1P2WYcJczl32etSpKnziC7lQyWe1smVPy/Lt7Kc+0vWY/gAgIIEqAN9we0pwKXreiMasxvabDQMM4riO+qxM2ogwDGOZTXxwxDiycQIcoYFBLj5K3EIaSctAq2kTYiw+ymhce7vwM9jSqO8JyVd5RH9gyTt2+J/yUmYlIR0s04n6+7Vm1ozezUeLEaUjhaDSuXHwVRgvLJn1tQ7xiuVv/ocTRF42mNgZGBgYGbwZOBiAAFGJBIMAAizAFoAAABiAGIAznjaY2BkYGAA4in8zwXi+W2+MjCzMIDApSwvXzC97Z4Ig8N/BxYGZgcgl52BCSQKAA3jCV8CAABfAAAAAAQAAEB42mNgZGBg4f3vACQZQABIMjKgAmYAKEgBXgAAeNpjYGY6wTiBgZWBg2kmUxoDA4MPhGZMYzBi1AHygVLYQUCaawqDA4PChxhmh/8ODDEsvAwHgMKMIDnGL0x7gJQCAwMAJd4MFwAAAHjaY2BgYGaA4DAGRgYQkAHyGMF8NgYrIM3JIAGVYYDT+AEjAwuDFpBmA9KMDEwMCh9i/v8H8sH0/4dQc1iAmAkALaUKLgAAAHjaTY9LDsIgEIbtgqHUPpDi3gPoBVyRTmTddOmqTXThEXqrob2gQ1FjwpDvfwCBdmdXC5AVKFu3e5MfNFJ29KTQT48Ob9/lqYwOGZxeUelN2U2R6+cArgtCJpauW7UQBqnFkUsjAY/kOU1cP+DAgvxwn1chZDwUbd6CFimGXwzwF6tPbFIcjEl+vvmM/byA48e6tWrKArm4ZJlCbdsrxksL1AwWn/yBSJKpYbq8AXaaTb8AAHja28jAwOC00ZrBeQNDQOWO//sdBBgYGRiYWYAEELEwMTE4uzo5Zzo5b2BxdnFOcALxNjA6b2ByTswC8jYwg0VlNuoCTWAMqNzMzsoK1rEhNqByEyerg5PMJlYuVueETKcd/89uBpnpvIEVomeHLoMsAAe1Id4AAAAAAAB42oWQT07CQBTGv0JBhagk7HQzKxca2sJCE1hDt4QF+9JOS0nbaaYDCQfwCJ7Au3AHj+LO13FMmm6cl7785vven0kBjHCBhfpYuNa5Ph1c0e2Xu3jEvWG7UdPDLZ4N92nOm+EBXuAbHmIMSRMs+4aUEd4Nd3CHD8NdvOLTsA2GL8M9PODbcL+hD7C1xoaHeLJSEao0FEW14ckxC+TU8TxvsY6X0eLPmRhry2WVioLpkrbp84LLQPGI7c6sOiUzpWIWS5GzlSgUzzLBSikOPFTOXqly7rqx0Z1Q5BAIoZBSFihQYQOOBEdkCOgXTOHA07HAGjGWiIjaPZNW13/+lm6S9FT7rLHFJ6fQbkATOG1j2OFMucKJJsxIVfQORl+9Jyda6Sl1dUYhSCm1dyClfoeDve4qMYdLEbfqHf3O/AdDumsjAAB42mNgYoAAZQYjBmyAGYQZmdhL8zLdDEydARfoAqIAAAABAAMABwAKABMAB///AA8AAQAAAAAAAAAAAAAAAAABAAAAAA==) format('woff');
  14 }
  15
  16 body {
  17   -webkit-text-size-adjust: 100%;
  18   text-size-adjust: 100%;
  19   color: #333;
  20   font-family: "Helvetica Neue", Helvetica, "Segoe UI", Arial, freesans, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol";
  21   font-size: 16px;
  22   line-height: 1.6;
  23   word-wrap: break-word;
  24   width: 728px;
  25   max-width: 99%;
  26   box-sizing: border-box;
  27   padding: 30px 30px 8rem 30px;
  28   margin-left: auto;
  29   margin-right: auto;
  30 }
  31
  32 body a {
  33   background-color: transparent;
  34 }
  35
  36 body a:active,
  37 body a:hover {
  38   outline: 0;
  39 }
  40
  41 body strong {
  42   font-weight: bold;
  43 }
  44
  45 body h1 {
  46   font-size: 2em;
  47   margin: 0.67em 0;
  48 }
  49
  50 body img {
  51   border: 0;
  52 }
  53
  54 body hr {
  55   box-sizing: content-box;
  56   height: 0;
  57 }
  58
  59 body pre {
  60   overflow: auto;
  61 }
  62
  63 body code,
  64 body kbd,
  65 body pre {
  66   font-family: monospace, monospace;
  67   font-size: 1em;
  68 }
  69
  70 body input {
  71   color: inherit;
  72   font: inherit;
  73   margin: 0;
  74 }
  75
  76 body html input[disabled] {
  77   cursor: default;
  78 }
  79
  80 body input {
  81   line-height: normal;
  82 }
  83
  84 body input[type="checkbox"] {
  85   box-sizing: border-box;
  86   padding: 0;
  87 }
  88
  89 body table {
  90   border-collapse: collapse;
  91   border-spacing: 0;
  92 }
  93
  94 body td,
  95 body th {
  96   padding: 0;
  97 }
  98
  99 body * {
 100   box-sizing: border-box;
 101 }
 102
 103 body input {
 104   font: 13px / 1.4 Helvetica, arial, nimbussansl, liberationsans, freesans, clean, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol";
 105 }
 106
 107 body a {
 108   color: #4078c0;
 109   text-decoration: none;
 110 }
 111
 112 body a:hover,
 113 body a:active {
 114   text-decoration: underline;
 115 }
 116
 117 body hr {
 118   height: 0;
 119   margin: 15px 0;
 120   overflow: hidden;
 121   background: transparent;
 122   border: 0;
 123   border-bottom: 1px solid #ddd;
 124 }
 125
 126 body hr:before {
 127   display: table;
 128   content: "";
 129 }
 130
 131 body hr:after {
 132   display: table;
 133   clear: both;
 134   content: "";
 135 }
 136
 137 body h1,
 138 body h2,
 139 body h3,
 140 body h4,
 141 body h5,
 142 body h6 {
 143   margin-top: 15px;
 144   margin-bottom: 15px;
 145   line-height: 1.1;
 146 }
 147
 148 body h1 {
 149   font-size: 30px;
 150 }
 151
 152 body h2 {
 153   font-size: 21px;
 154 }
 155
 156 body h3 {
 157   font-size: 16px;
 158 }
 159
 160 body h4 {
 161   font-size: 14px;
 162 }
 163
 164 body h5 {
 165   font-size: 12px;
 166 }
 167
 168 body h6 {
 169   font-size: 11px;
 170 }
 171
 172 body blockquote {
 173   margin: 0;
 174 }
 175
 176 body ul,
 177 body ol {
 178   padding: 0;
 179   margin-top: 0;
 180   margin-bottom: 0;
 181 }
 182
 183 body ol ol,
 184 body ul ol {
 185   list-style-type: lower-roman;
 186 }
 187
 188 body ul ul ol,
 189 body ul ol ol,
 190 body ol ul ol,
 191 body ol ol ol {
 192   list-style-type: lower-alpha;
 193 }
 194
 195 body dd {
 196   margin-left: 0;
 197 }
 198
 199 body code {
 200   font-family: Consolas, "Liberation Mono", Menlo, Courier, monospace;
 201   font-size: 12px;
 202 }
 203
 204 body pre {
 205   margin-top: 0;
 206   margin-bottom: 0;
 207   font: 12px Consolas, "Liberation Mono", Menlo, Courier, monospace;
 208 }
 209
 210 body .select::-ms-expand {
 211   opacity: 0;
 212 }
 213
 214 body .octicon {
 215   font: normal normal normal 16px/1 octicons-link;
 216   display: inline-block;
 217   text-decoration: none;
 218   text-rendering: auto;
 219   -webkit-font-smoothing: antialiased;
 220   -moz-osx-font-smoothing: grayscale;
 221   -webkit-user-select: none;
 222   -moz-user-select: none;
 223   -ms-user-select: none;
 224   user-select: none;
 225 }
 226
 227 body .octicon-link:before {
 228   content: '\f05c';
 229 }
 230
 231 body:before {
 232   display: table;
 233   content: "";
 234 }
 235
 236 body:after {
 237   display: table;
 238   clear: both;
 239   content: "";
 240 }
 241
 242 body>*:first-child {
 243   margin-top: 0 !important;
 244 }
 245
 246 body>*:last-child {
 247   margin-bottom: 0 !important;
 248 }
 249
 250 body a:not([href]) {
 251   color: inherit;
 252   text-decoration: none;
 253 }
 254
 255 body .anchor {
 256   display: inline-block;
 257   padding-right: 2px;
 258   margin-left: -18px;
 259 }
 260
 261 body .anchor:focus {
 262   outline: none;
 263 }
 264
 265 body h1,
 266 body h2,
 267 body h3,
 268 body h4,
 269 body h5,
 270 body h6 {
 271   margin-top: 1em;
 272   margin-bottom: 16px;
 273   font-weight: bold;
 274   line-height: 1.4;
 275 }
 276
 277 body h1 .octicon-link,
 278 body h2 .octicon-link,
 279 body h3 .octicon-link,
 280 body h4 .octicon-link,
 281 body h5 .octicon-link,
 282 body h6 .octicon-link {
 283   color: #000;
 284   vertical-align: middle;
 285   visibility: hidden;
 286 }
 287
 288 body h1:hover .anchor,
 289 body h2:hover .anchor,
 290 body h3:hover .anchor,
 291 body h4:hover .anchor,
 292 body h5:hover .anchor,
 293 body h6:hover .anchor {
 294   text-decoration: none;
 295 }
 296
 297 body h1:hover .anchor .octicon-link,
 298 body h2:hover .anchor .octicon-link,
 299 body h3:hover .anchor .octicon-link,
 300 body h4:hover .anchor .octicon-link,
 301 body h5:hover .anchor .octicon-link,
 302 body h6:hover .anchor .octicon-link {
 303   visibility: visible;
 304 }
 305
 306 body h1 {
 307   padding-bottom: 0.3em;
 308   font-size: 1.75em;
 309   line-height: 1.2;
 310 }
 311
 312 body h1 .anchor {
 313   line-height: 1;
 314 }
 315
 316 body h2 {
 317   padding-bottom: 0.3em;
 318   font-size: 1.5em;
 319   line-height: 1.225;
 320 }
 321
 322 body h2 .anchor {
 323   line-height: 1;
 324 }
 325
 326 body h3 {
 327   font-size: 1.25em;
 328   line-height: 1.43;
 329 }
 330
 331 body h3 .anchor {
 332   line-height: 1.2;
 333 }
 334
 335 body h4 {
 336   font-size: 1em;
 337 }
 338
 339 body h4 .anchor {
 340   line-height: 1.2;
 341 }
 342
 343 body h5 {
 344   font-size: 1em;
 345 }
 346
 347 body h5 .anchor {
 348   line-height: 1.1;
 349 }
 350
 351 body h6 {
 352   font-size: 1em;
 353   color: #777;
 354 }
 355
 356 body h6 .anchor {
 357   line-height: 1.1;
 358 }
 359
 360 body p,
 361 body blockquote,
 362 body ul,
 363 body ol,
 364 body dl,
 365 body table,
 366 body pre {
 367   margin-top: 0;
 368   margin-bottom: 16px;
 369 }
 370
 371 body hr {
 372   height: 4px;
 373   padding: 0;
 374   margin: 16px 0;
 375   background-color: #e7e7e7;
 376   border: 0 none;
 377 }
 378
 379 body ul,
 380 body ol {
 381   padding-left: 2em;
 382 }
 383
 384 body ul ul,
 385 body ul ol,
 386 body ol ol,
 387 body ol ul {
 388   margin-top: 0;
 389   margin-bottom: 0;
 390 }
 391
 392 body li>p {
 393   margin-top: 16px;
 394 }
 395
 396 body dl {
 397   padding: 0;
 398 }
 399
 400 body dl dt {
 401   padding: 0;
 402   margin-top: 16px;
 403   font-size: 1em;
 404   font-style: italic;
 405   font-weight: bold;
 406 }
 407
 408 body dl dd {
 409   padding: 0 16px;
 410   margin-bottom: 16px;
 411 }
 412
 413 body blockquote {
 414   padding: 0 15px;
 415   color: #777;
 416   border-left: 4px solid #ddd;
 417 }
 418
 419 body blockquote>:first-child {
 420   margin-top: 0;
 421 }
 422
 423 body blockquote>:last-child {
 424   margin-bottom: 0;
 425 }
 426
 427 body table {
 428   display: block;
 429   width: 100%;
 430   overflow: auto;
 431   word-break: normal;
 432   word-break: keep-all;
 433 }
 434
 435 body table th {
 436   font-weight: bold;
 437 }
 438
 439 body table th,
 440 body table td {
 441   padding: 6px 13px;
 442   border: 1px solid #ddd;
 443 }
 444
 445 body table tr {
 446   background-color: #fff;
 447   border-top: 1px solid #ccc;
 448 }
 449
 450 body table tr:nth-child(2n) {
 451   background-color: #f8f8f8;
 452 }
 453
 454 body img {
 455   max-width: 100%;
 456   box-sizing: content-box;
 457   background-color: #fff;
 458 }
 459
 460 body code {
 461   padding: 0;
 462   padding-top: 0;
 463   padding-bottom: 0;
 464   margin: 0;
 465   font-size: 85%;
 466   background-color: rgba(0,0,0,0.04);
 467   border-radius: 3px;
 468 }
 469
 470 body code:before,
 471 body code:after {
 472   letter-spacing: -0.2em;
 473   content: "\00a0";
 474 }
 475
 476 body pre>code {
 477   padding: 0;
 478   margin: 0;
 479   font-size: 100%;
 480   word-break: normal;
 481   white-space: pre;
 482   background: transparent;
 483   border: 0;
 484 }
 485
 486 body .highlight {
 487   margin-bottom: 16px;
 488 }
 489
 490 body .highlight pre,
 491 body pre {
 492   padding: 16px;
 493   overflow: auto;
 494   font-size: 85%;
 495   line-height: 1.45;
 496   background-color: #f7f7f7;
 497   border-radius: 3px;
 498 }
 499
 500 body .highlight pre {
 501   margin-bottom: 0;
 502   word-break: normal;
 503 }
 504
 505 body pre {
 506   word-wrap: normal;
 507 }
 508
 509 body pre code {
 510   display: inline;
 511   max-width: initial;
 512   padding: 0;
 513   margin: 0;
 514   overflow: initial;
 515   line-height: inherit;
 516   word-wrap: normal;
 517   background-color: transparent;
 518   border: 0;
 519 }
 520
 521 body pre code:before,
 522 body pre code:after {
 523   content: normal;
 524 }
 525
 526 body kbd {
 527   display: inline-block;
 528   padding: 3px 5px;
 529   font-size: 11px;
 530   line-height: 10px;
 531   color: #555;
 532   vertical-align: middle;
 533   background-color: #fcfcfc;
 534   border: solid 1px #ccc;
 535   border-bottom-color: #bbb;
 536   border-radius: 3px;
 537   box-shadow: inset 0 -1px 0 #bbb;
 538 }
 539
 540 body .pl-c {
 541   color: #969896;
 542 }
 543
 544 body .pl-c1,
 545 body .pl-s .pl-v {
 546   color: #0086b3;
 547 }
 548
 549 body .pl-e,
 550 body .pl-en {
 551   color: #795da3;
 552 }
 553
 554 body .pl-s .pl-s1,
 555 body .pl-smi {
 556   color: #333;
 557 }
 558
 559 body .pl-ent {
 560   color: #63a35c;
 561 }
 562
 563 body .pl-k {
 564   color: #a71d5d;
 565 }
 566
 567 body .pl-pds,
 568 body .pl-s,
 569 body .pl-s .pl-pse .pl-s1,
 570 body .pl-sr,
 571 body .pl-sr .pl-cce,
 572 body .pl-sr .pl-sra,
 573 body .pl-sr .pl-sre {
 574   color: #183691;
 575 }
 576
 577 body .pl-v {
 578   color: #ed6a43;
 579 }
 580
 581 body .pl-id {
 582   color: #b52a1d;
 583 }
 584
 585 body .pl-ii {
 586   background-color: #b52a1d;
 587   color: #f8f8f8;
 588 }
 589
 590 body .pl-sr .pl-cce {
 591   color: #63a35c;
 592   font-weight: bold;
 593 }
 594
 595 body .pl-ml {
 596   color: #693a17;
 597 }
 598
 599 body .pl-mh,
 600 body .pl-mh .pl-en,
 601 body .pl-ms {
 602   color: #1d3e81;
 603   font-weight: bold;
 604 }
 605
 606 body .pl-mq {
 607   color: #008080;
 608 }
 609
 610 body .pl-mi {
 611   color: #333;
 612   font-style: italic;
 613 }
 614
 615 body .pl-mb {
 616   color: #333;
 617   font-weight: bold;
 618 }
 619
 620 body .pl-md {
 621   background-color: #ffecec;
 622   color: #bd2c00;
 623 }
 624
 625 body .pl-mi1 {
 626   background-color: #eaffea;
 627   color: #55a532;
 628 }
 629
 630 body .pl-mdr {
 631   color: #795da3;
 632   font-weight: bold;
 633 }
 634
 635 body .pl-mo {
 636   color: #1d3e81;
 637 }
 638
 639 body kbd {
 640   display: inline-block;
 641   padding: 3px 5px;
 642   font: 11px Consolas, "Liberation Mono", Menlo, Courier, monospace;
 643   line-height: 10px;
 644   color: #555;
 645   vertical-align: middle;
 646   background-color: #fcfcfc;
 647   border: solid 1px #ccc;
 648   border-bottom-color: #bbb;
 649   border-radius: 3px;
 650   box-shadow: inset 0 -1px 0 #bbb;
 651 }
 652
 653 body .task-list-item {
 654   list-style-type: none;
 655 }
 656
 657 body .task-list-item+.task-list-item {
 658   margin-top: 3px;
 659 }
 660
 661 body .task-list-item input {
 662   margin: 0 0.35em 0.25em -1.6em;
 663   vertical-align: middle;
 664 }
 665
 666 body :checked+.radio-label {
 667   z-index: 1;
 668   position: relative;
 669   border-color: #4078c0;
 670 }
 671 </style>
 672 </head>
 673   <body>
 674 <ul>
 675 <li><a href="#tldr">tl;dr</a></li>
 676 <li><a href="#setting-up">Setting up</a>
 677 <ul>
 678 <li><a href="#java-11-compliant-jdk">Java 11 compliant JDK</a></li>
 679 <li><a href="#gradle-and-git">gradle and git</a></li>
 680 </ul>
 681 </li>
 682 <li><a href="#downloading-the-jalview-source-tree">Downloading the Jalview source tree</a>
 683 <ul>
 684 <li><a href="#whats-in-the-source-tree">What's in the source tree?</a></li>
 685 </ul>
 686 </li>
 687 <li><a href="#building-jalview">Building Jalview</a>
 688 <ul>
 689 <li><a href="#minimal-jalview-build">Minimal Jalview Build</a></li>
 690 <li><a href="#jalview-in-a-jar-file">Jalview in a Jar File</a></li>
 691 <li><a href="#distributed-jar-files">Distributed Jar Files</a></li>
 692 <li><a href="#single-shadow-jar-file">Single <em>shadow</em> Jar File</a></li>
 693 <li><a href="#building-the-getdown-launcher">Building the <code>getdown</code> launcher</a></li>
 694 <li><a href="#running-tests">Running tests</a></li>
 695 <li><a href="#installer-packaging-with-install4j">Installer packaging with <em>install4j</em></a></li>
 696 </ul>
 697 </li>
 698 <li><a href="#gradle-properties">Gradle properties</a></li>
 699 <li><a href="#enabling-code-coverage-with-openclover">Enabling Code Coverage with OpenClover</a></li>
 700 <li><a href="#setting-up-in-eclipse-ide">Setting up in Eclipse IDE</a>
 701 <ul>
 702 <li><a href="#installing-eclipse-ide">Installing Eclipse IDE</a></li>
 703 <li><a href="#importing-jalview-as-an-eclipse-project">Importing Jalview as an Eclipse project</a></li>
 704 </ul>
 705 </li>
 706 </ul>
 707 <h1 id="building-jalview-from-source"><a href="#building-jalview-from-source" name="building-jalview-from-source" class="anchor"><span class="octicon octicon-link"></span>Building Jalview from Source</a></h1>
 708 <h2 id="tldr"><a href="#tldr" name="tldr" class="anchor"><span class="octicon octicon-link"></span>tl;dr</a></h2>
 709 <pre><code># download
 710 git clone http://source.jalview.org/git/jalview.git
 711 # compile
 712 cd jalview
 713 gradle shadowJar
 714 # run
 715 java -jar build/libs/jalview-all-*-j11.jar
 716
 717 # and/or create launcher
 718 gradle getdown
 719 # use launcher
 720 cd getdown/files
 721 java -jar getdown-launcher.jar . jalview
 722 </code></pre>
 723 <h2 id="setting-up"><a href="#setting-up" name="setting-up" class="anchor"><span class="octicon octicon-link"></span>Setting up</a></h2>
 724 <blockquote>
 725 <p>To get set up using <em>only</em> the Eclipse IDE (<a href="https://www.eclipse.org/">https://www.eclipse.org/</a>) then please see the section <a href="#setting-up-in-eclipse-ide">Setting up in Eclipse IDE</a></p>
 726 </blockquote>
 727 <p>The method here is described in terms of using a command line.  You can easily do this on linux or in a Terminal window in macOS.  You can do it in Windows.</p>
 728 <ul>
 729 <li>Java 11 compliant JDK</li>
 730 <li>gradle 5.2 or above <em>(NB gradle 6.6 and above currently produces NullPointerExceptions during the build. This is non-fatal and does not affect the build. Use gradle 6.5.1 to avoid this)</em></li>
 731 <li>git</li>
 732 </ul>
 733 <blockquote>
 734 <p>The versions and installation methods here are just suggestions (which we have tested
 735 so are known to work).  If you need or wish to use different implementations (particularly
 736 you might need a bespoke JDK if you are on an exotic architecture) then the general
 737 build instructions should work with any gradle 5+.  You should be able to compile the
 738 bytecode with any JDK Java 11+.  The resulting bytecode (in particular the shadow jar)
 739 should be runnable in any JRE Java 1.8+.  Remember that because Jalview and the getdown launcher
 740 are Java bytecode you can build on one system where you might have gradle, and run
 741 on another where you don't (JRE 1.8+ required).</p>
 742 </blockquote>
 743 <h3 id="java-11-compliant-jdk"><a href="#java-11-compliant-jdk" name="java-11-compliant-jdk" class="anchor"><span class="octicon octicon-link"></span>Java 11 compliant JDK</a></h3>
 744 <h4 id="all-platforms"><a href="#all-platforms" name="all-platforms" class="anchor"><span class="octicon octicon-link"></span>All platforms</a></h4>
 745 <p>We recommend obtaining an OpenJDK JDK 11 (since 11 is the long term support release) from AdoptOpenJDK: <a href="https://adoptopenjdk.net/?variant=openjdk11&amp;jvmVariant=hotspot">https://adoptopenjdk.net/?variant=openjdk11&amp;jvmVariant=hotspot</a>, either the <em>Installer</em> or <code>.zip</code>/<code>.tar.gz</code> variants whichever you prefer (if you're not sure, choose the <em>Installer</em>).</p>
 746 <blockquote>
 747 <h5 id="alternativecli-install-of-adoptopenjdk-11"><a href="#alternativecli-install-of-adoptopenjdk-11" name="alternativecli-install-of-adoptopenjdk-11" class="anchor"><span class="octicon octicon-link"></span>Alternative/CLI install of AdoptOpenJDK 11</a></h5>
 748 <p>You can also install adoptopenjdk11 using either <code>brew</code> (macOS), <code>choco</code> (Windows)
 749 (see the section on <code>gradle</code> and <code>git</code> for more informaiton on <code>brew</code> and <code>choco</code>)
 750 or <code>yum</code> or <code>apt</code> (Linux):</p>
 751 <h6 id="alternative-for-macos-and-homebrew"><a href="#alternative-for-macos-and-homebrew" name="alternative-for-macos-and-homebrew" class="anchor"><span class="octicon octicon-link"></span>alternative for MacOS and Homebrew</a></h6>
 752 <pre><code>brew tap adoptopenjdk/openjdk
 753 brew cask install adoptopenjdk11
 754 </code></pre>
 755 <h6 id="alternative-for-windows-and-chocolatey"><a href="#alternative-for-windows-and-chocolatey" name="alternative-for-windows-and-chocolatey" class="anchor"><span class="octicon octicon-link"></span>alternative for Windows and Chocolatey</a></h6>
 756 <pre><code>choco install adoptopenjdk11
 757 </code></pre>
 758 <h6 id="alternative-for-linux-with-yumapt"><a href="#alternative-for-linux-with-yumapt" name="alternative-for-linux-with-yumapt" class="anchor"><span class="octicon octicon-link"></span>alternative for Linux with yum/apt</a></h6>
 759 <p>see <a href="https://adoptopenjdk.net/installation.html#linux-pkg">https://adoptopenjdk.net/installation.html#linux-pkg</a></p>
 760 </blockquote>
 761 <h3 id="gradle-and-git"><a href="#gradle-and-git" name="gradle-and-git" class="anchor"><span class="octicon octicon-link"></span>gradle and git</a></h3>
 762 <p>You should be able to install the latest (or sufficiently recent) versions of gradle and git using your OS package manager.</p>
 763 <h4 id="macos"><a href="#macos" name="macos" class="anchor"><span class="octicon octicon-link"></span>MacOS</a></h4>
 764 <p>we recommend using <code>brew</code>, which can be installed following the instructions at <a href="https://brew.sh/">https://brew.sh/</a>.
 765 After installing <code>brew</code>, open a Terminal window and type in (using an Administrator privileged user):</p>
 766 <pre><code class="language-bash">brew install gradle git
 767 </code></pre>
 768 <p>or if you aready have them installed but need to upgrade the version:</p>
 769 <pre><code class="language-bash">brew upgrade gradle git
 770 </code></pre>
 771 <h4 id="windows"><a href="#windows" name="windows" class="anchor"><span class="octicon octicon-link"></span>Windows</a></h4>
 772 <p>we suggest using the <strong>Chocolatey</strong> package manager.  See install instructions at <a href="https://chocolatey.org/">https://chocolatey.org/</a>, and you will just need</p>
 773 <pre><code class="language-bash">choco install gradle
 774 choco install git
 775 </code></pre>
 776 <p>Alternatively, you could install a real <code>bash</code> shell and install both <code>gradle</code> and <code>git</code> through <code>apt-get</code>.
 777 See <a href="https://devblogs.microsoft.com/commandline/bash-on-ubuntu-on-windows-download-now-3/">https://devblogs.microsoft.com/commandline/bash-on-ubuntu-on-windows-download-now-3/</a>
 778 for how to install the ubuntu bash shell in Windows 10.</p>
 779 <p>Another alternative would be to install them separately. For <code>gradle</code> follow the instructions at <a href="https://gradle.org/install/">https://gradle.org/install/</a>, and for <code>git</code> here are a couple of suggestions: Git for Windows <a href="https://gitforwindows.org/">https://gitforwindows.org/</a>.
 780 Getting the individual installs working together on the command line will be trickier
 781 so we recommend using Chocolatey or bash.</p>
 782 <h4 id="linux"><a href="#linux" name="linux" class="anchor"><span class="octicon octicon-link"></span>Linux</a></h4>
 783 <p>this will depend on which distribution you're using.</p>
 784 <h5 id="for-debian-based-distributions-eg-mint-ubuntu-debian"><a href="#for-debian-based-distributions-eg-mint-ubuntu-debian" name="for-debian-based-distributions-eg-mint-ubuntu-debian" class="anchor"><span class="octicon octicon-link"></span>For <em>Debian</em> based distributions (e.g. Mint, Ubuntu, Debian)</a></h5>
 785 <p>run</p>
 786 <pre><code class="language-bash"> sudo apt-get install gradle git
 787 </code></pre>
 788 <h5 id="for-rpm-based-distributions-eg-fedora-centos-redhat"><a href="#for-rpm-based-distributions-eg-fedora-centos-redhat" name="for-rpm-based-distributions-eg-fedora-centos-redhat" class="anchor"><span class="octicon octicon-link"></span>for RPM-based distributions (e.g. Fedora, CentOS, RedHat)</a></h5>
 789 <p>run</p>
 790 <pre><code class="language-bash">sudo yum install gradle git
 791 </code></pre>
 792 <p>If you have some other version of linux you'll probably be able to work it out!</p>
 793 <h2 id="downloading-the-jalview-source-tree"><a href="#downloading-the-jalview-source-tree" name="downloading-the-jalview-source-tree" class="anchor"><span class="octicon octicon-link"></span>Downloading the Jalview source tree</a></h2>
 794 <p>This can be done with <code>git</code>.
 795 On the command line, change directory to where you want to download Jalview's build-tree
 796 top level directory.  Then run</p>
 797 <pre><code class="language-bash">git clone http://source.jalview.org/git/jalview.git
 798 </code></pre>
 799 <p>You'll get some progress output and after a minute or two you should have the full
 800 Jalview build-tree in the folder <code>jalview</code>.</p>
 801 <h3 id="whats-in-the-source-tree"><a href="#whats-in-the-source-tree" name="whats-in-the-source-tree" class="anchor"><span class="octicon octicon-link"></span>What's in the source tree?</a></h3>
 802 <p>Jalview is a mature product with its codebase going back many years.  As such it doesn't
 803 have a folder structure that most new gradle projects would have, so you might not
 804 find everything in the place you might expect.  Here's a brief description of what
 805 you might find in the main folders under the <code>jalview</code> tree.</p>
 806 <p>Within the <code>jalview</code> folder you will find (of possible interest):</p>
 807 <table>
 808 <thead>
 809 <tr><th>dir/ or file</th><th>contains</th></tr>
 810 </thead>
 811 <tbody>
 812 <tr><td><code>bin/</code></td><td>used by eclipse for compiled classes -- no need to touch this</td></tr>
 813 <tr><td><code>build/</code></td><td>the gradle build dir</td></tr>
 814 <tr><td><code>classes/</code></td><td>contains the compiled Java classes for the Jalview application</td></tr>
 815 <tr><td><code>dist/</code></td><td>assembled <code>.jar</code> files needed to run Jalview application</td></tr>
 816 <tr><td><code>examples/</code></td><td>example input files usable by Jalview</td></tr>
 817 <tr><td><code>getdown/</code></td><td>the libraries used by the Javliew launcher (getdown)</td></tr>
 818 <tr><td><code>getdown/src/</code></td><td>our modified source for <code>getdown</code></td></tr>
 819 <tr><td><code>getdown/website/</code></td><td>the assembled &quot;download&quot; folder used by getdown for downloads/upgrades</td></tr>
 820 <tr><td><code>getdown/files/</code></td><td>the minimal fileset to launch the Jalview launcher, which can then download the rest of the Jalview application</td></tr>
 821 <tr><td><code>help/</code></td><td>the help documents</td></tr>
 822 <tr><td><code>j8lib/</code></td><td>libraries needed to run Jalview under Java 1.8</td></tr>
 823 <tr><td><code>j11lib/</code></td><td>libraries needed to run Jalivew under Java 11</td></tr>
 824 <tr><td><code>resource/</code></td><td>non-java resources used in the Jalview application</td></tr>
 825 <tr><td><code>src/</code></td><td>the Jalview application source <code>.java</code> files</td></tr>
 826 <tr><td><code>test/</code></td><td>Test class source files</td></tr>
 827 <tr><td><code>utils/</code></td><td>helper applications used in the build process</td></tr>
 828 <tr><td><code>utils/install4j/</code></td><td>files used by the packaging tool, install4j</td></tr>
 829 <tr><td><code>build.gradle</code></td><td>the build file used by gradle</td></tr>
 830 <tr><td><code>gradle.properties</code></td><td>configurable properties for the build process</td></tr>
 831 <tr><td><code>RELEASE</code></td><td>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</td></tr>
 832 </tbody>
 833 </table>
 834 <p>Note that you need a Java 11 JDK to compile Jalview whether your target build is Java 1.8 or Java 11.</p>
 835 <h2 id="building-jalview"><a href="#building-jalview" name="building-jalview" class="anchor"><span class="octicon octicon-link"></span>Building Jalview</a></h2>
 836 <p>You will need to have the Java 11 <code>javac</code> in your path, or alternatively you can configure
 837 gradle to know where this is by putting</p>
 838 <pre><code>org.gradle.java.home=/path_to_jdk_directory
 839 </code></pre>
 840 <p>in the <code>gradle.properties</code> file.</p>
 841 <blockquote>
 842 <p><em>You may want to see some of the other properties you can change at the end of this document.</em></p>
 843 </blockquote>
 844 <h3 id="minimal-jalview-build"><a href="#minimal-jalview-build" name="minimal-jalview-build" class="anchor"><span class="octicon octicon-link"></span>Minimal Jalview Build</a></h3>
 845 <p>To compile the necessary class files, just run</p>
 846 <pre><code class="language-bash">gradle compileJava
 847 </code></pre>
 848 <p>to compile the classes into the <code>classes</code> folder.
 849 You should now be able to run the Jalview application directly with</p>
 850 <pre><code class="language-bash">java -cp &quot;classes:resources:help:j11lib/*&quot; jalview.bin.Jalview
 851 </code></pre>
 852 <p>You can also run with an automatic large memory setting (which will set the maximum
 853 memory heap of the Jalview JVM to 90% of your local physical memory) and docked icon setting
 854 (if possible in your OS) with</p>
 855 <pre><code class="language-bash">java -cp &quot;classes:resources:help:j11lib/*&quot; jalview.bin.Launcher
 856 </code></pre>
 857 <blockquote>
 858 <p><em>You must use just &quot;<code>j11lib/*</code>&quot; and not &quot;<code>j11lib/*.jar</code>&quot; as this is a special Java
 859 classpath argument wildcard interpreted by <code>java</code>, <strong>not</strong> a shell expansion wildcard interpreted
 860 by the shell.</em></p>
 861 </blockquote>
 862 <p>Note that <code>jalview.bin.Launcher</code> is a simplified launcher class that re-launches <code>jalview.bin.Jalview</code>
 863 with the same JRE (<em>not</em> the same JVM instance), classpath and arguments, but with an automatically determined <code>-Xmx...</code>
 864 memory setting if one hasn't been provided.</p>
 865 <h3 id="jalview-in-a-jar-file"><a href="#jalview-in-a-jar-file" name="jalview-in-a-jar-file" class="anchor"><span class="octicon octicon-link"></span>Jalview in a Jar File</a></h3>
 866 <p>To package the <code>classes</code>, <code>resources</code>, and <code>help</code> into one jar, you can run</p>
 867 <pre><code class="language-bash">gradle jar
 868 </code></pre>
 869 <p>which assembles the Jalview classes and resources into <code>dist/jalview.jar</code></p>
 870 <p>To run this, use</p>
 871 <pre><code class="language-bash">java -cp &quot;dist/jalview.jar:j11lib/*&quot; jalview.bin.Jalview
 872 </code></pre>
 873 <h3 id="distributed-jar-files"><a href="#distributed-jar-files" name="distributed-jar-files" class="anchor"><span class="octicon octicon-link"></span>Distributed Jar Files</a></h3>
 874 <p>To simplify this, all required <code>.jar</code> files can be assembled into the <code>dist</code> folder
 875 using</p>
 876 <pre><code class="language-bash">gradle makeDist
 877 </code></pre>
 878 <p>which puts all required jar files into <code>dist</code> so you can run with</p>
 879 <pre><code class="language-bash">java -cp &quot;dist/*&quot; jalview.bin.Jalview
 880 </code></pre>
 881 <h3 id="single-shadow-jar-file"><a href="#single-shadow-jar-file" name="single-shadow-jar-file" class="anchor"><span class="octicon octicon-link"></span>Single <em>shadow</em> Jar File</a></h3>
 882 <p>The shadow jar file is a single <code>.jar</code> that contains all required classes and resources from <code>jalview.jar</code>
 883 and all of the supporting libraries in <code>j11lib/*.jar</code> merged into one <code>.jar</code> archive
 884 file.  A default launching class (<code>MAIN-CLASS: jalview.bin.Launcher</code>) is specified in the <code>.jar</code>
 885 manifest file (<code>META/MANIFEST.MF</code>) so a start class doesn't need to be specified.</p>
 886 <p>Build the shadow jar file in <code>build/libs/jalview-all-VERSION-j11.jar</code> with</p>
 887 <pre><code class="language-bash">gradle shadowJar
 888 </code></pre>
 889 <p><strong>NB</strong> <code>VERSION</code> will be replaced with a version number or &quot;<code>DEVELOPMENT</code>&quot; or &quot;<code>TEST</code>&quot; depending on how the branch is set up.</p>
 890 <p>Run it with</p>
 891 <pre><code class="language-bash">java -jar build/libs/jalview-all-VERSION-j11.jar
 892 </code></pre>
 893 <p>Because no arguments are required, most OSes will associate a <code>.jar</code> file with the
 894 <code>java</code> application (if this has been installed through the OS and not just a local
 895 unzip) as a <code>-jar</code> argument so you may find you can launch <code>jalview-all-VERSION-j11.jar</code>
 896 just by double-clicking on it)!</p>
 897 <blockquote>
 898 <p>The <code>shadowJar</code> task is not a requirement for any other task, so to build the shadow
 899 jar file you must specify the <code>shadowJar</code> task.</p>
 900 </blockquote>
 901 <blockquote>
 902 <p>The shadow jar file represents probably the simplest way to distribute the Jalview application to machines that already have a Java 11 installed,
 903 although without the many and compelling benefits of the <code>getdown</code> launcher.</p>
 904 </blockquote>
 905 <h3 id="building-the-getdown-launcher"><a href="#building-the-getdown-launcher" name="building-the-getdown-launcher" class="anchor"><span class="octicon octicon-link"></span>Building the <code>getdown</code> launcher</a></h3>
 906 <p>We have made significant customisations to the <code>getdown</code> launcher which you can find
 907 in <code>getdown/src/getdown</code>.</p>
 908 <blockquote>
 909 <p>You don't need to build this afresh as the required <code>gradle-core.jar</code>
 910 and <code>gradle-launcher.jar</code> files are already distributed in <code>j11lib</code> and <code>getdown/lib</code> but if you want to, then
 911 you'll need a working Maven and also a Java 8 JDK.  Ensure the Java 8 <code>javac</code> is forefront
 912 in your path and do</p>
 913 <pre><code class="language-bash">cd getdown/src/getdown
 914 mvn clean package -Dgetdown.host.whitelist=&quot;jalview.org,*.jalview.org&quot;
 915 </code></pre>
 916 <p>and you will find the required <code>.jar</code> files in <code>core/target/gradle-core-XXX.jar</code>
 917 and <code>launcher/target/gradle-launcher-XXX.jar</code>.  The <code>gradle-core.jar</code> should then be copied
 918 to all three of the <code>j8lib</code>, <code>j11lib</code> and <code>getdown/lib</code> folders, whilst the <code>gradle-launcher.jar</code> only
 919 needs to be copied to <code>getdown/lib</code>.</p>
 920 <p>The <code>mvn</code> command should ideally include the <code>-Dgetdown.host.whitelist=*.jalview.org</code> setting.
 921 This, and the necessary file copying commands, can be found in <code>getdown/src/getdown/mvn_cmd</code>.</p>
 922 </blockquote>
 923 <p>To assemble Jalview with <code>getdown</code> use the following gradle task:</p>
 924 <pre><code class="language-bash">gradle getdown
 925 </code></pre>
 926 <p>This puts all the necessary files to launch Jalview with <code>getdown</code>
 927 into <code>getdown/website/11/</code>.  This could be treated as the reference folder
 928 for <code>getdown</code>, which is where a getdown launcher will check to see if the Jalview application
 929 files it has are up to date, and download if they aren't or it simply doesn't have
 930 them.</p>
 931 <p>A minimal getdown-launcher can be found in <code>getdown/files/11/</code> which checks its up-to-date
 932 status with (the absolute path to) <code>getdown/website/11/</code>.</p>
 933 <p>This can be launched with</p>
 934 <pre><code class="language-bash">java -jar getdown/files/11/getdown-launcher.jar getdown/files/11/ jalview
 935 </code></pre>
 936 <blockquote>
 937 <p>We've already met the <code>-jar file.jar</code> arguments.  The next argument is the working folder for
 938 getdown, and the final argument, &quot;<code>jalview</code>&quot;, is a getdown application id (only &quot;<code>jalview</code>&quot;
 939 is defined here).</p>
 940 </blockquote>
 941 <h3 id="running-tests"><a href="#running-tests" name="running-tests" class="anchor"><span class="octicon octicon-link"></span>Running tests</a></h3>
 942 <p>There are substantial tests written for Jalview that use TestNG, which you can run with</p>
 943 <pre><code class="language-bash">gradle test
 944 </code></pre>
 945 <p>These normally take around 5 - 10 minutes to complete and outputs its full results into
 946 the <code>tests/</code> folder.  A summary of results should appear in your console.</p>
 947 <p>You can run different defined groups of tests with</p>
 948 <pre><code class="language-bash">gradle test -PtestngGroups=Network
 949 </code></pre>
 950 <p>Available groups include Functional (default), Network, External.</p>
 951 <h4 id="excluding-some-tests"><a href="#excluding-some-tests" name="excluding-some-tests" class="anchor"><span class="octicon octicon-link"></span>Excluding some tests</a></h4>
 952 <p>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.</p>
 953 <p>To exclude one or more groups of tests, add them as a comma separated list in testngExcludedGroups.</p>
 954 <pre><code class="language-bash">gradle test -PtestngExcludedGroups=Not-bamboo
 955 </code></pre>
 956 <h3 id="installer-packaging-with-install4j"><a href="#installer-packaging-with-install4j" name="installer-packaging-with-install4j" class="anchor"><span class="octicon octicon-link"></span>Installer packaging with <em>install4j</em></a></h3>
 957 <p>Jalview is currently using <em>install4j</em> <a href="https://www.ej-technologies.com/products/install4j/overview.html">https://www.ej-technologies.com/products/install4j/overview.html</a>
 958 as its installer packaging tool.</p>
 959 <p>If you have a licensed installation of <em>install4j</em> you can build Jalview installers
 960 by running</p>
 961 <pre><code class="language-bash">gradle installers
 962 </code></pre>
 963 <p>though you may need to fiddle with the <code>install4j</code> and <code>copyInstall4jTemplate</code> tasks
 964 in <code>build.gradle</code> file to point to your installation of <em>install4j</em> and also to bundled
 965 JREs if you want to bundle those into the installers.</p>
 966 <p>If you want more details, get in touch on our development mailing list <a href="mailto:jalview-dev@jalview.org">jalview-dev@jalview.org</a>.
 967 Sign up at <a href="http://www.compbio.dundee.ac.uk/mailman/listinfo/jalview-dev">http://www.compbio.dundee.ac.uk/mailman/listinfo/jalview-dev</a>.</p>
 968 <h2 id="gradle-properties"><a href="#gradle-properties" name="gradle-properties" class="anchor"><span class="octicon octicon-link"></span>Gradle properties</a></h2>
 969 <p>There are a lot of properties configured in <code>gradle.properties</code> which we strongly recommend
 970 being left as they are unless you have a specific problem with the build process.</p>
 971 <p>There are a few gradle properties you might want to set on the command line with the
 972 <code>-P</code> flag when building a version of Jalview with specific requirements:</p>
 973 <h4 id="java-version"><a href="#java-version" name="java-version" class="anchor"><span class="octicon octicon-link"></span><code>JAVA_VERSION</code></a></h4>
 974 <p>This changes the <em>target</em> java bytecode version</p>
 975 <blockquote>
 976 <p>NOTE that you will need to use a Java 11 (or greater) JDK Java compiler to build
 977 Jalview for any byte-code target version.</p>
 978 </blockquote>
 979 <p>Valid values are <code>11</code> and <code>1.8</code>.</p>
 980 <p>e.g.</p>
 981 <pre><code class="language-bash">gradle shadowJar -PJAVA_VERSION=1.8
 982 </code></pre>
 983 <p>When using <code>-PJAVA_VERSION=1.8</code> the libraries from <code>j8lib</code> (instead of <code>j11lib</code>) will be used in the compile<br />
 984 and runtime classpath and also used in the <code>makeDist</code> build step.  Where a Java version of <code>11</code> is used in folder and file names, it will
 985 instead use <code>1.8</code>.  Also if you are building installer packages with <em>install4j</em> the
 986 package builder will look for JRE 1.8 bundles to package in the installers.</p>
 987 <blockquote>
 988 <p>Note that continued development of Jalview will assume a Java 11+ runtime environment,
 989 the 2.11.0 release will run under a Java 1.8 JRE with a few minor features disabled.</p>
 990 </blockquote>
 991 <h4 id="channel"><a href="#channel" name="channel" class="anchor"><span class="octicon octicon-link"></span><code>CHANNEL</code></a></h4>
 992 <p>This changes the <code>appbase</code> setting in <code>getdown.txt</code> (<code>appbase</code> is where the getdown launcher
 993 looks to see if there's an updated file) to point to a particular Jalview channel or some other appropriate
 994 place to look for required files.  If the selected channel type requires the getdown <code>appbase</code> to be a local
 995 directory on the filesystem (instead of a website URL) then a modified version of the <code>getdown-launcher.jar</code> will
 996 be used to allow this.  The two versions of the <code>getdown-launcher.jar</code> can be found in <code>getdown/lib</code>.
 997 Some other variables used in the build process might also be set differently depending on the value of <code>CHANNEL</code>
 998 to allow smooth operation of getdown in the given context.</p>
 999 <p>There are several values of <code>CHANNEL</code> that can be chosen, with a default of <code>LOCAL</code>.  Here's what they're for and what they do:</p>
1000 <ul>
1001 <li><code>LOCAL</code>: This is for running the compiled application from the development directory.
1002 It will set
1003 <ul>
1004 <li><code>appbase</code> as <code>file://PATH/TO/YOUR/DEVELOPMENT/getdown/files/JAVA_VERSION</code>
1005 (e.g. <code>file://home/user/git/jalview/getdown/files/11</code>)</li>
1006 <li>application subdir as <code>alt</code></li>
1007 <li>Getdown launcher can use a <code>file://</code> scheme appbase.</li>
1008 </ul>
1009 </li>
1010 <li><code>BUILD</code>: This is for creating an appbase channel on the build server by an automatic or manually started build.
1011 It will set
1012 <ul>
1013 <li><code>appbase</code> as <code>https://builds.jalview.org/browse/${bamboo_planKey}/latest/artifact/shared/getdown-channel/JAVA_VERSION</code>
1014 Note that bamboo_planKey should be set by the build plan with <code>-Pbamboo_planKey=${bamboo.planKey}</code></li>
1015 <li>application subdir as <code>alt</code></li>
1016 <li>Getdown launcher cannot use a <code>file://</code> scheme appbase.</li>
1017 </ul>
1018 </li>
1019 <li><code>DEVELOP</code>: This is for creating a <code>develop</code> appbase channel on the main web server. This won't become live until the actual getdown artefact is synced to the web server.
1020 It will set
1021 <ul>
1022 <li><code>appbase</code> as <code>http://www.jalview.org/getdown/develop/JAVA_VERSION</code></li>
1023 <li>application subdir as <code>alt</code></li>
1024 <li>Getdown launcher cannot use a <code>file://</code> scheme appbase.</li>
1025 </ul>
1026 </li>
1027 <li><code>SCRATCH-NAME</code>: 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 <code>release</code> or <code>develop</code> channels.  The value of <code>NAME</code> can be any &quot;word-character&quot; [A-Za-z0-9_]
1028 It will set
1029 <ul>
1030 <li><code>appbase</code> as <code>http://www.jalview.org/getdown/SCRATCH-NAME/JAVA_VERSION</code></li>
1031 <li>application subdir as <code>alt</code></li>
1032 <li>Getdown launcher cannot use a <code>file://</code> scheme appbase.</li>
1033 </ul>
1034 </li>
1035 <li><code>TEST-LOCAL</code>:  Like <code>SCRATCH</code> but with a specific <code>test-local</code> channel name and a local filesystem appbase.  This is meant for testing an over-the-air update on the local filesystem.  An extra property <code>LOCALDIR</code> must be given (e.g. <code>-PLOCALDIR=/home/user/tmp/test</code>)
1036 It will set
1037 <ul>
1038 <li><code>appbase</code> as <code>file://${LOCALDIR}</code></li>
1039 <li>application subdir as <code>alt</code></li>
1040 <li>Getdown launcher can use a <code>file://</code> scheme appbase.</li>
1041 </ul>
1042 </li>
1043 <li><code>TEST-RELEASE</code>:  Like <code>SCRATCH</code> but with a specific <code>test-release</code> 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 <code>release</code> or <code>develop</code> channels.
1044 It will set
1045 <ul>
1046 <li><code>appbase</code> as <code>http://www.jalview.org/getdown/test-release/JAVA_VERSION</code></li>
1047 <li>application subdir as <code>alt</code></li>
1048 <li>Getdown launcher cannot use a <code>file://</code> scheme appbase.</li>
1049 </ul>
1050 </li>
1051 <li><code>RELEASE</code>:  This is for an actual release build, and will use an appbase on the main web server with the main <code>release</code> channel name.  This won't become live until the actual getdown artefact is synced to the web server.
1052 It will set
1053 <ul>
1054 <li><code>appbase</code> as <code>http://www.jalview.org/getdown/release/JAVA_VERSION</code></li>
1055 <li>application subdir as <code>release</code></li>
1056 <li>Getdown launcher cannot use a <code>file://</code> scheme appbase.</li>
1057 </ul>
1058 </li>
1059 <li><code>ARCHIVE</code>:  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 <code>archive/JALVIEW_VERSION</code> channel name.  This won't become live until the actual getdown artefact is synced to the web server.
1060 You must also specify an <code>ARCHIVEDIR</code> property that points to an earlier version of Jalview with a <code>dist</code> directory containing the required jar files.  This should create a getdown structure and digest with the older jar files.
1061 It will set
1062 <ul>
1063 <li><code>appbase</code> as <code>http://www.jalview.org/getdown/archive/JALVIEW_VERSION/JAVA_VERSION</code></li>
1064 <li>application subdir as <code>alt</code></li>
1065 <li>Getdown launcher cannot use a <code>file://</code> scheme appbase.</li>
1066 </ul>
1067 </li>
1068 <li><code>ARCHIVELOCAL</code>:  Like <code>ARCHIVE</code> but with a local filesystem appbase for local testing.
1069 You must also specify an <code>ARCHIVEDIR</code> property that points to an earlier version of Jalview with a <code>dist</code> directory containing the required jar files.  This should create a getdown structure and digest with the older jar files.
1070 It will set
1071 <ul>
1072 <li><code>appbase</code> as <code>file://PATH/TO/YOUR/DEVELOPMENT/getdown/website/JAVA_VERSION</code> (where the old jars will have been copied and digested)</li>
1073 <li>application subdir as <code>alt</code></li>
1074 <li>Getdown launcher can use a <code>file://</code> scheme appbase.</li>
1075 </ul>
1076 </li>
1077 </ul>
1078 <p>e.g.</p>
1079 <pre><code class="language-bash">gradle getdown -PCHANNEL=SCRATCH-my_test_version
1080 </code></pre>
1081 <h4 id="jalview-version-and-the-release-file"><a href="#jalview-version-and-the-release-file" name="jalview-version-and-the-release-file" class="anchor"><span class="octicon octicon-link"></span>JALVIEW_VERSION and the RELEASE file</a></h4>
1082 <p>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 <code>jalview.version</code> property specified in the RELEASE file:</p>
1083 <ul>
1084 <li><code>CHANNEL=RELEASE</code> will set version to jalview.version</li>
1085 <li><code>CHANNEL=TEST or DEVELOP</code> will append '-test' or '-develop' to jalview.version</li>
1086 </ul>
1087 <p>It is also possible to specify a custom location for the RELEASE file via an optional JALVIEW_RELEASE_FILE property.</p>
1088 <h4 id="install4jmediatypes"><a href="#install4jmediatypes" name="install4jmediatypes" class="anchor"><span class="octicon octicon-link"></span><code>install4jMediaTypes</code></a></h4>
1089 <p>If you are building <em>install4j</em> installers (requires <em>install4j</em> to be installed) then this property specifies a comma-separated
1090 list of media types (i.e. platform specific installers) <em>install4j</em> should actually build.</p>
1091 <p>Currently the valid values are
1092 <code>linuxDeb</code>,
1093 <code>linuxRPM</code>,
1094 <code>macosArchive</code>,
1095 <code>unixArchive</code>,
1096 <code>unixInstaller</code>,
1097 <code>windows</code></p>
1098 <p>The default value is all of them.</p>
1099 <p>e.g.</p>
1100 <pre><code class="language-bash">gradle installers -PJAVA_VERSION=1.8 -Pinstall4jMediaTypes=macosArchive
1101 </code></pre>
1102 <p>To get an up-to-date list of possible values, you can run</p>
1103 <pre><code class="language-bash">perl -n -e 'm/^\s*&lt;(\w+)[^&gt;]*\bmediaFileName=/ &amp;&amp; print &quot;$1\n&quot;;' utils/install4j/install4j_template.install4j  | sort -u
1104 </code></pre>
1105 <p>in the <code>jalview</code> root folder.</p>
1106 <h2 id="enabling-code-coverage-with-openclover"><a href="#enabling-code-coverage-with-openclover" name="enabling-code-coverage-with-openclover" class="anchor"><span class="octicon octicon-link"></span>Enabling Code Coverage with OpenClover</a></h2>
1107 <p>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.</p>
1108 <p><code>gradle -Pclover=true test cloverReport</code></p>
1109 <h4 id="troubleshooting-report-generation"><a href="#troubleshooting-report-generation" name="troubleshooting-report-generation" class="anchor"><span class="octicon octicon-link"></span>Troubleshooting report generation</a></h4>
1110 <p>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:</p>
1111 <h5 id="jvm-memory-settings---increase-if-out-of-memory-errors-are-reported"><a href="#jvm-memory-settings---increase-if-out-of-memory-errors-are-reported" name="jvm-memory-settings---increase-if-out-of-memory-errors-are-reported" class="anchor"><span class="octicon octicon-link"></span>JVM Memory settings - increase if out of memory errors are reported</a></h5>
1112 <p><code>cloverReportJVMHeap = 2g</code></p>
1113 <h5 id="-dfileencodingutf-8-is-an-essential-parameters-for-report-generation-add-additional-ones-separated-by-a-space"><a href="#-dfileencodingutf-8-is-an-essential-parameters-for-report-generation-add-additional-ones-separated-by-a-space" name="-dfileencodingutf-8-is-an-essential-parameters-for-report-generation-add-additional-ones-separated-by-a-space" class="anchor"><span class="octicon octicon-link"></span>-Dfile.encoding=UTF-8 is an essential parameters for report generation. Add additional ones separated by a space.</a></h5>
1114 <p><code>cloverReportJVMArgs = -Dfile.encoding=UTF-8</code></p>
1115 <h5 id="add--v-to-debug-velocity-html-generation-errors-or--d-to-track-more-detailed-issues-with-the-coverage-database"><a href="#add--v-to-debug-velocity-html-generation-errors-or--d-to-track-more-detailed-issues-with-the-coverage-database" name="add--v-to-debug-velocity-html-generation-errors-or--d-to-track-more-detailed-issues-with-the-coverage-database" class="anchor"><span class="octicon octicon-link"></span>Add -v to debug velocity html generation errors, or -d to track more detailed issues with the coverage database</a></h5>
1116 <p><code>cloverReportHTMLOptions =</code></p>
1117 <h5 id="-v-for-verbose--d-for-debug-level-messages-as-above"><a href="#-v-for-verbose--d-for-debug-level-messages-as-above" name="-v-for-verbose--d-for-debug-level-messages-as-above" class="anchor"><span class="octicon octicon-link"></span>-v for verbose, -d for debug level messages (as above)</a></h5>
1118 <p><code>cloverReportXMLOptions =</code></p>
1119 <p><em>Note</em> 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.</p>
1120 <h2 id="setting-up-in-eclipse-ide"><a href="#setting-up-in-eclipse-ide" name="setting-up-in-eclipse-ide" class="anchor"><span class="octicon octicon-link"></span>Setting up in Eclipse IDE</a></h2>
1121 <h3 id="installing-eclipse-ide"><a href="#installing-eclipse-ide" name="installing-eclipse-ide" class="anchor"><span class="octicon octicon-link"></span>Installing Eclipse IDE</a></h3>
1122 <p>We develop in Eclipse, and support settings to develop and save Jalview source code
1123 in our preferred style.  We also support running the Jalview application, debugging
1124 and running tests with TestNG from within Eclipse.</p>
1125 <p>To get Jalview set up as a project in Eclipse, we recommend using at least the 2020-03
1126 version of Eclipse IDE for Java Developers which you can download from the Eclipse
1127 website: <a href="https://www.eclipse.org/downloads/">https://www.eclipse.org/downloads/</a>.  Since Eclipse 2020-03 you are encouraged to use the Eclipse Installer (see the Eclipse Downloads page).
1128 In the installer, when given a choice of packages for Eclipse you should choose the &quot;Eclipse IDE for Enterprise Java Developers&quot; package.</p>
1129 <p><img src="./images/eclipse_installer.png" alt="" title="Eclipse Installer screenshot" /></p>
1130 <p>Once Eclipse is installed, we also recommend installing several plugins from the Eclipse Marketplace.</p>
1131 <p>Some of these should already be installed with the Enterprise Java Developer package:</p>
1132 <ol>
1133 <li>Buildship Gradle Integration 3.0 (or greater)</li>
1134 <li>EclEmma Java Code Coverage</li>
1135 <li>Egit - Git Integration for Eclipse</li>
1136 </ol>
1137 <p>To install the others, launch Eclipse, and go to Help-&gt;Eclipse Marketplace...</p>
1138 <p>Search for and install:</p>
1139 <ol>
1140 <li>Groovy Development Tools 3.4.0 (or greater)</li>
1141 <li>Checkstyle Plug-in (optional)</li>
1142 <li>TestNG for Eclipse (optional -- only needed if you want to run tests from Eclipse)</li>
1143 </ol>
1144 <blockquote>
1145 <p>At time of writing, TestNG for Eclipse does not show up in the Eclipse Marketplace
1146 as the latest released version does not install in Eclipse 2020-03.
1147 However, you can install a working release of TestNG for Eclipse by going to</p>
1148 <p>Help-&gt;Install New Software...</p>
1149 <p>and entering</p>
1150 <p><code>TestNG Release - https://dl.bintray.com/testng-team/testng-eclipse-release</code></p>
1151 <p>into the <em>Work with</em> box and click on the <em>Add...</em> button.</p>
1152 <p>Eclipse might pause for a bit with the word <em>Pending</em> in the table below at this point, but it will eventually list TestNG with
1153 a selection box under the <em>Name</em> column.</p>
1154 <p>Select <em>TestNG</em> and carry on through the
1155 install process to install the TestNG plugin.</p>
1156 </blockquote>
1157 <p>After installing the plugins, check that Java 11 is set up in Eclipse as the default JRE (see section <a href="#java-11-compliant-jdk">Java 11 compliant JDK</a>).</p>
1158 <p>To do this go to Preferences (Eclipse-&gt;Preferences in macOS, File-&gt;Preferences
1159 on Windows or Window-&gt;Preferences on Linux) and find</p>
1160 <p>Java -&gt; Installed JREs</p>
1161 <p>If your Java 11 installation is not listed, click on</p>
1162 <p><em>Add</em> -&gt; Standard VM -&gt; <em>Next</em></p>
1163 <p>and enter the JRE home.  You can browse to where it is installed. Give it a name (like &quot;AdoptOpenJDK 11&quot;).  Select this JDK
1164 as the default JRE and click on <em>Apply and Close</em>.</p>
1165 <p>You can now import Jalview.</p>
1166 <h3 id="importing-jalview-as-an-eclipse-project"><a href="#importing-jalview-as-an-eclipse-project" name="importing-jalview-as-an-eclipse-project" class="anchor"><span class="octicon octicon-link"></span>Importing Jalview as an Eclipse project</a></h3>
1167 <h4 id="importing-an-already-downloaded-git-repo"><a href="#importing-an-already-downloaded-git-repo" name="importing-an-already-downloaded-git-repo" class="anchor"><span class="octicon octicon-link"></span>Importing an already downloaded git repo</a></h4>
1168 <p>If you have already downloaded Jalview using <code>git clone</code> then you can import this folder into Eclipse directly.</p>
1169 <p><strong>Before importing the cloned git repo you must create the Eclipse project files.</strong> You can do this by either running</p>
1170 <p><code>gradle eclipse</code></p>
1171 <p>or</p>
1172 <p>Unzipping the file <code>utils/eclipse/eclipse_startup_files.zip</code> in the base repo directory (<code>jalview</code>)</p>
1173 <p>It is important to import
1174 Jalview as a Gradle project (not as a Java project), so go to</p>
1175 <p>File-&gt;Import...</p>
1176 <p>find and select</p>
1177 <p>Gradle-&gt;Existing Gradle Project</p>
1178 <p>and then click on the <em>Next</em> button.</p>
1179 <p>In the following options, it is the <strong>Project Root Directory</strong> you should set to be the
1180 <code>jalview</code> folder that git downloaded.  Then you can click on the <em>Finish</em> button.</p>
1181 <h4 id="using-eclipse-ide-to-download-the-git-repo"><a href="#using-eclipse-ide-to-download-the-git-repo" name="using-eclipse-ide-to-download-the-git-repo" class="anchor"><span class="octicon octicon-link"></span>Using Eclipse IDE to download the git repo</a></h4>
1182 <p>If you don't have git as a command line tool or would prefer to work entirely within Eclipse IDE then
1183 Eclipse's eGit plugin can set up a git repo of the jalview source.  Go to</p>
1184 <p>File-&gt;Import...</p>
1185 <p>Find and select</p>
1186 <p>Git-&gt;Projects from Git</p>
1187 <p>and then click on the <em>Next</em> button.</p>
1188 <p>Then select Clone URI and click on <em>Next</em>.</p>
1189 <p>In the next window (Source Git Repository) you should put the <code>git clone</code> URL in the text box labelled <code>URI</code>.  If you have a Jalview developer account (with a username and password for the Jalview git repository) then you should enter
1190 <code>https://source.jalview.org/git/jalview.git</code>.
1191 If you do not have a Jalview developer account then you should enter
1192 <code>http://source.jalview.org/git/jalview.git</code>.
1193 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.</p>
1194 <blockquote>
1195 <p>You can sign up for a Jalview developer account at <a href="https://source.jalview.org/crucible/">https://source.jalview.org/crucible/</a></p>
1196 </blockquote>
1197 <p>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.</p>
1198 <p><img src="./images/eclipse_egit_connection.png" alt="Eclipse eGit connection configuration" /></p>
1199 <p>Click on the <em>Next</em> button.</p>
1200 <p>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 <code>develop</code> branch so you can click on the <em>Deselect All</em> button, find the <code>develop</code> branch (the filter text helps), select that, and then click on the <em>Next</em> button.</p>
1201 <p>Choose a directory to your copy of the git repo in, and leave the other options as they are and click on the <em>Next</em> button.  The next stage may take a minute or two as it checks out the selected branch(es) from the Jalview git repository.</p>
1202 <p>When it has finished it is important to select <strong>Import as general project</strong> and then click on <em>Next</em>.</p>
1203 <blockquote>
1204 <p>Ideally there would be an <em>Import as gradle project</em> here but there isn't -- we'll sort that out later.</p>
1205 </blockquote>
1206 <p><img src="./images/eclipse_egit_import.png" alt="Eclipse eGit import choice" /></p>
1207 <p>Click on the <em>Next</em> button.</p>
1208 <p>You can change the project name here.  By default it will show as <strong>jalview</strong> 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.</p>
1209 <p>Click on <em>Finish</em>!</p>
1210 <p>However, we haven't finished...</p>
1211 <p>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!</p>
1212 <p>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.</p>
1213 <p><img src="./images/eclipse_add_gradle_nature.png" alt="Eclipse Add Gradle Nature" /></p>
1214 <p>The project should now reconfigure itself using the <code>build.gradle</code> file to dynamically set various aspects of the project including classpath.</p>
1215 <h4 id="additional-views"><a href="#additional-views" name="additional-views" class="anchor"><span class="octicon octicon-link"></span>Additional views</a></h4>
1216 <p>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
1217 Window-&gt;Show View-&gt;Console
1218 and
1219 Window-&gt;Show View-&gt;Other...
1220 Filter with the word &quot;gradle&quot; and choose both <strong>Gradle Executions</strong> and <strong>Gradle Tasks</strong> and then click on the <em>Open</em> button.</p>
1221 <p>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 <a href="https://docs.google.com/document/d/1lZo_pZRkazDBJGNachXr6qCVlw8ByuMYG6e9SZlPUlQ/edit?usp=sharing">https://docs.google.com/document/d/1lZo_pZRkazDBJGNachXr6qCVlw8ByuMYG6e9SZlPUlQ/edit?usp=sharing</a></p>
1222 <hr />
1223 <p><a href="mailto:help@jalview.org">Jalview Development Team</a></p>
1224
1225   </body>
1226 </html>