doc/building.html

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