| <!DOCTYPE html> |
| <html lang="en"> |
| <head> |
| <meta charset="UTF-8"> |
| <meta http-equiv="X-UA-Compatible" content="IE=edge"> |
| <meta name="viewport" content="width=device-width, initial-scale=1.0"> |
| <meta name="generator" content="Asciidoctor 2.0.12"> |
| <meta name="author" content="Copyright (c) 2010, 2021 Contributors to the Eclipse Foundation"> |
| <title>Eclipse ESCET™ documentation (Incubation)</title> |
| <link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Open+Sans:300,300italic,400,400italic,600,600italic%7CNoto+Serif:400,400italic,700,700italic%7CDroid+Sans+Mono:400,700"> |
| <style> |
| /* Asciidoctor default stylesheet | MIT License | https://asciidoctor.org */ |
| /* Uncomment @import statement to use as custom stylesheet */ |
| /*@import "https://fonts.googleapis.com/css?family=Open+Sans:300,300italic,400,400italic,600,600italic%7CNoto+Serif:400,400italic,700,700italic%7CDroid+Sans+Mono:400,700";*/ |
| article,aside,details,figcaption,figure,footer,header,hgroup,main,nav,section{display:block} |
| audio,video{display:inline-block} |
| audio:not([controls]){display:none;height:0} |
| html{font-family:sans-serif;-ms-text-size-adjust:100%;-webkit-text-size-adjust:100%} |
| a{background:none} |
| a:focus{outline:thin dotted} |
| a:active,a:hover{outline:0} |
| h1{font-size:2em;margin:.67em 0} |
| abbr[title]{border-bottom:1px dotted} |
| b,strong{font-weight:bold} |
| dfn{font-style:italic} |
| hr{-moz-box-sizing:content-box;box-sizing:content-box;height:0} |
| mark{background:#ff0;color:#000} |
| code,kbd,pre,samp{font-family:monospace;font-size:1em} |
| pre{white-space:pre-wrap} |
| q{quotes:"\201C" "\201D" "\2018" "\2019"} |
| small{font-size:80%} |
| sub,sup{font-size:75%;line-height:0;position:relative;vertical-align:baseline} |
| sup{top:-.5em} |
| sub{bottom:-.25em} |
| img{border:0} |
| svg:not(:root){overflow:hidden} |
| figure{margin:0} |
| fieldset{border:1px solid silver;margin:0 2px;padding:.35em .625em .75em} |
| legend{border:0;padding:0} |
| button,input,select,textarea{font-family:inherit;font-size:100%;margin:0} |
| button,input{line-height:normal} |
| button,select{text-transform:none} |
| button,html input[type="button"],input[type="reset"],input[type="submit"]{-webkit-appearance:button;cursor:pointer} |
| button[disabled],html input[disabled]{cursor:default} |
| input[type="checkbox"],input[type="radio"]{box-sizing:border-box;padding:0} |
| button::-moz-focus-inner,input::-moz-focus-inner{border:0;padding:0} |
| textarea{overflow:auto;vertical-align:top} |
| table{border-collapse:collapse;border-spacing:0} |
| *,*::before,*::after{-moz-box-sizing:border-box;-webkit-box-sizing:border-box;box-sizing:border-box} |
| html,body{font-size:100%} |
| body{background:#fff;color:rgba(0,0,0,.8);padding:0;margin:0;font-family:"Noto Serif","DejaVu Serif",serif;font-weight:400;font-style:normal;line-height:1;position:relative;cursor:auto;tab-size:4;word-wrap:anywhere;-moz-osx-font-smoothing:grayscale;-webkit-font-smoothing:antialiased} |
| a:hover{cursor:pointer} |
| img,object,embed{max-width:100%;height:auto} |
| object,embed{height:100%} |
| img{-ms-interpolation-mode:bicubic} |
| .left{float:left!important} |
| .right{float:right!important} |
| .text-left{text-align:left!important} |
| .text-right{text-align:right!important} |
| .text-center{text-align:center!important} |
| .text-justify{text-align:justify!important} |
| .hide{display:none} |
| img,object,svg{display:inline-block;vertical-align:middle} |
| textarea{height:auto;min-height:50px} |
| select{width:100%} |
| .subheader,.admonitionblock td.content>.title,.audioblock>.title,.exampleblock>.title,.imageblock>.title,.listingblock>.title,.literalblock>.title,.stemblock>.title,.openblock>.title,.paragraph>.title,.quoteblock>.title,table.tableblock>.title,.verseblock>.title,.videoblock>.title,.dlist>.title,.olist>.title,.ulist>.title,.qlist>.title,.hdlist>.title{line-height:1.45;color:#7a2518;font-weight:400;margin-top:0;margin-bottom:.25em} |
| div,dl,dt,dd,ul,ol,li,h1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6,pre,form,p,blockquote,th,td{margin:0;padding:0} |
| a{color:#2156a5;text-decoration:underline;line-height:inherit} |
| a:hover,a:focus{color:#1d4b8f} |
| a img{border:0} |
| p{font-family:inherit;font-weight:400;font-size:1em;line-height:1.6;margin-bottom:1.25em;text-rendering:optimizeLegibility} |
| p aside{font-size:.875em;line-height:1.35;font-style:italic} |
| h1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6{font-family:"Open Sans","DejaVu Sans",sans-serif;font-weight:300;font-style:normal;color:#ba3925;text-rendering:optimizeLegibility;margin-top:1em;margin-bottom:.5em;line-height:1.0125em} |
| h1 small,h2 small,h3 small,#toctitle small,.sidebarblock>.content>.title small,h4 small,h5 small,h6 small{font-size:60%;color:#e99b8f;line-height:0} |
| h1{font-size:2.125em} |
| h2{font-size:1.6875em} |
| h3,#toctitle,.sidebarblock>.content>.title{font-size:1.375em} |
| h4,h5{font-size:1.125em} |
| h6{font-size:1em} |
| hr{border:solid #dddddf;border-width:1px 0 0;clear:both;margin:1.25em 0 1.1875em;height:0} |
| em,i{font-style:italic;line-height:inherit} |
| strong,b{font-weight:bold;line-height:inherit} |
| small{font-size:60%;line-height:inherit} |
| code{font-family:"Droid Sans Mono","DejaVu Sans Mono",monospace;font-weight:400;color:rgba(0,0,0,.9)} |
| ul,ol,dl{font-size:1em;line-height:1.6;margin-bottom:1.25em;list-style-position:outside;font-family:inherit} |
| ul,ol{margin-left:1.5em} |
| ul li ul,ul li ol{margin-left:1.25em;margin-bottom:0;font-size:1em} |
| ul.square li ul,ul.circle li ul,ul.disc li ul{list-style:inherit} |
| ul.square{list-style-type:square} |
| ul.circle{list-style-type:circle} |
| ul.disc{list-style-type:disc} |
| ol li ul,ol li ol{margin-left:1.25em;margin-bottom:0} |
| dl dt{margin-bottom:.3125em;font-weight:bold} |
| dl dd{margin-bottom:1.25em} |
| abbr,acronym{text-transform:uppercase;font-size:90%;color:rgba(0,0,0,.8);border-bottom:1px dotted #ddd;cursor:help} |
| abbr{text-transform:none} |
| blockquote{margin:0 0 1.25em;padding:.5625em 1.25em 0 1.1875em;border-left:1px solid #ddd} |
| blockquote cite{display:block;font-size:.9375em;color:rgba(0,0,0,.6)} |
| blockquote cite::before{content:"\2014 \0020"} |
| blockquote cite a,blockquote cite a:visited{color:rgba(0,0,0,.6)} |
| blockquote,blockquote p{line-height:1.6;color:rgba(0,0,0,.85)} |
| @media screen and (min-width:768px){h1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6{line-height:1.2} |
| h1{font-size:2.75em} |
| h2{font-size:2.3125em} |
| h3,#toctitle,.sidebarblock>.content>.title{font-size:1.6875em} |
| h4{font-size:1.4375em}} |
| table{background:#fff;margin-bottom:1.25em;border:solid 1px #dedede;word-wrap:normal} |
| table thead,table tfoot{background:#f7f8f7} |
| table thead tr th,table thead tr td,table tfoot tr th,table tfoot tr td{padding:.5em .625em .625em;font-size:inherit;color:rgba(0,0,0,.8);text-align:left} |
| table tr th,table tr td{padding:.5625em .625em;font-size:inherit;color:rgba(0,0,0,.8)} |
| table tr.even,table tr.alt{background:#f8f8f7} |
| table thead tr th,table tfoot tr th,table tbody tr td,table tr td,table tfoot tr td{line-height:1.6} |
| h1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6{line-height:1.2;word-spacing:-.05em} |
| h1 strong,h2 strong,h3 strong,#toctitle strong,.sidebarblock>.content>.title strong,h4 strong,h5 strong,h6 strong{font-weight:400} |
| .center{margin-left:auto;margin-right:auto} |
| .stretch{width:100%} |
| .clearfix::before,.clearfix::after,.float-group::before,.float-group::after{content:" ";display:table} |
| .clearfix::after,.float-group::after{clear:both} |
| :not(pre).nobreak{word-wrap:normal} |
| :not(pre).nowrap{white-space:nowrap} |
| :not(pre).pre-wrap{white-space:pre-wrap} |
| :not(pre):not([class^=L])>code{font-size:.9375em;font-style:normal!important;letter-spacing:0;padding:.1em .5ex;word-spacing:-.15em;background:#f7f7f8;-webkit-border-radius:4px;border-radius:4px;line-height:1.45;text-rendering:optimizeSpeed} |
| pre{color:rgba(0,0,0,.9);font-family:"Droid Sans Mono","DejaVu Sans Mono",monospace;line-height:1.45;text-rendering:optimizeSpeed} |
| pre code,pre pre{color:inherit;font-size:inherit;line-height:inherit} |
| pre>code{display:block} |
| pre.nowrap,pre.nowrap pre{white-space:pre;word-wrap:normal} |
| em em{font-style:normal} |
| strong strong{font-weight:400} |
| .keyseq{color:rgba(51,51,51,.8)} |
| kbd{font-family:"Droid Sans Mono","DejaVu Sans Mono",monospace;display:inline-block;color:rgba(0,0,0,.8);font-size:.65em;line-height:1.45;background:#f7f7f7;border:1px solid #ccc;-webkit-border-radius:3px;border-radius:3px;-webkit-box-shadow:0 1px 0 rgba(0,0,0,.2),0 0 0 .1em white inset;box-shadow:0 1px 0 rgba(0,0,0,.2),0 0 0 .1em #fff inset;margin:0 .15em;padding:.2em .5em;vertical-align:middle;position:relative;top:-.1em;white-space:nowrap} |
| .keyseq kbd:first-child{margin-left:0} |
| .keyseq kbd:last-child{margin-right:0} |
| .menuseq,.menuref{color:#000} |
| .menuseq b:not(.caret),.menuref{font-weight:inherit} |
| .menuseq{word-spacing:-.02em} |
| .menuseq b.caret{font-size:1.25em;line-height:.8} |
| .menuseq i.caret{font-weight:bold;text-align:center;width:.45em} |
| b.button::before,b.button::after{position:relative;top:-1px;font-weight:400} |
| b.button::before{content:"[";padding:0 3px 0 2px} |
| b.button::after{content:"]";padding:0 2px 0 3px} |
| p a>code:hover{color:rgba(0,0,0,.9)} |
| #header,#content,#footnotes,#footer{width:100%;margin-left:auto;margin-right:auto;margin-top:0;margin-bottom:0;max-width:62.5em;*zoom:1;position:relative;padding-left:.9375em;padding-right:.9375em} |
| #header::before,#header::after,#content::before,#content::after,#footnotes::before,#footnotes::after,#footer::before,#footer::after{content:" ";display:table} |
| #header::after,#content::after,#footnotes::after,#footer::after{clear:both} |
| #content{margin-top:1.25em} |
| #content::before{content:none} |
| #header>h1:first-child{color:rgba(0,0,0,.85);margin-top:2.25rem;margin-bottom:0} |
| #header>h1:first-child+#toc{margin-top:8px;border-top:1px solid #dddddf} |
| #header>h1:only-child,body.toc2 #header>h1:nth-last-child(2){border-bottom:1px solid #dddddf;padding-bottom:8px} |
| #header .details{border-bottom:1px solid #dddddf;line-height:1.45;padding-top:.25em;padding-bottom:.25em;padding-left:.25em;color:rgba(0,0,0,.6);display:-ms-flexbox;display:-webkit-flex;display:flex;-ms-flex-flow:row wrap;-webkit-flex-flow:row wrap;flex-flow:row wrap} |
| #header .details span:first-child{margin-left:-.125em} |
| #header .details span.email a{color:rgba(0,0,0,.85)} |
| #header .details br{display:none} |
| #header .details br+span::before{content:"\00a0\2013\00a0"} |
| #header .details br+span.author::before{content:"\00a0\22c5\00a0";color:rgba(0,0,0,.85)} |
| #header .details br+span#revremark::before{content:"\00a0|\00a0"} |
| #header #revnumber{text-transform:capitalize} |
| #header #revnumber::after{content:"\00a0"} |
| #content>h1:first-child:not([class]){color:rgba(0,0,0,.85);border-bottom:1px solid #dddddf;padding-bottom:8px;margin-top:0;padding-top:1rem;margin-bottom:1.25rem} |
| #toc{border-bottom:1px solid #e7e7e9;padding-bottom:.5em} |
| #toc>ul{margin-left:.125em} |
| #toc ul.sectlevel0>li>a{font-style:italic} |
| #toc ul.sectlevel0 ul.sectlevel1{margin:.5em 0} |
| #toc ul{font-family:"Open Sans","DejaVu Sans",sans-serif;list-style-type:none} |
| #toc li{line-height:1.3334;margin-top:.3334em} |
| #toc a{text-decoration:none} |
| #toc a:active{text-decoration:underline} |
| #toctitle{color:#7a2518;font-size:1.2em} |
| @media screen and (min-width:768px){#toctitle{font-size:1.375em} |
| body.toc2{padding-left:15em;padding-right:0} |
| #toc.toc2{margin-top:0!important;background:#f8f8f7;position:fixed;width:15em;left:0;top:0;border-right:1px solid #e7e7e9;border-top-width:0!important;border-bottom-width:0!important;z-index:1000;padding:1.25em 1em;height:100%;overflow:auto} |
| #toc.toc2 #toctitle{margin-top:0;margin-bottom:.8rem;font-size:1.2em} |
| #toc.toc2>ul{font-size:.9em;margin-bottom:0} |
| #toc.toc2 ul ul{margin-left:0;padding-left:1em} |
| #toc.toc2 ul.sectlevel0 ul.sectlevel1{padding-left:0;margin-top:.5em;margin-bottom:.5em} |
| body.toc2.toc-right{padding-left:0;padding-right:15em} |
| body.toc2.toc-right #toc.toc2{border-right-width:0;border-left:1px solid #e7e7e9;left:auto;right:0}} |
| @media screen and (min-width:1280px){body.toc2{padding-left:20em;padding-right:0} |
| #toc.toc2{width:20em} |
| #toc.toc2 #toctitle{font-size:1.375em} |
| #toc.toc2>ul{font-size:.95em} |
| #toc.toc2 ul ul{padding-left:1.25em} |
| body.toc2.toc-right{padding-left:0;padding-right:20em}} |
| #content #toc{border-style:solid;border-width:1px;border-color:#e0e0dc;margin-bottom:1.25em;padding:1.25em;background:#f8f8f7;-webkit-border-radius:4px;border-radius:4px} |
| #content #toc>:first-child{margin-top:0} |
| #content #toc>:last-child{margin-bottom:0} |
| #footer{max-width:none;background:rgba(0,0,0,.8);padding:1.25em} |
| #footer-text{color:rgba(255,255,255,.8);line-height:1.44} |
| #content{margin-bottom:.625em} |
| .sect1{padding-bottom:.625em} |
| @media screen and (min-width:768px){#content{margin-bottom:1.25em} |
| .sect1{padding-bottom:1.25em}} |
| .sect1:last-child{padding-bottom:0} |
| .sect1+.sect1{border-top:1px solid #e7e7e9} |
| #content h1>a.anchor,h2>a.anchor,h3>a.anchor,#toctitle>a.anchor,.sidebarblock>.content>.title>a.anchor,h4>a.anchor,h5>a.anchor,h6>a.anchor{position:absolute;z-index:1001;width:1.5ex;margin-left:-1.5ex;display:block;text-decoration:none!important;visibility:hidden;text-align:center;font-weight:400} |
| #content h1>a.anchor::before,h2>a.anchor::before,h3>a.anchor::before,#toctitle>a.anchor::before,.sidebarblock>.content>.title>a.anchor::before,h4>a.anchor::before,h5>a.anchor::before,h6>a.anchor::before{content:"\00A7";font-size:.85em;display:block;padding-top:.1em} |
| #content h1:hover>a.anchor,#content h1>a.anchor:hover,h2:hover>a.anchor,h2>a.anchor:hover,h3:hover>a.anchor,#toctitle:hover>a.anchor,.sidebarblock>.content>.title:hover>a.anchor,h3>a.anchor:hover,#toctitle>a.anchor:hover,.sidebarblock>.content>.title>a.anchor:hover,h4:hover>a.anchor,h4>a.anchor:hover,h5:hover>a.anchor,h5>a.anchor:hover,h6:hover>a.anchor,h6>a.anchor:hover{visibility:visible} |
| #content h1>a.link,h2>a.link,h3>a.link,#toctitle>a.link,.sidebarblock>.content>.title>a.link,h4>a.link,h5>a.link,h6>a.link{color:#ba3925;text-decoration:none} |
| #content h1>a.link:hover,h2>a.link:hover,h3>a.link:hover,#toctitle>a.link:hover,.sidebarblock>.content>.title>a.link:hover,h4>a.link:hover,h5>a.link:hover,h6>a.link:hover{color:#a53221} |
| details,.audioblock,.imageblock,.literalblock,.listingblock,.stemblock,.videoblock{margin-bottom:1.25em} |
| details>summary:first-of-type{cursor:pointer;display:list-item;outline:none;margin-bottom:.75em} |
| .admonitionblock td.content>.title,.audioblock>.title,.exampleblock>.title,.imageblock>.title,.listingblock>.title,.literalblock>.title,.stemblock>.title,.openblock>.title,.paragraph>.title,.quoteblock>.title,table.tableblock>.title,.verseblock>.title,.videoblock>.title,.dlist>.title,.olist>.title,.ulist>.title,.qlist>.title,.hdlist>.title{text-rendering:optimizeLegibility;text-align:left;font-family:"Noto Serif","DejaVu Serif",serif;font-size:1rem;font-style:italic} |
| table.tableblock.fit-content>caption.title{white-space:nowrap;width:0} |
| .paragraph.lead>p,#preamble>.sectionbody>[class="paragraph"]:first-of-type p{font-size:1.21875em;line-height:1.6;color:rgba(0,0,0,.85)} |
| table.tableblock #preamble>.sectionbody>[class="paragraph"]:first-of-type p{font-size:inherit} |
| .admonitionblock>table{border-collapse:separate;border:0;background:none;width:100%} |
| .admonitionblock>table td.icon{text-align:center;width:80px} |
| .admonitionblock>table td.icon img{max-width:none} |
| .admonitionblock>table td.icon .title{font-weight:bold;font-family:"Open Sans","DejaVu Sans",sans-serif;text-transform:uppercase} |
| .admonitionblock>table td.content{padding-left:1.125em;padding-right:1.25em;border-left:1px solid #dddddf;color:rgba(0,0,0,.6);word-wrap:anywhere} |
| .admonitionblock>table td.content>:last-child>:last-child{margin-bottom:0} |
| .exampleblock>.content{border-style:solid;border-width:1px;border-color:#e6e6e6;margin-bottom:1.25em;padding:1.25em;background:#fff;-webkit-border-radius:4px;border-radius:4px} |
| .exampleblock>.content>:first-child{margin-top:0} |
| .exampleblock>.content>:last-child{margin-bottom:0} |
| .sidebarblock{border-style:solid;border-width:1px;border-color:#dbdbd6;margin-bottom:1.25em;padding:1.25em;background:#f3f3f2;-webkit-border-radius:4px;border-radius:4px} |
| .sidebarblock>:first-child{margin-top:0} |
| .sidebarblock>:last-child{margin-bottom:0} |
| .sidebarblock>.content>.title{color:#7a2518;margin-top:0;text-align:center} |
| .exampleblock>.content>:last-child>:last-child,.exampleblock>.content .olist>ol>li:last-child>:last-child,.exampleblock>.content .ulist>ul>li:last-child>:last-child,.exampleblock>.content .qlist>ol>li:last-child>:last-child,.sidebarblock>.content>:last-child>:last-child,.sidebarblock>.content .olist>ol>li:last-child>:last-child,.sidebarblock>.content .ulist>ul>li:last-child>:last-child,.sidebarblock>.content .qlist>ol>li:last-child>:last-child{margin-bottom:0} |
| .literalblock pre,.listingblock>.content>pre{-webkit-border-radius:4px;border-radius:4px;overflow-x:auto;padding:1em;font-size:.8125em} |
| @media screen and (min-width:768px){.literalblock pre,.listingblock>.content>pre{font-size:.90625em}} |
| @media screen and (min-width:1280px){.literalblock pre,.listingblock>.content>pre{font-size:1em}} |
| .literalblock pre,.listingblock>.content>pre:not(.highlight),.listingblock>.content>pre[class="highlight"],.listingblock>.content>pre[class^="highlight "]{background:#f7f7f8} |
| .literalblock.output pre{color:#f7f7f8;background:rgba(0,0,0,.9)} |
| .listingblock>.content{position:relative} |
| .listingblock code[data-lang]::before{display:none;content:attr(data-lang);position:absolute;font-size:.75em;top:.425rem;right:.5rem;line-height:1;text-transform:uppercase;color:inherit;opacity:.5} |
| .listingblock:hover code[data-lang]::before{display:block} |
| .listingblock.terminal pre .command::before{content:attr(data-prompt);padding-right:.5em;color:inherit;opacity:.5} |
| .listingblock.terminal pre .command:not([data-prompt])::before{content:"$"} |
| .listingblock pre.highlightjs{padding:0} |
| .listingblock pre.highlightjs>code{padding:1em;-webkit-border-radius:4px;border-radius:4px} |
| .listingblock pre.prettyprint{border-width:0} |
| .prettyprint{background:#f7f7f8} |
| pre.prettyprint .linenums{line-height:1.45;margin-left:2em} |
| pre.prettyprint li{background:none;list-style-type:inherit;padding-left:0} |
| pre.prettyprint li code[data-lang]::before{opacity:1} |
| pre.prettyprint li:not(:first-child) code[data-lang]::before{display:none} |
| table.linenotable{border-collapse:separate;border:0;margin-bottom:0;background:none} |
| table.linenotable td[class]{color:inherit;vertical-align:top;padding:0;line-height:inherit;white-space:normal} |
| table.linenotable td.code{padding-left:.75em} |
| table.linenotable td.linenos{border-right:1px solid currentColor;opacity:.35;padding-right:.5em} |
| pre.pygments .lineno{border-right:1px solid currentColor;opacity:.35;display:inline-block;margin-right:.75em} |
| pre.pygments .lineno::before{content:"";margin-right:-.125em} |
| .quoteblock{margin:0 1em 1.25em 1.5em;display:table} |
| .quoteblock:not(.excerpt)>.title{margin-left:-1.5em;margin-bottom:.75em} |
| .quoteblock blockquote,.quoteblock p{color:rgba(0,0,0,.85);font-size:1.15rem;line-height:1.75;word-spacing:.1em;letter-spacing:0;font-style:italic;text-align:justify} |
| .quoteblock blockquote{margin:0;padding:0;border:0} |
| .quoteblock blockquote::before{content:"\201c";float:left;font-size:2.75em;font-weight:bold;line-height:.6em;margin-left:-.6em;color:#7a2518;text-shadow:0 1px 2px rgba(0,0,0,.1)} |
| .quoteblock blockquote>.paragraph:last-child p{margin-bottom:0} |
| .quoteblock .attribution{margin-top:.75em;margin-right:.5ex;text-align:right} |
| .verseblock{margin:0 1em 1.25em} |
| .verseblock pre{font-family:"Open Sans","DejaVu Sans",sans;font-size:1.15rem;color:rgba(0,0,0,.85);font-weight:300;text-rendering:optimizeLegibility} |
| .verseblock pre strong{font-weight:400} |
| .verseblock .attribution{margin-top:1.25rem;margin-left:.5ex} |
| .quoteblock .attribution,.verseblock .attribution{font-size:.9375em;line-height:1.45;font-style:italic} |
| .quoteblock .attribution br,.verseblock .attribution br{display:none} |
| .quoteblock .attribution cite,.verseblock .attribution cite{display:block;letter-spacing:-.025em;color:rgba(0,0,0,.6)} |
| .quoteblock.abstract blockquote::before,.quoteblock.excerpt blockquote::before,.quoteblock .quoteblock blockquote::before{display:none} |
| .quoteblock.abstract blockquote,.quoteblock.abstract p,.quoteblock.excerpt blockquote,.quoteblock.excerpt p,.quoteblock .quoteblock blockquote,.quoteblock .quoteblock p{line-height:1.6;word-spacing:0} |
| .quoteblock.abstract{margin:0 1em 1.25em;display:block} |
| .quoteblock.abstract>.title{margin:0 0 .375em;font-size:1.15em;text-align:center} |
| .quoteblock.excerpt>blockquote,.quoteblock .quoteblock{padding:0 0 .25em 1em;border-left:.25em solid #dddddf} |
| .quoteblock.excerpt,.quoteblock .quoteblock{margin-left:0} |
| .quoteblock.excerpt blockquote,.quoteblock.excerpt p,.quoteblock .quoteblock blockquote,.quoteblock .quoteblock p{color:inherit;font-size:1.0625rem} |
| .quoteblock.excerpt .attribution,.quoteblock .quoteblock .attribution{color:inherit;text-align:left;margin-right:0} |
| p.tableblock:last-child{margin-bottom:0} |
| td.tableblock>.content{margin-bottom:1.25em;word-wrap:anywhere} |
| td.tableblock>.content>:last-child{margin-bottom:-1.25em} |
| table.tableblock,th.tableblock,td.tableblock{border:0 solid #dedede} |
| table.grid-all>*>tr>*{border-width:1px} |
| table.grid-cols>*>tr>*{border-width:0 1px} |
| table.grid-rows>*>tr>*{border-width:1px 0} |
| table.frame-all{border-width:1px} |
| table.frame-ends{border-width:1px 0} |
| table.frame-sides{border-width:0 1px} |
| table.frame-none>colgroup+*>:first-child>*,table.frame-sides>colgroup+*>:first-child>*{border-top-width:0} |
| table.frame-none>:last-child>:last-child>*,table.frame-sides>:last-child>:last-child>*{border-bottom-width:0} |
| table.frame-none>*>tr>:first-child,table.frame-ends>*>tr>:first-child{border-left-width:0} |
| table.frame-none>*>tr>:last-child,table.frame-ends>*>tr>:last-child{border-right-width:0} |
| table.stripes-all tr,table.stripes-odd tr:nth-of-type(odd),table.stripes-even tr:nth-of-type(even),table.stripes-hover tr:hover{background:#f8f8f7} |
| th.halign-left,td.halign-left{text-align:left} |
| th.halign-right,td.halign-right{text-align:right} |
| th.halign-center,td.halign-center{text-align:center} |
| th.valign-top,td.valign-top{vertical-align:top} |
| th.valign-bottom,td.valign-bottom{vertical-align:bottom} |
| th.valign-middle,td.valign-middle{vertical-align:middle} |
| table thead th,table tfoot th{font-weight:bold} |
| tbody tr th{background:#f7f8f7} |
| tbody tr th,tbody tr th p,tfoot tr th,tfoot tr th p{color:rgba(0,0,0,.8);font-weight:bold} |
| p.tableblock>code:only-child{background:none;padding:0} |
| p.tableblock{font-size:1em} |
| ol{margin-left:1.75em} |
| ul li ol{margin-left:1.5em} |
| dl dd{margin-left:1.125em} |
| dl dd:last-child,dl dd:last-child>:last-child{margin-bottom:0} |
| ol>li p,ul>li p,ul dd,ol dd,.olist .olist,.ulist .ulist,.ulist .olist,.olist .ulist{margin-bottom:.625em} |
| ul.checklist,ul.none,ol.none,ul.no-bullet,ol.no-bullet,ol.unnumbered,ul.unstyled,ol.unstyled{list-style-type:none} |
| ul.no-bullet,ol.no-bullet,ol.unnumbered{margin-left:.625em} |
| ul.unstyled,ol.unstyled{margin-left:0} |
| ul.checklist{margin-left:.625em} |
| ul.checklist li>p:first-child>.fa-square-o:first-child,ul.checklist li>p:first-child>.fa-check-square-o:first-child{width:1.25em;font-size:.8em;position:relative;bottom:.125em} |
| ul.checklist li>p:first-child>input[type="checkbox"]:first-child{margin-right:.25em} |
| ul.inline{display:-ms-flexbox;display:-webkit-box;display:flex;-ms-flex-flow:row wrap;-webkit-flex-flow:row wrap;flex-flow:row wrap;list-style:none;margin:0 0 .625em -1.25em} |
| ul.inline>li{margin-left:1.25em} |
| .unstyled dl dt{font-weight:400;font-style:normal} |
| ol.arabic{list-style-type:decimal} |
| ol.decimal{list-style-type:decimal-leading-zero} |
| ol.loweralpha{list-style-type:lower-alpha} |
| ol.upperalpha{list-style-type:upper-alpha} |
| ol.lowerroman{list-style-type:lower-roman} |
| ol.upperroman{list-style-type:upper-roman} |
| ol.lowergreek{list-style-type:lower-greek} |
| .hdlist>table,.colist>table{border:0;background:none} |
| .hdlist>table>tbody>tr,.colist>table>tbody>tr{background:none} |
| td.hdlist1,td.hdlist2{vertical-align:top;padding:0 .625em} |
| td.hdlist1{font-weight:bold;padding-bottom:1.25em} |
| td.hdlist2{word-wrap:anywhere} |
| .literalblock+.colist,.listingblock+.colist{margin-top:-.5em} |
| .colist td:not([class]):first-child{padding:.4em .75em 0;line-height:1;vertical-align:top} |
| .colist td:not([class]):first-child img{max-width:none} |
| .colist td:not([class]):last-child{padding:.25em 0} |
| .thumb,.th{line-height:0;display:inline-block;border:solid 4px #fff;-webkit-box-shadow:0 0 0 1px #ddd;box-shadow:0 0 0 1px #ddd} |
| .imageblock.left{margin:.25em .625em 1.25em 0} |
| .imageblock.right{margin:.25em 0 1.25em .625em} |
| .imageblock>.title{margin-bottom:0} |
| .imageblock.thumb,.imageblock.th{border-width:6px} |
| .imageblock.thumb>.title,.imageblock.th>.title{padding:0 .125em} |
| .image.left,.image.right{margin-top:.25em;margin-bottom:.25em;display:inline-block;line-height:0} |
| .image.left{margin-right:.625em} |
| .image.right{margin-left:.625em} |
| a.image{text-decoration:none;display:inline-block} |
| a.image object{pointer-events:none} |
| sup.footnote,sup.footnoteref{font-size:.875em;position:static;vertical-align:super} |
| sup.footnote a,sup.footnoteref a{text-decoration:none} |
| sup.footnote a:active,sup.footnoteref a:active{text-decoration:underline} |
| #footnotes{padding-top:.75em;padding-bottom:.75em;margin-bottom:.625em} |
| #footnotes hr{width:20%;min-width:6.25em;margin:-.25em 0 .75em;border-width:1px 0 0} |
| #footnotes .footnote{padding:0 .375em 0 .225em;line-height:1.3334;font-size:.875em;margin-left:1.2em;margin-bottom:.2em} |
| #footnotes .footnote a:first-of-type{font-weight:bold;text-decoration:none;margin-left:-1.05em} |
| #footnotes .footnote:last-of-type{margin-bottom:0} |
| #content #footnotes{margin-top:-.625em;margin-bottom:0;padding:.75em 0} |
| .gist .file-data>table{border:0;background:#fff;width:100%;margin-bottom:0} |
| .gist .file-data>table td.line-data{width:99%} |
| div.unbreakable{page-break-inside:avoid} |
| .big{font-size:larger} |
| .small{font-size:smaller} |
| .underline{text-decoration:underline} |
| .overline{text-decoration:overline} |
| .line-through{text-decoration:line-through} |
| .aqua{color:#00bfbf} |
| .aqua-background{background:#00fafa} |
| .black{color:#000} |
| .black-background{background:#000} |
| .blue{color:#0000bf} |
| .blue-background{background:#0000fa} |
| .fuchsia{color:#bf00bf} |
| .fuchsia-background{background:#fa00fa} |
| .gray{color:#606060} |
| .gray-background{background:#7d7d7d} |
| .green{color:#006000} |
| .green-background{background:#007d00} |
| .lime{color:#00bf00} |
| .lime-background{background:#00fa00} |
| .maroon{color:#600000} |
| .maroon-background{background:#7d0000} |
| .navy{color:#000060} |
| .navy-background{background:#00007d} |
| .olive{color:#606000} |
| .olive-background{background:#7d7d00} |
| .purple{color:#600060} |
| .purple-background{background:#7d007d} |
| .red{color:#bf0000} |
| .red-background{background:#fa0000} |
| .silver{color:#909090} |
| .silver-background{background:#bcbcbc} |
| .teal{color:#006060} |
| .teal-background{background:#007d7d} |
| .white{color:#bfbfbf} |
| .white-background{background:#fafafa} |
| .yellow{color:#bfbf00} |
| .yellow-background{background:#fafa00} |
| span.icon>.fa{cursor:default} |
| a span.icon>.fa{cursor:inherit} |
| .admonitionblock td.icon [class^="fa icon-"]{font-size:2.5em;text-shadow:1px 1px 2px rgba(0,0,0,.5);cursor:default} |
| .admonitionblock td.icon .icon-note::before{content:"\f05a";color:#19407c} |
| .admonitionblock td.icon .icon-tip::before{content:"\f0eb";text-shadow:1px 1px 2px rgba(155,155,0,.8);color:#111} |
| .admonitionblock td.icon .icon-warning::before{content:"\f071";color:#bf6900} |
| .admonitionblock td.icon .icon-caution::before{content:"\f06d";color:#bf3400} |
| .admonitionblock td.icon .icon-important::before{content:"\f06a";color:#bf0000} |
| .conum[data-value]{display:inline-block;color:#fff!important;background:rgba(0,0,0,.8);-webkit-border-radius:50%;border-radius:50%;text-align:center;font-size:.75em;width:1.67em;height:1.67em;line-height:1.67em;font-family:"Open Sans","DejaVu Sans",sans-serif;font-style:normal;font-weight:bold} |
| .conum[data-value] *{color:#fff!important} |
| .conum[data-value]+b{display:none} |
| .conum[data-value]::after{content:attr(data-value)} |
| pre .conum[data-value]{position:relative;top:-.125em} |
| b.conum *{color:inherit!important} |
| .conum:not([data-value]):empty{display:none} |
| dt,th.tableblock,td.content,div.footnote{text-rendering:optimizeLegibility} |
| h1,h2,p,td.content,span.alt{letter-spacing:-.01em} |
| p strong,td.content strong,div.footnote strong{letter-spacing:-.005em} |
| p,blockquote,dt,td.content,span.alt{font-size:1.0625rem} |
| p{margin-bottom:1.25rem} |
| .sidebarblock p,.sidebarblock dt,.sidebarblock td.content,p.tableblock{font-size:1em} |
| .exampleblock>.content{background:#fffef7;border-color:#e0e0dc;-webkit-box-shadow:0 1px 4px #e0e0dc;box-shadow:0 1px 4px #e0e0dc} |
| .print-only{display:none!important} |
| @page{margin:1.25cm .75cm} |
| @media print{*{-webkit-box-shadow:none!important;box-shadow:none!important;text-shadow:none!important} |
| html{font-size:80%} |
| a{color:inherit!important;text-decoration:underline!important} |
| a.bare,a[href^="#"],a[href^="mailto:"]{text-decoration:none!important} |
| a[href^="http:"]:not(.bare)::after,a[href^="https:"]:not(.bare)::after{content:"(" attr(href) ")";display:inline-block;font-size:.875em;padding-left:.25em} |
| abbr[title]::after{content:" (" attr(title) ")"} |
| pre,blockquote,tr,img,object,svg{page-break-inside:avoid} |
| thead{display:table-header-group} |
| svg{max-width:100%} |
| p,blockquote,dt,td.content{font-size:1em;orphans:3;widows:3} |
| h2,h3,#toctitle,.sidebarblock>.content>.title{page-break-after:avoid} |
| #header,#content,#footnotes,#footer{max-width:none} |
| #toc,.sidebarblock,.exampleblock>.content{background:none!important} |
| #toc{border-bottom:1px solid #dddddf!important;padding-bottom:0!important} |
| body.book #header{text-align:center} |
| body.book #header>h1:first-child{border:0!important;margin:2.5em 0 1em} |
| body.book #header .details{border:0!important;display:block;padding:0!important} |
| body.book #header .details span:first-child{margin-left:0!important} |
| body.book #header .details br{display:block} |
| body.book #header .details br+span::before{content:none!important} |
| body.book #toc{border:0!important;text-align:left!important;padding:0!important;margin:0!important} |
| body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-break-before:always} |
| .listingblock code[data-lang]::before{display:block} |
| #footer{padding:0 .9375em} |
| .hide-on-print{display:none!important} |
| .print-only{display:block!important} |
| .hide-for-print{display:none!important} |
| .show-for-print{display:inherit!important}} |
| @media print,amzn-kf8{#header>h1:first-child{margin-top:1.25rem} |
| .sect1{padding:0!important} |
| .sect1+.sect1{border:0} |
| #footer{background:none} |
| #footer-text{color:rgba(0,0,0,.6);font-size:.9em}} |
| @media amzn-kf8{#header,#content,#footnotes,#footer{padding:0}} |
| </style> |
| <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.7.0/css/font-awesome.min.css"> |
| <!-- |
| Copyright (c) 2010, 2021 Contributors to the Eclipse Foundation |
| |
| See the NOTICE file(s) distributed with this work for additional |
| information regarding copyright ownership. |
| |
| This program and the accompanying materials are made available under the terms |
| of the MIT License which is available at https://opensource.org/licenses/MIT |
| |
| SPDX-License-Identifier: MIT |
| --> |
| <style> |
| .menu, .submenu, .menuitem, .menuref { |
| background-color: Menu; |
| } |
| |
| .button { |
| border: 1px solid ButtonFace; |
| /* |
| Styling too similar to a real button is considered bad practice, see https://github.com/asciidoctor/asciidoctor/issues/1881#issuecomment-250702085 |
| border: 2px outset ButtonFace; |
| background-color: ButtonFace; |
| */ |
| padding-left: 0.5ex; |
| padding-right: 0.5ex; |
| font-weight: normal; |
| font-family: "Segoe UI","Open Sans","DejaVu Sans",sans-serif; |
| white-space: nowrap; |
| } |
| .button:before { |
| content: none !important; |
| } |
| .button:after { |
| content: none !important; |
| } |
| |
| #footer-text, #footer-text a { |
| color: rgba(255,255,255,.8) |
| } |
| </style> |
| </head> |
| <body class="book toc2 toc-left"> |
| <div id="header"> |
| <h1>Eclipse ESCET™ documentation (Incubation)</h1> |
| <div class="details"> |
| <span id="author" class="author">Copyright (c) 2010, 2021 Contributors to the Eclipse Foundation</span><br> |
| <span id="revnumber">version v0.2</span> |
| </div> |
| <div id="toc" class="toc2"> |
| <div id="toctitle">Table of Contents</div> |
| <ul class="sectlevel1"> |
| <li><a href="#intro-chapter-index">Introduction to Eclipse ESCET project</a> |
| <ul class="sectlevel2"> |
| <li><a href="#intro-chapter-chi">Chi</a></li> |
| <li><a href="#intro-chapter-cif">CIF</a></li> |
| <li><a href="#intro-chapter-setext">SeText</a></li> |
| <li><a href="#intro-chapter-tooldef">ToolDef</a></li> |
| </ul> |
| </li> |
| <li><a href="#download-install-chapter-index">Download and install Eclipse ESCET toolkit</a> |
| <ul class="sectlevel2"> |
| <li><a href="#download-install-install">Installation of Eclipse ESCET tools</a></li> |
| <li><a href="#download-install-first-start">Starting Eclipse ESCET IDE for the first time</a></li> |
| <li><a href="#download-install-update">Updating Eclipse ESCET tools</a></li> |
| <li><a href="#download-install-remove">Removing Eclipse ESCET tools</a></li> |
| <li><a href="#download-install-find-version">Finding the tool’s version number</a></li> |
| </ul> |
| </li> |
| <li><a href="#use-chapter-index">Using Eclipse ESCET tools</a> |
| <ul class="sectlevel2"> |
| <li><a href="#use-terminology">Eclipse terminology</a></li> |
| <li><a href="#use-projects">Working with projects, directories, and files</a></li> |
| <li><a href="#use-edit-exec">Editing files and executing commands</a></li> |
| <li><a href="#use-escet-perspective">Eclipse ESCET perspective</a></li> |
| <li><a href="#use-apps-view">Applications view</a></li> |
| </ul> |
| </li> |
| <li><a href="#performance-chapter-index">Resolving performance and memory problems</a> |
| <ul class="sectlevel2"> |
| <li><a href="#performance-clear-console">Clearing the console</a></li> |
| <li><a href="#performance-reduce-console-output">Reducing console output</a></li> |
| <li><a href="#performance-close-running-apps">Closing running applications</a></li> |
| <li><a href="#performance-tweak-perf-settings">Tweaking performance settings</a></li> |
| </ul> |
| </li> |
| <li><a href="#developer-chapter-index">Eclipse ESCET development</a> |
| <ul class="sectlevel2"> |
| <li><a href="#developer-development-process-chapter-index">Development process</a></li> |
| <li><a href="#developer-contributing-chapter-index">Contributing</a></li> |
| <li><a href="#developer-issue-tracking-chapter-index">Issue tracking</a></li> |
| <li><a href="#developer-dev-env-setup-chapter-index">Development environment setup</a></li> |
| <li><a href="#developer-git-repo-chapter-index">Git repository</a></li> |
| <li><a href="#developer-coding-standards-chapter-index">Coding standards</a></li> |
| <li><a href="#developer-building-and-testing-chapter-index">Building and testing</a></li> |
| <li><a href="#developer-release-process-chapter-index">Release process</a></li> |
| <li><a href="#developer-third-party-tools-chapter-index">Third party tools</a></li> |
| <li><a href="#developer-upgrade-instructions-chapter-index">Upgrade instructions</a></li> |
| </ul> |
| </li> |
| <li><a href="#app-framework-chapter-index">Application framework</a> |
| <ul class="sectlevel2"> |
| <li><a href="#app-framework-introduction">Introduction</a></li> |
| <li><a href="#app-framework-standalone-vs-eclipse">Stand-alone execution versus Eclipse IDE</a></li> |
| <li><a href="#app-framework-application-class">The Application class</a></li> |
| <li><a href="#app-framework-exception-framework">The exception framework</a></li> |
| <li><a href="#app-framework-exit-codes">Exit codes</a></li> |
| <li><a href="#app-framework-io-framework">The I/O framework</a></li> |
| <li><a href="#app-framework-option-framework">The option framework</a></li> |
| <li><a href="#app-framework-compiler-framework">The compiler framework</a></li> |
| <li><a href="#app-framework-implement-your-application">How to implement your own application</a></li> |
| <li><a href="#app-framework-registration">Application registration</a></li> |
| <li><a href="#app-framework-execution">Execution</a></li> |
| </ul> |
| </li> |
| <li><a href="#rail-chapter-index">Rail diagram generator</a> |
| <ul class="sectlevel2"> |
| <li><a href="#rail-introduction">Introduction</a></li> |
| <li><a href="#rail-examples">Examples</a></li> |
| <li><a href="#rail-customizing-output">Customizing output</a></li> |
| <li><a href="#rail-lexical-syntax">Lexical syntax</a></li> |
| <li><a href="#rail-grammar">Grammar</a></li> |
| </ul> |
| </li> |
| <li><a href="#release-notes-chapter-index">Eclipse ESCET release notes</a> |
| <ul class="sectlevel2"> |
| <li><a href="#version-0-2">Version 0.2</a></li> |
| <li><a href="#version-0-1">Version 0.1</a></li> |
| </ul> |
| </li> |
| <li><a href="#contact-chapter-index">Contact information</a></li> |
| <li><a href="#legal-chapter-index">Legal</a></li> |
| </ul> |
| </div> |
| </div> |
| <div id="content"> |
| <div id="preamble"> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p>The Eclipse Supervisory Control Engineering Toolkit (Eclipse ESCET™) project is an <a href="https://eclipse.org">Eclipse Foundation</a> open-source project that provides a toolkit for the development of supervisory controllers in the Model-Based Systems Engineering (MBSE) paradigm. |
| The toolkit has a strong focus on model-based design, supervisory controller synthesis, and industrial applicability, for example to cyber-physical systems. |
| The toolkit supports the entire development process of (supervisory) controllers, from modeling, supervisory controller synthesis, simulation-based validation and visualization, and formal verification, to real-time testing and implementation.</p> |
| </div> |
| <div class="admonitionblock warning"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <i class="fa icon-warning" title="Warning"></i> |
| </td> |
| <td class="content"> |
| <div class="paragraph"> |
| <p>The Eclipse ESCET project and all its tools are currently in the <a href="https://wiki.eclipse.org/Development_Resources/Process_Guidelines/What_is_Incubation">Incubation Phase</a>.</p> |
| </div> |
| <div class="paragraph"> |
| <p><span class="image"><img src="./eclipse-incubation.png" alt="eclipse incubation" width="300"></span></p> |
| </div> |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="admonitionblock tip"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <i class="fa icon-tip" title="Tip"></i> |
| </td> |
| <td class="content"> |
| You can <a href="eclipse-escet-incubation-manual.pdf">download this manual</a> as a PDF as well. |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="paragraph"> |
| <p>The Eclipse ESCET toolkit features the following languages and associated tools:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="#intro-chapter-chi">Chi</a></p> |
| </li> |
| <li> |
| <p><a href="#intro-chapter-cif">CIF</a></p> |
| </li> |
| <li> |
| <p><a href="#intro-chapter-setext">SeText</a></p> |
| </li> |
| <li> |
| <p><a href="#intro-chapter-tooldef">ToolDef</a></p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>This manual includes information related to the Eclipse ESCET toolkit as a whole, and applies to those tools as well. |
| The following information is available for end users of the toolkit:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="#intro-chapter-index">Introduction to Eclipse ESCET project</a></p> |
| </li> |
| <li> |
| <p><a href="#download-install-chapter-index">Download and install Eclipse ESCET toolkit</a></p> |
| </li> |
| <li> |
| <p><a href="#use-chapter-index">Using Eclipse ESCET tools</a></p> |
| </li> |
| <li> |
| <p><a href="#performance-chapter-index">Resolving performance and memory problems</a></p> |
| </li> |
| <li> |
| <p><a href="#release-notes-chapter-index">Eclipse ESCET release notes</a></p> |
| </li> |
| <li> |
| <p><a href="#contact-chapter-index">Contact information</a></p> |
| </li> |
| <li> |
| <p><a href="#legal-chapter-index">Legal</a></p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>The following information is available for developers of the toolkit:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="#developer-chapter-index">Eclipse ESCET development</a></p> |
| </li> |
| <li> |
| <p><a href="#app-framework-chapter-index">Application framework</a></p> |
| </li> |
| <li> |
| <p><a href="#rail-chapter-index">Rail diagram generator</a></p> |
| </li> |
| </ul> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="intro-chapter-index">Introduction to Eclipse ESCET project</h2> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p></p> |
| </div> |
| <div class="paragraph"> |
| <p>High-tech companies increasingly adopt the <a href="https://en.wikipedia.org/wiki/Model-based_systems_engineering">Model-Based Systems Engineering</a> (MBSE) paradigm. |
| The use of (formal) models for controller design allows validation and verification of controllers long before they are implemented and integrated into the system. |
| Early validation and verification have been shown to lead to less defects and reduced costs.</p> |
| </div> |
| <div class="paragraph"> |
| <p></p> |
| </div> |
| <div class="paragraph"> |
| <p>The Eclipse Supervisory Control Engineering Toolkit (Eclipse ESCET™) project is an <a href="https://eclipse.org">Eclipse Foundation</a> open-source project that provides a toolkit for the development of supervisory controllers in the MBSE paradigm. |
| The toolkit has a strong focus on model-based design, supervisory controller synthesis, and industrial applicability, for example to cyber-physical systems. |
| The toolkit supports the entire development process of (supervisory) controllers, from modeling, supervisory controller synthesis, simulation-based validation and visualization, and formal verification, to real-time testing and implementation.</p> |
| </div> |
| <div class="paragraph"> |
| <p></p> |
| </div> |
| <div class="paragraph"> |
| <p>Supervisory controller synthesis is a key feature of the toolkit. |
| It involves the automatic generation of supervisory controllers from a specification of the uncontrolled system and the (safety) requirements that the controller needs to enforce. |
| This shifts controller design from 'how should the implementation work' to 'what should the controller do'. |
| Implementation of the controller is achieved through (implementation language) code generation, reducing the number of errors introduced at this stage.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The Eclipse ESCET toolkit features the following languages and associated tools:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="#intro-chapter-chi">Chi</a></p> |
| </li> |
| <li> |
| <p><a href="#intro-chapter-cif">CIF</a></p> |
| </li> |
| <li> |
| <p><a href="#intro-chapter-setext">SeText</a></p> |
| </li> |
| <li> |
| <p><a href="#intro-chapter-tooldef">ToolDef</a></p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p></p> |
| </div> |
| <div class="sect2"> |
| <h3 id="intro-chapter-chi">Chi</h3> |
| <div class="paragraph"> |
| <p>The Chi language is a modeling language for describing and analyzing the performance of discrete event systems by means of simulation. |
| The language design is based on decades of successful analyses of various (industrial) systems, aiming to be powerful for advanced users, and easy to use for non-experts.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The language uses a process-based view. |
| A system (and its control) is modeled as a collection of parallel running processes, communicating with each other using point-to-point communication channels. |
| Processes do not share data with other processes, and channels are synchronous (sending and receiving is always done together at the same time), making reasoning about process behavior easier. |
| Processes and channels are dynamic, new processes can be created as needed, and communication channels can be created or rerouted, making for a powerful specification language.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The language is designed to be formal and easily extensible. |
| Models are written as an imperative program, with an intuitive syntax, making it easy to read and write models. |
| A small generic set of statements can be used to describe algorithms, including assignments, <em>if</em>, <em>while</em> and <em>for</em> statements. |
| This set is relatively easy to explain to non-experts, allowing them to understand the model, and participate in the discussions.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The data of the system can be modeled using both basic data types, such as <em>booleans</em> and <em>integer</em> and <em>real</em> numbers, as well as high level structured collections of data like <em>lists</em>, <em>sets</em> and <em>dictionaries</em>. |
| If desired, processes and channels can also be part of that data. |
| Furthermore, timers and (quasi-)random number generation distributions are available for modeling timed and stochastic systems. |
| Features to easily specify repeated experiments, e.g. for stochastic simulation, or simulation for various inputs obtained from files, exist to support large simulation experiments.</p> |
| </div> |
| <div class="paragraph"> |
| <p>While the language is generic, the main application area is modeling of the operation of (manufacturing) systems. |
| During the design process, engineers can make use of analytical models, to get answers about the operation of the system. |
| Simulation studies can provide insights into e.g. the throughput of the system, the effect of set-up time in a machine, or how the batch size of an order will influence the flow time of the product-items.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The Chi toolset allows verification of properties of the actual system by means of simulation, e.g. to optimize the supervisory (logic) control of the system. |
| The Chi language has features that allow for easy specification. |
| Chi aims to make the process of verifying properties for large systems effortless.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Tutorials and manuals demonstrate the use of the language for effective modeling of system processes. |
| More detailed modeling of the processes and e.g performance indicators, or custom tailoring them to the real situation, has no inherent limits.</p> |
| </div> |
| <div class="paragraph"> |
| <p>See the separate <a href="https://eclipse.org/escet/chi">Chi documentation</a> for more information.</p> |
| </div> |
| <div class="paragraph"> |
| <p></p> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="intro-chapter-cif">CIF</h3> |
| <div class="paragraph"> |
| <p>The CIF language is a powerful declarative automata-based modeling language for the specification of discrete event, timed (linear dynamics), hybrid (piecewise continuous dynamics) systems. |
| It can be seen as a rich state machine language with the following main features:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>Modular specification with synchronized events and communication between automata.</p> |
| </li> |
| <li> |
| <p>Many data types are available (booleans, integers, reals, tuples, lists, arrays, sets, and dictionaries), combined with a powerful expression language for compact variables updates.</p> |
| </li> |
| <li> |
| <p>Text-based specification of the automata, with many features to simplify modeling large non-trivial industrial systems.</p> |
| </li> |
| <li> |
| <p>Primitives for supervisory controller synthesis are integrated in the language.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>The CIF tooling supports the entire development process of controllers, including among others specification, supervisory controller synthesis, simulation-based validation and visualization, verification, real-time testing, and code generation. |
| Highlights of the CIF tooling include:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>Text-based editor that allows to easily specify and edit models.</p> |
| </li> |
| <li> |
| <p>Feature-rich powerful data-based synthesis tool. |
| A transformation to the supervisory controller synthesis tool Supremica is also available.</p> |
| </li> |
| <li> |
| <p>A simulator that supports both interactive and automated validation of specifications. |
| Powerful visualization features allow for interactive visualization-based validation.</p> |
| </li> |
| <li> |
| <p>Conversion to formal verification tools such as mCRL2 and UPPAAL.</p> |
| </li> |
| <li> |
| <p>Implementation language code generation (PLC languages, Java, C, and Simulink) for real-time testing and implementation of the designed controller.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>See the separate <a href="https://eclipse.org/escet/cif">CIF documentation</a> for more information.</p> |
| </div> |
| <div class="paragraph"> |
| <p></p> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="intro-chapter-setext">SeText</h3> |
| <div class="paragraph"> |
| <p>SeText is a textual syntax specification language and associated scanner/parser generator. |
| It can be used to specify the syntax of a language, and automatically generate a scanner and LALR(1) parser(s).</p> |
| </div> |
| <div class="paragraph"> |
| <p>SeText is used as scanner/parser technology for the other tools within the Eclipse ESCET project. |
| It is however a generic scanner/parser generator that can also be used for the development of scanners and parsers for other languages.</p> |
| </div> |
| <div class="paragraph"> |
| <p>See the separate <a href="https://eclipse.org/escet/setext">SeText documentation</a> for more information.</p> |
| </div> |
| <div class="paragraph"> |
| <p></p> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="intro-chapter-tooldef">ToolDef</h3> |
| <div class="paragraph"> |
| <p>ToolDef is a cross-platform and machine-independent scripting language. |
| It supports command line execution, but is also available as plug-in for the Eclipse IDE, providing an integrated development experience.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The ToolDef language features a simple and intuitive syntax to make it easy to write scripts, static typing to catch simple mistakes, a large number of built-in data types and tools, Java integration, and more.</p> |
| </div> |
| <div class="paragraph"> |
| <p>ToolDef libraries with ToolDef compatible tools are available for all tools within the Eclipse ESCET toolkit, allowing cross-platform and machine-independent scripting using Eclipse ESCET tools. |
| ToolDef however is a generic scripting language, and can be used without using any of the other Eclipse ESCET tools. |
| Furthermore, other tools can be made available for use within ToolDef scripts by defining ToolDef libraries for them.</p> |
| </div> |
| <div class="paragraph"> |
| <p>See the separate <a href="https://eclipse.org/escet/tooldef">ToolDef documentation</a> for more information.</p> |
| </div> |
| <div class="paragraph"> |
| <p> |
| </p> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="download-install-chapter-index">Download and install Eclipse ESCET toolkit</h2> |
| <div class="sectionbody"> |
| <div class="admonitionblock warning"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <i class="fa icon-warning" title="Warning"></i> |
| </td> |
| <td class="content"> |
| The Eclipse ESCET project and all its tools are currently in the <a href="https://wiki.eclipse.org/Development_Resources/Process_Guidelines/What_is_Incubation">Incubation Phase</a>. |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="paragraph"> |
| <p>You can download Eclipse ESCET from the following locations:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="https://download.eclipse.org/escet">Eclipse ESCET downloads</a> (for recent versions)</p> |
| </li> |
| <li> |
| <p><a href="https://archive.eclipse.org/escet">Eclipse ESCET archived downloads</a> (for older versions)</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>Downloads for Eclipse ESCET tools are available for the following platforms:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>Windows, x64 (64-bit)</p> |
| </li> |
| <li> |
| <p>Linux, x64 (64-bit)</p> |
| </li> |
| <li> |
| <p>macOS, x64 (64-bit)</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>The downloads are archives that can be extracted anywhere on the local system. |
| Each download contains the Eclipse ESCET toolkit, with the tools available in two ways:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>As IDE based on the Eclipse IDE, providing the full experience. |
| Includes full GUI integration and e.g. text editors with syntax highlighting and error checking.</p> |
| </li> |
| <li> |
| <p>As command line execution scripts (<code>bin</code> directory of the archives), allowing execution in a command line terminal or console, particularly useful for execution of the tools on headless clusters. |
| The command line scripts are only available for Windows and Linux, not for macOS.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>The tools are also available as plug-ins for the Eclipse IDE, by means of an Eclipse P2 update site.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Furthermore, the following documentation is available for download:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>Eclipse ESCET documentation (this documentation)</p> |
| </li> |
| <li> |
| <p><a href="#intro-chapter-chi">Chi</a> documentation</p> |
| </li> |
| <li> |
| <p><a href="#intro-chapter-cif">CIF</a> documentation</p> |
| </li> |
| <li> |
| <p><a href="#intro-chapter-setext">SeText</a> documentation</p> |
| </li> |
| <li> |
| <p><a href="#intro-chapter-tooldef">ToolDef</a> documentation</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>The following additional information is available:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="#download-install-install">Installation of Eclipse ESCET tools</a></p> |
| </li> |
| <li> |
| <p><a href="#download-install-first-start">Starting Eclipse ESCET IDE for the first time</a></p> |
| </li> |
| <li> |
| <p><a href="#download-install-update">Updating Eclipse ESCET tools</a></p> |
| </li> |
| <li> |
| <p><a href="#download-install-remove">Removing Eclipse ESCET tools</a></p> |
| </li> |
| <li> |
| <p><a href="#download-install-find-version">Finding the tool’s version number</a></p> |
| </li> |
| </ul> |
| </div> |
| <div class="sect2"> |
| <h3 id="download-install-install">Installation of Eclipse ESCET tools</h3> |
| <div class="paragraph"> |
| <p>First, obtain the Eclipse ESCET tools:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="#download-install-chapter-index">Download</a> the Eclipse ESCET tools.</p> |
| </li> |
| <li> |
| <p>Extract the downloaded archive somewhere on your hard disk, to a new empty directory where you have read and write access.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>You can now start the Eclipse ESCET IDE:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>For Windows, execute <code>eclipse.exe</code> from the directory that contains the extracted files.</p> |
| </li> |
| <li> |
| <p>For Linux, execute <code>eclipse</code> from the directory that contains the extracted files.</p> |
| </li> |
| <li> |
| <p>For macOS, open the downloaded <code>.dmg</code> file by double clicking. |
| This opens a window with the Eclipse app and a shortcut icon to your Applications folder. |
| Drag the Eclipse icon onto the Applications folder icon. |
| This causes the Eclipse app to be copied to the Applications folder, where all apps can be found. |
| You can now open the Eclipse app from the Applications folder.</p> |
| <div class="paragraph"> |
| <p>The first time you open the Eclipse app, you will get an error message saying either <em>"Eclipse" can’t be opened because Apple cannot check it for malicious software</em> or <em>"Eclipse" can’t be opened because it was not downloaded from the App store</em>. |
| Dismiss the popup by clicking <b class="button">OK</b>. |
| Go to <span class="menuseq"><b class="menu">Apple menu</b> <i class="fa fa-angle-right caret"></i> <b class="menuitem">System Preferences</b></span>, click <em>Security & Privacy</em>, then click tab <em>General</em>. |
| Under <em>Allow apps downloaded from:</em> you should see in light grey two tick boxes: one for <em>App Store</em> and one for <em>App Store and identified developers</em>. |
| Below that, you should see an additional line: <em>"Eclipse.app"</em> was blocked from use because it is not from an identified developer, and after that, a button <b class="button">Open Anyway</b>. |
| Clicking that button will allow the Eclipse app to be executed.</p> |
| </div> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>For more information, see the section on starting the Eclipse ESCET IDE <a href="#download-install-first-start">for the first time</a>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>You can now also use the command line scripts located in the <code>bin</code> directory. |
| These are only available for Windows and Linux, not for macOS. |
| To see which tools are available, simply look in this directory. |
| Each of these tools can be started with the <code>-h</code> or <code>--help</code> option to get further information. |
| You may want to add the <code>bin</code> directory to your <code>PATH</code> environment variable. |
| See e.g. <a href="https://www.java.com/en/download/help/path.xml">How do I set or change the PATH system variable?</a> for how to achieve this.</p> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="download-install-first-start">Starting Eclipse ESCET IDE for the first time</h3> |
| <div class="paragraph"> |
| <p>When you start the Eclipse ESCET IDE for the first time, it will ask you to choose a <a href="#use-terminology-workspace">workspace</a> directory. |
| A workspace directory is where all your settings will be stored. |
| It is also the default directory for <a href="#use-create-project">new projects</a>, in which you will store your files.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Choose a workspace directory and continue. |
| Make sure that you have read and write access to the directory you choose. |
| If you wish, the Eclipse ESCET IDE can remember your workspace directory. |
| Note that if the workspace directory you choose does not yet exist, Eclipse will create it for you.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The first time Eclipse launches in a fresh workspace, you will get a <em>Welcome</em> screen. |
| You can close this tab by clicking the 'X' at the right of the tab, or by clicking on the 'workbench' icon (the right most icon on the welcome page).</p> |
| </div> |
| <div class="paragraph"> |
| <p></p> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="download-install-update">Updating Eclipse ESCET tools</h3> |
| <div class="paragraph"> |
| <p>There are two ways to obtain a newer version of the Eclipse ESCET tools:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>New download of the Eclipse ESCET tools (including command line scripts), to be used side-by-side the older version.</p> |
| </li> |
| <li> |
| <p>In-place update of the Eclipse ESCET tools.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="sect3"> |
| <h4 id="download-install-side-by-side-new-installation">Side by side new installation</h4> |
| <div class="paragraph"> |
| <p>To download and install a new version of Eclipse ESCET tools (including the command line scripts) side-by-side an older version, follow these steps:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>Follow the normal <a href="#download-install-install">installation instructions</a>, extracting the new version to a different directory than the old version.</p> |
| </li> |
| <li> |
| <p>You can copy the data (<a href="#use-terminology-project">projects</a>, files, and settings) of an earlier installation to the new installation. |
| While neither version of the Eclipse ESCET IDE is running, simply remove the <a href="#use-terminology-workspace">workspace</a> directory of the new installation, and copy the workspace directory of the earlier installation to the new installation.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>Using these instructions, it is possible to use multiple installations side by side, at the same time, regardless of whether the installations are the same release or different releases. |
| Simply extract them to different directories and launch them as you would normally do.</p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="download-install-in-place-update">In-place update</h4> |
| <div class="paragraph"> |
| <p>To perform an in-place update of the Eclipse ESCET tools:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>Select <span class="menuseq"><b class="menu">Help</b> <i class="fa fa-angle-right caret"></i> <b class="menuitem">Check for Updates</b></span> within the Eclipse ESCET IDE. |
| Follow the on-screen instructions to perform an in-place update.</p> |
| </li> |
| <li> |
| <p>This will <em>not</em> update the command line scripts.</p> |
| </li> |
| <li> |
| <p>If the tool indicates that no updates are available, while you are sure that an updated version has been released, or if some other problem occurs, please restart the tool and try again. |
| If still an in-place update fails, try to install a new version side-by-side the older version.</p> |
| </li> |
| <li> |
| <p>If you get a dialog stating there is a problem, click the <b class="button">Details</b> button for further details. |
| If may mention <code>Address family not supported by protocol family: connect</code>. |
| If so, close Eclipse, and add the following line to the <code>eclipse.ini</code> file:</p> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlight"><code>-Djava.net.preferIPv4Stack=true</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Add the line at the end of the file, on a line by itself. |
| By default, <code>eclipse.ini</code> is located in the Eclipse ESCET tools installation directory, except for macOS, where instead it is in the <code>Eclipse.app/Contents/MacOS</code> directory inside the Eclipse ESCET tools installation directory. |
| Restart the Eclipse ESCET IDE and try again.</p> |
| </div> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p></p> |
| </div> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="download-install-remove">Removing Eclipse ESCET tools</h3> |
| <div class="paragraph"> |
| <p>Before removing a version of the Eclipse ESCET tools, you may want to preserve (back up) its <a href="#use-terminology-workspace">workspace</a> directory, to keep your data (settings, projects, files). |
| Then, to remove a release, simply remove the directory that contains files that you extracted from the downloaded archive during <a href="#download-install-install">installation</a>.</p> |
| </div> |
| <div class="paragraph"> |
| <p></p> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="download-install-find-version">Finding the tool’s version number</h3> |
| <div class="paragraph"> |
| <p>From the Eclipse ESCET IDE, there are multiple ways to find out which version of the toolkit or specific tools you have currently installed:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>Via the Eclipse <em>About Eclipse ESCET</em> dialog.</p> |
| <div class="paragraph"> |
| <p>The <em>About Eclipse ESCET</em> dialog can be opened via the <span class="menuseq"><b class="menu">Help</b> <i class="fa fa-angle-right caret"></i> <b class="menuitem">About Eclipse ESCET</b></span> menu of the Eclipse ESCET IDE. |
| The dialog shows the version of the Eclipse ESCET toolkit. |
| An <b class="button">Installation Details</b> button is available to open the <em>Eclipse Installation Details</em> dialog. |
| In this dialog, the <em>Installed Software</em> tab shows all the installed software, including their versions under the <em>Version</em> column.</p> |
| </div> |
| </li> |
| <li> |
| <p>Via the option dialogs of the various tools.</p> |
| <div class="paragraph"> |
| <p>Most of the Eclipse ESCET tools can be started in a way that shows the option dialog for that tool. |
| All option dialogs for our tools have a <em>Help</em> category. |
| By clicking on that category, the help text for that tool is shown. |
| The help text includes the version of the tool that you are using.</p> |
| </div> |
| </li> |
| <li> |
| <p>Via the command line option, in a ToolDef script.</p> |
| <div class="paragraph"> |
| <p>If you start an application using a ToolDef script, you can specify command line arguments in the script as well. |
| Start a tool with the <code>-h</code> or <code>--help</code> option to see the command line help text, which includes the version.</p> |
| </div> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>For command line scripts, the following approach is recommended:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>Start a tool with the <code>-h</code> or <code>--help</code> option to see the command line help text, which includes the version.</p> |
| </li> |
| </ul> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="use-chapter-index">Using Eclipse ESCET tools</h2> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p>After you have <a href="#download-install-install">installed</a> the Eclipse ESCET tools, you can start using them. |
| The following information is available to get you started on using the Eclipse ESCET tools in general, and applies to the various tools in the toolkit:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="#use-terminology">Eclipse terminology</a></p> |
| </li> |
| <li> |
| <p><a href="#use-projects">Working with projects, directories, and files</a></p> |
| </li> |
| <li> |
| <p><a href="#use-edit-exec">Editing files and executing commands</a></p> |
| </li> |
| <li> |
| <p><a href="#use-escet-perspective">Eclipse ESCET perspective</a></p> |
| </li> |
| <li> |
| <p><a href="#use-apps-view">Applications view</a></p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>Consult the documentation of the individual tools for specific information regarding their use.</p> |
| </div> |
| <div class="paragraph"> |
| <p></p> |
| </div> |
| <div class="sect2"> |
| <h3 id="use-terminology">Eclipse terminology</h3> |
| <div class="paragraph"> |
| <p>The Eclipse ESCET IDE is based on the <em>Eclipse IDE</em>, a cross platform Integrated Development Environment (IDE). |
| There is quite a bit of terminology that is used within the IDE. |
| If you are not familiar with Eclipse terminology, it may be difficult to use the Eclipse ESCET IDE. |
| Here we’ll explain some basic Eclipse terminology:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="#use-terminology-workspace">Eclipse workspace</a></p> |
| </li> |
| <li> |
| <p><a href="#use-terminology-view">Eclipse views</a></p> |
| </li> |
| <li> |
| <p><a href="#use-terminology-project">Eclipse projects</a></p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p> |
| |
| |
| |
| </p> |
| </div> |
| <div class="sect3"> |
| <h4 id="use-terminology-workspace">Eclipse workspace</h4> |
| <div class="paragraph"> |
| <p>Eclipse stores all its settings in a so-called <em>workspace</em>. |
| The workspace is simply a directory on your computer. |
| You can choose any directory you like to serve as a workspace, as long as you have write access to that directory. |
| It is usually best to choose an empty directory or a directory that does not yet exist as your workspace.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Typically, and by default, a directory named <code>workspace</code> inside your Eclipse ESCET installation directory is used. |
| Eclipse will ask you to choose a workspace directory when you start the Eclipse ESCET IDE for the <a href="#download-install-first-start">first time</a>.</p> |
| </div> |
| <div class="paragraph"> |
| <p> |
| |
| |
| |
| |
| |
| The actual settings are stored in a sub-directory of the workspace directory, called <code>.metadata</code>. |
| You should avoid manually manipulating this directory. |
| Note that because the name of the directory starts with a dot (<code>.</code>), depending on your operating system, file browser, and settings, the directory may be hidden.</p> |
| </div> |
| <div class="paragraph"> |
| <p> |
| </p> |
| </div> |
| <div id="use-terminology-workspace-change" class="paragraph"> |
| <p>You can easily change your workspace directory from within Eclipse, by selecting <span class="menuseq"><b class="menu">File</b> <i class="fa fa-angle-right caret"></i> <b class="menuitem">Switch workspace</b></span>. |
| Select one of the workspaces from the list of last used workspaces, or select <b class="menuref">Other…​</b> to freely select any directory on your system to use as a workspace directory.</p> |
| </div> |
| <div class="paragraph"> |
| <p> |
| It is possible to run multiple instances of Eclipse at the same time, but each instance must use its own workspace.</p> |
| </div> |
| <div class="paragraph"> |
| <p> |
| |
| The workspace is also the default directory for <a href="#use-create-project">new projects</a>. |
| However, <a href="#use-terminology-project">projects</a> don’t have to be physically located inside your workspace directory. |
| They can be stored in any directory on your system. |
| Whenever you <a href="#use-create-project">create a project</a> and store it outside of your workspace, or whenever you <a href="#use-import-project">import an existing project</a> from outside your workspace, it is <em>linked</em> to the workspace, but remains physically stored in a directory outside of the workspace.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Having projects stored outside of the workspace has some benefits. |
| The most important benefit is that you can remove the workspace directory, without losing your files.</p> |
| </div> |
| <div class="paragraph"> |
| <p> |
| |
| |
| |
| </p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="use-terminology-view">Eclipse views</h4> |
| <div class="paragraph"> |
| <p>Eclipse is an Integrated Development Environment (IDE) with a lot of functionality. |
| Most of the functionality is available through <em>views</em>. |
| A view is a part of the Eclipse graphical user interface. |
| Views can be thought of as 'sub-windows'. |
| When you start Eclipse you are likely to see the <em>Project Explorer</em> or <em>Package Explorer</em> view on the left, and the <em>Problems</em> view at the bottom.</p> |
| </div> |
| <div class="paragraph"> |
| <p> |
| </p> |
| </div> |
| <div class="sect4"> |
| <h5 id="use-terminology-view-open">Opening a view</h5> |
| <div class="paragraph"> |
| <p>To open/show a view, select <span class="menuseq"><b class="menu">Window</b> <i class="fa fa-angle-right caret"></i> <b class="menuitem">Show view</b></span> and then choose the view that you wish to open.</p> |
| </div> |
| <div class="paragraph"> |
| <p>If the particular view that you wish to open is not in that menu, choose <b class="menuref">Other…​</b> instead. |
| A new dialog opens, in which you can find all available views. |
| The views are organized into categories. |
| Expand a category, select the desired view, and click <b class="button">OK</b>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Alternatively, in the <b class="menuref">Show view</b> dialog, enter the name of the view (or the first part of it) in the filter box at the top of the dialog, and observe how views that don’t match the filter are no longer displayed. |
| This makes it easier to find the desired view.</p> |
| </div> |
| <div class="paragraph"> |
| <p> |
| |
| |
| |
| |
| </p> |
| </div> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="use-terminology-project">Eclipse projects</h4> |
| <div class="paragraph"> |
| <p>Eclipse, being an Integrated Development Environment (IDE), does not only allow you to <a href="#use-edit">edit</a> a single file, and <a href="#use-commands">simulate</a> it, but also allows you to <em>manage</em> your files.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Eclipse works with so-called <em>projects</em>. |
| A project is a collection of files and directories. |
| A project may be located anywhere on your system, even though by default project are <a href="#use-create-project">created</a> in your <a href="#use-terminology-workspace">workspace</a> directory.</p> |
| </div> |
| <div class="paragraph"> |
| <p>A project is essentially a directory on your computer, with a special file named <code>.project</code>. |
| This special file stores the information about your project, such as the name of the project. |
| It is recommended to keep the name of the project as Eclipse sees it, the same as the name of the directory in which the project is stored on your hard disk.</p> |
| </div> |
| <div class="paragraph"> |
| <p>You can see the projects that Eclipse knows about in the <em>Project Explorer</em> or <em>Package Explorer</em> <use-terminology-view,view>>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>For more information on projects, see the <a href="#use-projects">Working with projects, directories, and files</a> section.</p> |
| </div> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="use-projects">Working with projects, directories, and files</h3> |
| <div class="paragraph"> |
| <p>Eclipse uses <a href="#use-terminology-project">projects</a> to manage files and directories (also called <em>folders</em>). |
| This section contains information on the following topics:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="#use-create-project">Creating a new project</a></p> |
| </li> |
| <li> |
| <p><a href="#use-import-project">Importing an existing project</a></p> |
| </li> |
| <li> |
| <p><a href="#use-create-dir">Creating a new directory</a></p> |
| </li> |
| <li> |
| <p><a href="#use-create-file">Creating a new file</a></p> |
| </li> |
| <li> |
| <p><a href="#use-rename">Renaming a file, directory, or project</a></p> |
| </li> |
| <li> |
| <p><a href="#use-locations">Locating files, directories, and projects</a></p> |
| </li> |
| <li> |
| <p><a href="#use-refresh">Refreshing a file, directory, or project</a></p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p> |
| </p> |
| </div> |
| <div class="sect3"> |
| <h4 id="use-create-project">Creating a new project</h4> |
| <div class="paragraph"> |
| <p>To create a new project, ensure you have either the <em>Project Explorer</em> or <em>Package Explorer</em> <a href="#use-terminology-view">view</a> visible.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Select <span class="menuseq"><b class="menu">File</b> <i class="fa fa-angle-right caret"></i> <b class="submenu">New</b> <i class="fa fa-angle-right caret"></i> <b class="menuitem">Project…​</b></span> to open the <em>New Project</em> window. |
| Alternatively, right click somewhere in the <em>Project Explorer</em> or <em>Package Explorer</em> view, and select <span class="menuseq"><b class="menu">New</b> <i class="fa fa-angle-right caret"></i> <b class="menuitem">Project…​</b></span>, to open the same window.</p> |
| </div> |
| <div class="paragraph"> |
| <p>In the <em>New Project</em> window, from the <em>General</em> category select <em>Project</em>, and click the <b class="button">Next ></b> button.</p> |
| </div> |
| <div class="paragraph"> |
| <p>In the next window, enter a project name, for example <code>models</code>.</p> |
| </div> |
| <div class="paragraph"> |
| <p> |
| |
| By default, a project is created inside your <a href="#use-terminology-workspace">workspace</a> directory. |
| If you want it at a different place (so you can remove the workspace without losing your projects), uncheck the <em>Use default location</em> option, and enter a <em>Location</em>. |
| Make sure the location does not yet exist, for example by ending with the project name. |
| It is recommended to always create a project in a directory that has the same name as the project.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Click the <b class="button">Finish</b> button to create the project. |
| Observe how it appears in the <em>Project Explorer</em> or <em>Package Explorer</em> view.</p> |
| </div> |
| <div class="paragraph"> |
| <p> |
| |
| |
| |
| |
| </p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="use-import-project">Importing an existing project</h4> |
| <div class="paragraph"> |
| <p>If you previously created a project, but it is no longer visible in your <em>Project Explorer</em> or <em>Package Explorer</em> <a href="#use-terminology-view">view</a>, you can import it. |
| Imported projects are <em>linked</em> to your <a href="#use-terminology-workspace">workspace</a>, but remain in their original location on your hard disk (by default, they are <em>not</em> moved or copied to your workspace directory).</p> |
| </div> |
| <div class="paragraph"> |
| <p>Importing existing projects is particularly useful if you removed you workspace directory and started with a fresh one, e.g. for a new installation.</p> |
| </div> |
| <div class="paragraph"> |
| <p>To import one or more existing projects, select <span class="menuseq"><b class="menu">File</b> <i class="fa fa-angle-right caret"></i> <b class="menuitem">Import…​</b></span> to open the <em>Import</em> window. |
| Alternatively, right click somewhere in the <em>Project Explorer</em> or <em>Package Explorer</em> view, and select <b class="menuref">Import…​</b> to open the same window.</p> |
| </div> |
| <div class="paragraph"> |
| <p>In the <em>Import</em> window, from the <em>General</em> category, select <em>Existing Projects into Workspace</em>, and click <b class="button">Next ></b>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>In the next window, in <em>Select root directory</em>, point it to the directory that contains the project you wish to import. |
| The available projects in the given root directory, and all its sub-directories (recursively), are listed in the <em>Projects</em> list. |
| Select the project(s) you want to import, by checking the relevant check boxes, and click <b class="button">Finish</b>. |
| Observe how the project(s) appear(s) in the <em>Project Explorer</em> or <em>Package Explorer</em> view.</p> |
| </div> |
| <div class="paragraph"> |
| <p> |
| |
| |
| </p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="use-remove-project">Removing a project from Eclipse</h4> |
| <div class="paragraph"> |
| <p>To remove a project from Eclipse, ensure you have either the <em>Project Explorer</em> or <em>Package Explorer</em> <a href="#use-terminology-view">view</a> visible.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Right click the project in the <em>Project Explorer</em> or <em>Package Explorer</em> view and choose <b class="menuref">Delete</b>. |
| Alternatively, select it and press the <kbd>Delete</kbd> key on your keyboard. |
| The <em>Delete Resources</em> dialog appears. |
| To only remove the project from Eclipse, and keep the files on your hard disk, disable the <em>Delete project contents on disk (cannot be undone)</em> option and click the <b class="button">OK</b> button. |
| Alternatively, to remove the project from Eclipse and also remove all the files in the project from your hard disk, enable the <em>Delete project contents on disk (cannot be undone)</em> option and click the <b class="button">OK</b> button.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Wait for Eclipse to complete the removal operation.</p> |
| </div> |
| <div class="paragraph"> |
| <p> |
| |
| |
| |
| |
| </p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="use-create-dir">Creating a new directory</h4> |
| <div class="paragraph"> |
| <p>You can structure large collections of files, by putting them into different directories (also called <em>folders</em>). |
| Directories can only be created in <a href="#use-terminology-project">projects</a>, or in other directories.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Select the project or directory in which you want to create a new directory (by left clicking its name in the <em>Project Explorer</em> or <em>Package Explorer</em> <a href="#use-terminology-view">view</a>, and create a new directory by selecting <span class="menuseq"><b class="menu">File</b> <i class="fa fa-angle-right caret"></i> <b class="submenu">New</b> <i class="fa fa-angle-right caret"></i> <b class="menuitem">Folder</b></span>. |
| Alternatively, right click on the project or directory instead, and from the popup menu select <span class="menuseq"><b class="menu">New</b> <i class="fa fa-angle-right caret"></i> <b class="menuitem">Folder</b></span>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>In the <em>New Folder</em> window, enter the <em>Folder name</em>, and click <b class="button">Finish</b>.</p> |
| </div> |
| <div class="paragraph"> |
| <p> |
| |
| </p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="use-create-file">Creating a new file</h4> |
| <div class="paragraph"> |
| <p>Select the <a href="#use-terminology-project">project</a> or directory in which you want to create a new file (by left clicking its name in the <em>Project Explorer</em> or <em>Package Explorer</em> <a href="#use-terminology-view">view</a>), and create a new file by selecting <span class="menuseq"><b class="menu">File</b> <i class="fa fa-angle-right caret"></i> <b class="submenu">New</b> <i class="fa fa-angle-right caret"></i> <b class="menuitem">File</b></span>. |
| Alternatively, right click on the project or directory instead, and from the popup menu select <span class="menuseq"><b class="menu">New</b> <i class="fa fa-angle-right caret"></i> <b class="menuitem">File</b></span>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>In the <em>New File</em> window, enter the <em>File name</em>, and click <b class="button">Finish</b>. |
| Make sure to give the file the correct file extension. |
| E.g. CIF files should end with <code>.cif</code>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>An editor for the new file opens, and you can start <a href="#use-edit">editing it</a>.</p> |
| </div> |
| <div class="paragraph"> |
| <p> |
| |
| |
| |
| |
| |
| |
| </p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="use-rename">Renaming a file, directory, or project</h4> |
| <div class="paragraph"> |
| <p>To rename a file, directory, or <a href="#use-terminology-project">project</a>, select it by left clicking its name in the <em>Project Explorer</em> or <em>Package Explorer</em> <a href="#use-terminology-view">view</a>, and then select <span class="menuseq"><b class="menu">File</b> <i class="fa fa-angle-right caret"></i> <b class="menuitem">Rename…​</b></span>. |
| Alternatively, right click on the file, directory, or project instead, and from the popup menu select <span class="menuseq"><b class="menu">Refactor</b> <i class="fa fa-angle-right caret"></i> <b class="menuitem">Rename…​</b></span>. |
| A second alternative is to select the file, directory, or project, and then press the <kbd>F2</kbd> key.</p> |
| </div> |
| <div class="paragraph"> |
| <p>In the <em>Rename Resource</em> window, enter the <em>New name</em>, and click <b class="button">OK</b>.</p> |
| </div> |
| <div class="paragraph"> |
| <p> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| </p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="use-locations">Locating files, directories, and projects</h4> |
| <div class="paragraph"> |
| <p>Often, it is convenient to be able to manage files not from inside Eclipse, but from outside Eclipse, for instance in a file explorer provided by your operating system. |
| The <em>Properties</em> <a href="#use-terminology-view">view</a> can be used to find out where the files, directories, and projects that are in Eclipse, are located on your hard disk. |
| With the <em>Properties</em> view visible, select a file, directory, or project in the <em>Project Explorer</em> or <em>Package Explorer</em> view. |
| In the <em>Property</em> column of the <em>Properties</em> view, look for <em>location</em>. |
| The corresponding <em>Value</em> indicates where the file, directory, or project is located on your hard disk. |
| Note that you can right click the location and choose <em>Copy</em> to copy the location to the clipboard.</p> |
| </div> |
| <div class="paragraph"> |
| <p>As an alternative to the <em>Properties</em> view, you can also use the <em>Properties</em> window. |
| Right click a file, directory, or project in the <em>Project Explorer</em> or <em>Package Explorer</em> view and choose <b class="menuref">Properties</b>. |
| In the window that shows, select <em>Resource</em> on the left, if it is not already selected. |
| Then, on the right, look for the <em>Location</em>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>To directly open the directory that contains a file, directory, or project in your system’s file explorer, right click the file, directory, or project in the <em>Project Explorer</em> or <em>Package Explorer</em> view and choose <span class="menuseq"><b class="menu">Show In</b> <i class="fa fa-angle-right caret"></i> <b class="menuitem">System Explorer</b></span>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Don’t forget to <a href="#use-refresh">refresh</a> your projects in Eclipse after manipulating them outside Eclipse.</p> |
| </div> |
| <div class="paragraph"> |
| <p> |
| |
| |
| |
| |
| |
| </p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="use-refresh">Refreshing a file, directory, or project</h4> |
| <div class="paragraph"> |
| <p>Whenever changes are made to files or directories from outside Eclipse, and those files or directories are also in one of the projects inside Eclipse, the changes are <em>not</em> always automatically reflected in the <em>Project Explorer</em> or <em>Package Explorer</em> <a href="#use-terminology-view">view</a>. |
| To ensure that the current state of the files and directories are properly reflected in Eclipse, a refresh is required. |
| To refresh a file, directory, or project, right click it, and choose <b class="menuref">Refresh</b>. |
| Any files and directories that no longer exist will disappear from Eclipse. |
| Any new files and directories created outside Eclipse will appear in Eclipse as well.</p> |
| </div> |
| <div class="paragraph"> |
| <p> |
| |
| |
| </p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="use-filesize">Checking the size of a file</h4> |
| <div class="paragraph"> |
| <p>When working with files, you may occasionally encounter large files. |
| Opening large files in Eclipse can cause serious <a href="#performance-chapter-index">performance problems</a>. |
| You can use the <em>Properties</em> <a href="#use-terminology-view">view</a> to check the size of a file. |
| With the <em>Properties</em> view visible, select a file in the <em>Project Explorer</em> or <em>Package Explorer</em> view. |
| In the <em>Property</em> column of the <em>Properties</em> view, look for <em>size</em>. |
| The corresponding <em>Value</em> indicates the size of the file.</p> |
| </div> |
| <div class="paragraph"> |
| <p>As an alternative to the <em>Properties</em> view, you can also use the <em>Properties</em> window. |
| Right click a file in the <em>Project Explorer</em> or <em>Package Explorer</em> view and choose <b class="menuref">Properties</b>. |
| In the window that shows, select <em>Resource</em> on the left, if it is not already selected. |
| Then, on the right, look for the <em>Size</em>.</p> |
| </div> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="use-edit-exec">Editing files and executing commands</h3> |
| <div class="paragraph"> |
| <p>This section contains information on <a href="#use-edit">editing text files</a> and <a href="#use-commands">executing commands</a> (such as starting a simulator).</p> |
| </div> |
| <div class="paragraph"> |
| <p> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| </p> |
| </div> |
| <div class="sect3"> |
| <h4 id="use-edit">Editing a text file</h4> |
| <div class="paragraph"> |
| <p>To edit a file, double click it in the <em>Project explorer</em> or <em>Package explorer</em> <a href="#use-terminology-view">view</a>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Whenever you open a text file, change it, or the editor receives the focus, the file is checked for errors. |
| If there are errors (or warnings), they are displayed in the editor as shown below.</p> |
| </div> |
| <div class="imageblock"> |
| <div class="content"> |
| <img src="./use/model_with_error.png" alt="model with error"> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Note that you can hover over an error in the source code itself to find out what the problem is. |
| Alternatively, you can hover over the error marker in the margin of the editor, or look at the <em>Problems</em> view. |
| Also, if a file has an error or a warning, an overlay icon is shown in the <em>Project Explorer</em> and <em>Package Explorer</em> views, for that file, the directories that contain it, and the <a href="#use-terminology-project">project</a> that contains it.</p> |
| </div> |
| <div class="paragraph"> |
| <p> |
| |
| |
| |
| </p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="use-commands">Executing commands</h4> |
| <div class="paragraph"> |
| <p>If you have a file without errors, you can execute certain commands on it. |
| The various Eclipse ESCET tools add <em>commands</em> to Eclipse. |
| For instance, CIF models can be simulated using a simulation command.</p> |
| </div> |
| <div class="paragraph"> |
| <p>To execute a command on a file, right click the file in the <em>Project Explorer</em> or <em>Package Explorer</em> <a href="#use-terminology-view">view</a>, and select the command. |
| Alternatively, if you have the file open in an editor, right click the editor, and select the command.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The commands that are available are determined by the file extension of the file. |
| That is, only the commands applicable for a certain file are shown.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Besides simulation, other commands may be available, depending on the modeling language and tools you use. |
| Consult the specific documentation for each tool for more details.</p> |
| </div> |
| <div class="paragraph"> |
| <p> |
| |
| </p> |
| </div> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="use-escet-perspective">Eclipse ESCET perspective</h3> |
| <div class="paragraph"> |
| <p>The layout of the different parts of the Eclipse ESCET IDE, including the position and size of the various <a href="#use-terminology-view">views</a>, can be configured per perspective. |
| Different perspectives allow you to use different layouts for different tasks.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The Eclipse ESCET IDE ships with some built-in perspectives. |
| The default <em>ESCET</em> perspective is ideally suited for the use of the Eclipse ESCET software.</p> |
| </div> |
| <div class="paragraph"> |
| <p> |
| |
| You can manually open the <em>ESCET</em> perspective (or any other perspective), by selecting <span class="menuseq"><b class="menu">Window</b> <i class="fa fa-angle-right caret"></i> <b class="submenu">Perspective</b> <i class="fa fa-angle-right caret"></i> <b class="submenu">Open Perspective</b> <i class="fa fa-angle-right caret"></i> <b class="menuitem">Other…​</b></span>. |
| Then, in the <em>Open Perspective</em> dialog, select the <em>ESCET</em> perspective from the list, and click the <b class="button">OK</b> button.</p> |
| </div> |
| <div class="paragraph"> |
| <p> |
| |
| By default, the Eclipse ESCET IDE shows the opened perspectives at the top right corner of the IDE. |
| Each perspective is a button that can be used to active it. |
| If the button appears in a pushed state, that perspective is active. |
| The following image shows an Eclipse ESCET IDE with two open perspectives: the <em>Resource</em> perspective and the <em>ESCET</em> perspective. |
| The <em>ESCET</em> perspective is the currently enabled perspective.</p> |
| </div> |
| <div class="imageblock"> |
| <div class="content"> |
| <img src="./use/perspectives.png" alt="perspectives"> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>By default, the <em>ESCET</em> perspective shows the following views:</p> |
| </div> |
| <div class="paragraph"> |
| <p> |
| |
| |
| |
| |
| </p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>Project explorer (top left)</p> |
| </li> |
| <li> |
| <p><a href="#use-apps-view">Applications</a> (bottom left)</p> |
| </li> |
| <li> |
| <p>Problems (bottom, grouped)</p> |
| </li> |
| <li> |
| <p>Properties (bottom, grouped)</p> |
| </li> |
| <li> |
| <p>Console (bottom, grouped)</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p> |
| |
| You can manually <a href="#use-terminology-view-open">open</a> additional <a href="#use-terminology-view">views</a>, close some views, move views around, change the size of the different views, etc. |
| If at any time you wish to go back to the original layout, you can reset the perspective, by selecting <span class="menuseq"><b class="menu">Window</b> <i class="fa fa-angle-right caret"></i> <b class="submenu">Perspective</b> <i class="fa fa-angle-right caret"></i> <b class="menuitem">Reset Perspective…​</b></span>. |
| Click the <b class="button">OK</b> button to confirm.</p> |
| </div> |
| <div class="paragraph"> |
| <p> |
| |
| Whenever a new release changes the default layout of a perspective, for instance by adding a new default view, you can reset the perspective to get the new view, or you can <a href="#use-terminology-view-open">open</a> that view it manually.</p> |
| </div> |
| <div class="paragraph"> |
| <p> |
| </p> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="use-apps-view">Applications view</h3> |
| <div class="paragraph"> |
| <p>The <em>Applications</em> <a href="#use-terminology-view">view</a> can be used to manage the applications of the Eclipse ESCET software running within the Eclipse ESCET IDE.</p> |
| </div> |
| <div class="imageblock"> |
| <div class="content"> |
| <img src="./use/apps_view.png" alt="apps view"> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p> |
| </p> |
| </div> |
| <div class="sect3"> |
| <h4 id="use-opening-the-view">Opening the view</h4> |
| <div class="paragraph"> |
| <p>The <em>Applications</em> view can be <a href="#use-terminology-view-open">opened</a> by selecting <span class="menuseq"><b class="menu">Window</b> <i class="fa fa-angle-right caret"></i> <b class="submenu">Show view</b> <i class="fa fa-angle-right caret"></i> <b class="menuitem">Applications</b></span>, assuming the <a href="#use-escet-perspective">ESCET perspective</a> is enabled.</p> |
| </div> |
| <div class="paragraph"> |
| <p> |
| |
| |
| |
| </p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="use-apps-view-status">Application status</h4> |
| <div class="paragraph"> |
| <p>The view shows a list of running applications. |
| If an application starts another application, it is shown as a child, forming a tree structure. |
| Each item of the tree shows a single application. |
| In the example screenshot above, there are four running applications. |
| The first application is a <em>ToolDef interpreter</em>, which is running a second application, a <em>CIF simulator</em>. |
| The third application is also a <em>ToolDef interpreter</em>, which is running a fourth application, also a <em>CIF simulator</em>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>To the left of each item, the status of the application is indicated. |
| The following statuses are available:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><span class="image"><img src="./use/status_starting.png" alt="status starting"></span> Staring</p> |
| </li> |
| <li> |
| <p><span class="image"><img src="./use/status_running.png" alt="status running"></span> Running</p> |
| </li> |
| <li> |
| <p><span class="image"><img src="./use/status_terminating.png" alt="status terminating"></span> Terminating</p> |
| </li> |
| <li> |
| <p><span class="image"><img src="./use/status_terminated.png" alt="status terminated"></span> Terminated</p> |
| </li> |
| <li> |
| <p><span class="image"><img src="./use/status_finished.png" alt="status finished"></span> Finished</p> |
| </li> |
| <li> |
| <p><span class="image"><img src="./use/status_failed.png" alt="status failed"></span> Failed</p> |
| </li> |
| <li> |
| <p><span class="image"><img src="./use/status_crashed.png" alt="status crashed"></span> Crashed</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>When an application is started, it get a <em>Starting</em> state. |
| Once the options have been processed from the command line and the option dialog (if requested), the actual application code is executed, and the status changes to <em>Running</em>. |
| If the application is not terminated at the request of the user, the application will be done with its execution after some time. |
| If execution finished without problems, it then reaches status <em>Finished</em>. |
| If execution failed for some reason, it reaches status <em>Failed</em> instead. |
| If the execution crashed due to internal problems, the application reaches status <em>Crashed</em>. |
| If however the user <a href="#use-apps-view-termination">terminates</a> the application, the status is first changed to <em>Terminating</em>. |
| Once the application has successfully been terminated, the status changes to <em>Terminated</em>.</p> |
| </div> |
| <div class="paragraph"> |
| <p> |
| You can also view these statuses and their corresponding icons from within the IDE, by opening the <em>Application Status Legend</em> dialog, which is available via the view’s drop-down button popup menu:</p> |
| </div> |
| <div class="imageblock"> |
| <div class="content"> |
| <img src="./use/show_status_legend.png" alt="show status legend"> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p> |
| </p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="use-apps-view-termination">Termination</h4> |
| <div class="paragraph"> |
| <p>The <em>Applications</em> view supports terminating running applications. |
| There are several ways to terminate an application using the <em>Applications</em> view.</p> |
| </div> |
| <div class="paragraph"> |
| <p>When terminating an application (with a <em>Starting</em> or <em>Running</em> state), the application will get a <em>Terminating</em> state. |
| Applications occasionally poll for termination requests. |
| Therefore, it may take a while for the application to actually process the termination request. |
| Once it has been processed, the application will have terminated, and the status changes to <em>Terminated</em> as well.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Applications can’t process a termination request while a modal dialog (such as the option dialog) is open, or when input is requested from the console. |
| They will terminate as soon as possible, after the dialog is closed, or the user has provided input via the console.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The following buttons related to termination are available in the <em>Applications</em> view’s toolbar:</p> |
| </div> |
| <div class="paragraph"> |
| <p> |
| </p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>Auto Terminate (<span class="image"><img src="./use/command_auto_terminate.png" alt="command auto terminate"></span>)</p> |
| <div class="paragraph"> |
| <p>Most users will only want to have a single application running at a time, including application started by that application, etc. |
| To facilitate this, the view provides an <em>Auto Terminate</em> feature. |
| This feature can be enabled and disabled from the view’s toolbar. |
| It is enabled by default. |
| Your choice whether to enable or disable this option will be remembered, even after Eclipse is restarted. |
| The feature only has an effect if the view is shown in at least one of the opened <a href="#use-escet-perspective">perspectives</a>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>If enabled, and a new application (not started by another already running application) is started, all other already running applications are automatically terminated. |
| The new application starts its execution immediately. |
| The already running applications will start to process the termination request, and will terminate as soon as possible.</p> |
| </div> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p> |
| </p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>Terminate All (<span class="image"><img src="./use/command_terminate_all.png" alt="command terminate all"></span>)</p> |
| <div class="paragraph"> |
| <p>The view’s toolbar contains a <em>Terminate All</em> button that can be used to terminate all running applications. |
| The button is only enabled when at least one of the listed applications can be terminated. |
| When clicked, all running applications are given a termination request, and will terminate as soon as possible.</p> |
| </div> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p> |
| </p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>Terminate (<span class="image"><img src="./use/command_terminate.png" alt="command terminate"></span>)</p> |
| <div class="paragraph"> |
| <p>The view’s drop-down button popup menu contains a <em>Terminate</em> item that can be used to terminate all selected applications that are running. |
| The item is only enabled when at least one of the listed applications that is selected, can be terminated. |
| When clicked, all selected applications that can be terminated, are given a termination request, and will terminate as soon as possible.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Even when a child application is selected, all applications in the entire tree, starting from the root, will be given a termination request, if not already terminated or having finished their execution. |
| In other words, only an entire tree of related applications can be terminated.</p> |
| </div> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p> |
| </p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="use-apps-view-removal">Removal</h4> |
| <div class="paragraph"> |
| <p>The <em>Applications</em> view can get a bit crowded, if already terminated applications are not removed from the list. |
| To keep only relevant applications, the <em>Applications</em> view supports removing items from the list.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Only applications which have finished execution can be removed. |
| That is, the root of the tree of applications needs to have a <em>Terminated</em>, <em>Finished</em>, <em>Failed</em>, or <em>Crashed</em> status, for the tree to be allowed to be removed. |
| This prevents removing applications that are still running, which would make it impossible to terminate them, or observe their status.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The following buttons related to removal are available in the <em>Applications</em> view’s toolbar:</p> |
| </div> |
| <div class="paragraph"> |
| <p> |
| </p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>Auto Remove (<span class="image"><img src="./use/command_auto_remove.png" alt="command auto remove"></span>)</p> |
| <div class="paragraph"> |
| <p>Most users will only want to only have applications listed in the view, that are either still running, or have just finished execution. |
| To facilitate this, the view provides an <em>Auto Remove</em> feature. |
| This feature can be enabled and disabled from the view’s toolbar. |
| It is enabled by default. |
| Your choice whether to enable or disable this option will be remembered, even after Eclipse is restarted. |
| The feature only has an effect if the view is shown in at least one of the opened <a href="#use-escet-perspective">perspectives</a>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>If enabled, and a new application (not started by another already running application) is started, all already terminated applications, will be removed from the list. |
| If combined with the <em>Auto Terminate</em> feature, all other applications that can not be removed immediately because they are still running, will be removed as soon as possible, after they have been terminated.</p> |
| </div> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p> |
| </p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>Remove All (<span class="image"><img src="./use/command_remove_all.png" alt="command remove all"></span>)</p> |
| <div class="paragraph"> |
| <p>The view’s drop-down button popup menu contains a <em>Remove All</em> item that can be used to remove all listed applications that may be removed. |
| The item is only enabled when at least one of the listed applications can be removed. |
| When clicked, all listed applications that can be removed, are immediately removed from the list.</p> |
| </div> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p> |
| </p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>Remove (<span class="image"><img src="./use/command_remove.png" alt="command remove"></span>)</p> |
| <div class="paragraph"> |
| <p>The view’s drop-down button popup menu contains a <em>Remove</em> item that can be used to remove all selected applications that can be removed. |
| The item is only enabled when at least one of the listed applications that is selected, can be removed. |
| When clicked, all selected applications that can be removed, are immediately removed from the list.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Even when a child application is selected, all applications in the entire tree, starting from the root, will be removed. |
| In other words, only an entire tree of related applications can be removed, and only if all applications in that tree have finished execution.</p> |
| </div> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p> |
| </p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="use-apps-view-expansion">Expansion</h4> |
| <div class="paragraph"> |
| <p>When one application starts another application, they are listed in a tree, with the parent containing the child. |
| When running a single application, it may be of interest to see which child applications are being executed by the parent application. |
| However, when executing multiple applications, this may quickly crowd the view. |
| It may then be better to keep all root items collapsed, only showing the status of the root applications. |
| This provides an overview over those multiple applications.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The following buttons related to expansion are available in the <em>Applications</em> view’s toolbar:</p> |
| </div> |
| <div class="paragraph"> |
| <p> |
| </p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>Auto Expand (<span class="image"><img src="./use/command_auto_expand.png" alt="command auto expand"></span>)</p> |
| <div class="paragraph"> |
| <p>Most users will have the <em>Auto Terminate</em> and <em>Auto Remove</em> features enabled, and will thus only have a single application listed. |
| They will want to automatically expand a parent application, to show its children. |
| To facilitate this, the view provides an <em>Auto Expand</em> feature. |
| This feature can be enabled and disabled from the view’s toolbar. |
| It is enabled by default. |
| Your choice whether to enable or disable this option will be remembered, even after Eclipse is restarted. |
| The feature only has an effect if the view is shown in at least one of the opened <a href="#use-escet-perspective">perspectives</a>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>If enabled, and a parent application starts a child application, the item for the parent application in the view, is automatically expanded to show its children. |
| If disabled, no items will be automatically expanded.</p> |
| </div> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p> |
| |
| |
| </p> |
| </div> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="performance-chapter-index">Resolving performance and memory problems</h2> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p>During the use of the Eclipse ESCET toolkit, you may encounter performance and/or memory problems. |
| This includes slow execution, performance degradation over time, out-of-memory errors, etc. |
| One way to solve such problems, is to use a computer that is faster and/or has more memory. |
| If that is not an option, or if that doesn’t help, the following information is available to help you get rid of these problems:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="#performance-clear-console">Clearing the console</a></p> |
| </li> |
| <li> |
| <p><a href="#performance-reduce-console-output">Reducing console output</a></p> |
| </li> |
| <li> |
| <p><a href="#performance-close-running-apps">Closing running applications</a></p> |
| </li> |
| <li> |
| <p><a href="#performance-tweak-perf-settings">Tweaking performance settings</a></p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>In particular, the <a href="#performance-tweak-perf-settings">Tweaking performance settings</a> section provides information on how to give Eclipse ESCET tools more memory. |
| This solves the most common performance problems and out-of-memory errors.</p> |
| </div> |
| <div class="paragraph"> |
| <p> |
| |
| </p> |
| </div> |
| <div class="sect2"> |
| <h3 id="performance-clear-console">Clearing the console</h3> |
| <div class="paragraph"> |
| <p>In the Eclipse ESCET IDE, the <em>Console</em> <a href="#use-terminology-view">view</a> displays the console output generated by the applications that you run. |
| This console keeps all the output in memory. |
| If the application that you run creates a lot of output, this can quickly fill the available memory, and lead to <a href="#performance-tweak-perf-settings-practical">out of memory</a> errors.</p> |
| </div> |
| <div class="paragraph"> |
| <p>By clearing the console, the output is removed and the associated memory becomes free for other uses. |
| To clear the console, right click the console (the part of the view that contains the actual console text) and choose <b class="menuref">Clear</b> from the popup menu. |
| Alternatively, click the <em>Clear Console</em> button (<span class="image"><img src="./performance/clear_console.png" alt="clear console"></span>) of the <em>Console</em> view’s toolbar.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The Eclipse <em>Console</em> view does not just keep the console output of the currently running application or applications in memory, it also keeps the output of all terminated applications in memory. |
| To look at the applications that you executed, click the small arrow next to the <em>Display Selected Console</em> icon (<span class="image"><img src="./performance/console_pages.png" alt="console pages"></span>) of the <em>Console</em> view’s toolbar.A list of executed applications will appear, that looks something like this:</p> |
| </div> |
| <div class="imageblock"> |
| <div class="content"> |
| <img src="./performance/console_pages_list.png" alt="console pages list"> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>In this case, four applications have been launched. |
| The console output for the fourth application is currently displayed on the console, as indicated by the selection indicator on the left. |
| Clicking on any of the other applications will activate the console for that application, and show its console output in the <em>Console</em> view. |
| Clearing the console of applications that have terminated can free a lot of memory for other uses, if the applications produced a lot of console output.</p> |
| </div> |
| <div class="paragraph"> |
| <p> |
| Note that instead of clearing the console after a lot of output has been generated, it is often better to <a href="#performance-reduce-console-output">prevent</a> that much output from being created in the first place.</p> |
| </div> |
| <div class="paragraph"> |
| <p> |
| |
| |
| |
| </p> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="performance-reduce-console-output">Reducing console output</h3> |
| <div class="paragraph"> |
| <p>Console output is expensive. |
| Not only because of the amount of memory the generated console output uses, but also because the console output itself needs to be generated, and displayed on the console. |
| Reducing console output can significantly increase the performance of our tools.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Therefore, instead of <a href="#performance-clear-console">clearing the console</a>, it may be better to prevent that much output from being written to the console in the first place. |
| If your model itself generates a lot of console output, consider letting it generate less output. |
| Alternatively, if the tool you use generates a lot of console output, consider checking its options to see if you can disable certain console output.</p> |
| </div> |
| <div class="paragraph"> |
| <p> |
| |
| |
| |
| |
| All Eclipse ESCET applications have an <em>Output mode</em> option (<em>General</em> category). |
| Changing the value of this option from <em>Debug</em> to <em>Normal</em>, or from <em>Normal</em> to <em>Warning</em> may significantly reduce the amount of output that is written to the console. |
| Note however that this is mostly an all or nothing approach. |
| It is often much better to use application specific settings, or change your model, to reduce the amount of output that is generated, as it allows for more control over what output is or isn’t generated.</p> |
| </div> |
| <div class="paragraph"> |
| <p> |
| |
| |
| </p> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="performance-close-running-apps">Closing running applications</h3> |
| <div class="paragraph"> |
| <p>One of the nice features of an the Eclipse ESCET IDE is that it allows the simultaneous execution of multiple applications, as well as the simultaneous execution of a single application on many different inputs. |
| For instance, it is possible to simultaneously simulate two models using a simulator. |
| The downside is that running multiple applications at the same time, costs more memory. |
| Sometimes, if you forget to close an application, it can still consume memory, and may even still be running active computations, thus consuming processing power.</p> |
| </div> |
| <div class="sect3"> |
| <h4 id="performance-application-management-via-the-applications-view">Application management via the applications view</h4> |
| <div class="paragraph"> |
| <p>The <a href="#use-apps-view">Applications view</a> can also be used observe the <a href="#use-apps-view-status">status</a> of running applications, and to <a href="#use-apps-view-termination">terminate</a> them.</p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="performance-application-management-via-the-console-view">Application management via the console view</h4> |
| <div class="paragraph"> |
| <p>The Eclipse <em>Console</em> <a href="#use-terminology-view">view</a> maintains the console output for all running and finished applications. |
| To look at the applications that you executed, click the small arrow next to the <em>Display Selected Console</em> icon (<span class="image"><img src="./performance/console_pages.png" alt="console pages"></span>) of the <em>Console</em> view’s toolbar. |
| A list of executed applications will appear, that looks something like this:</p> |
| </div> |
| <div class="imageblock"> |
| <div class="content"> |
| <img src="./performance/console_pages_list.png" alt="console pages list"> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>In this case, of the four applications that have been started, the second and fourth are still running. |
| The console for the fourth application is currently displayed, as indicated by the selection indicator on the left. |
| Clicking on any of the other applications will activate the console for that application, allowing it to be terminated, thus freeing resources for other applications.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The application that is currently active in the console can be terminated at any time, by using the <em>Terminate</em> button (<span class="image"><img src="./performance/terminate_button.png" alt="terminate button"></span>), located at the upper right corner of the console. |
| Note however that if the console does not have the focus, this button may not be visible. |
| If the button is not visible, click somewhere in the console to make the button appear. |
| If even then the button is still not available, it may still appear if you <em>Maximize</em> the console. |
| Also note that the button has no effect while the application interactively asks for input from the console. |
| However, once the console input is provided, and <kbd>ENTER</kbd> is pressed, the termination request will be processed.</p> |
| </div> |
| <div class="paragraph"> |
| <p> |
| |
| |
| |
| |
| |
| |
| |
| |
| </p> |
| </div> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="performance-tweak-perf-settings">Tweaking performance settings</h3> |
| <div class="paragraph"> |
| <p>If you run into errors related to running out of memory, you may need to tweak some settings. |
| However, even if you don’t get errors, tweaking settings can significantly improve performance.</p> |
| </div> |
| <div class="paragraph"> |
| <p>This page provides a lot of background information, to allow you to better understand the impact of the various settings. |
| If you wish, you can skip the background information, and go directly to the <a href="#performance-tweak-perf-settings-quickdirty">Quick and dirty solution</a> section.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The following information is available on this page:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="#performance-tweak-perf-settings-quickdirty">Quick and dirty solution</a></p> |
| </li> |
| <li> |
| <p><a href="#performance-tweak-perf-settings-managed-gc">Managed memory and garbage collection</a></p> |
| </li> |
| <li> |
| <p><a href="#performance-tweak-perf-settings-types">Different types of memory</a></p> |
| </li> |
| <li> |
| <p><a href="#performance-tweak-perf-settings-benefits">Benefits of increasing the available memory</a></p> |
| </li> |
| <li> |
| <p><a href="#performance-tweak-perf-settings-available">Available settings</a></p> |
| </li> |
| <li> |
| <p><a href="#performance-tweak-perf-settings-change">Changing memory settings</a></p> |
| </li> |
| <li> |
| <p><a href="#performance-tweak-perf-settings-practical">Practical hints to solve performance and memory problems</a></p> |
| </li> |
| <li> |
| <p><a href="#performance-tweak-perf-settings-heapstatus">Monitoring Eclipse heap status</a></p> |
| </li> |
| <li> |
| <p><a href="#performance-tweak-perf-settings-visualvm">Monitoring with VisualVM</a></p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p> |
| |
| |
| |
| </p> |
| </div> |
| <div class="sect3"> |
| <h4 id="performance-tweak-perf-settings-quickdirty">Quick and dirty solution</h4> |
| <div class="paragraph"> |
| <p>This section explains a 'quick and dirty' solution that gives Eclipse more memory, resolving the most common performance problems and out-of-memory errors.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Find the <code>eclipse.ini</code> file. |
| By default, it is located in your Eclipse ESCET installation directory, except for macOS, where instead it is in the <code>Eclipse.app/Contents/MacOS</code> directory inside the Eclipse ESCET installation directory. |
| Modify the last line (usually <code>-Xmx4g</code>). |
| Replace it by the following to change the maximum available memory from 4 <a href="https://en.wikipedia.org/wiki/Gibibyte">GiB</a> to 8 GiB:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlight"><code>-Xmx8g</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Restart the Eclipse ESCET IDE or command line script to apply the new settings. |
| If the instructions given here don’t fix your problem, or if the IDE or script will no longer start after you changed these settings, you should read the remainder of this page.</p> |
| </div> |
| <div class="paragraph"> |
| <p> |
| |
| |
| |
| </p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="performance-tweak-perf-settings-managed-gc">Managed memory and garbage collection</h4> |
| <div class="paragraph"> |
| <p>Before going into the actual settings, this section provides a little background on managed memory and garbage collection, to make it easier to understand the following sections. |
| The information here is highly simplified, in order not to complicate matters too much.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The Eclipse ESCET IDE and command line scripts run on <a href="https://en.wikipedia.org/wiki/Java_%28programming_language%29">Java</a>, a computer programming language. |
| The <em>Java Virtual Machine</em> (JVM) manages all memory used by Eclipse, as well as the Eclipse ESCET tools. |
| Not all settings may apply, as different versions of the JVM often change/tweak their garbage collector, settings, defaults, etc. |
| As such, the information on this page should be used to guide you, but may not be completely accurate.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The JVM keeps track of all data that is maintained by the Eclipse ESCET tools, and releases (frees) the memory once it is no longer needed, so that it can be used to store other data. |
| The JVM frees memory by means of a process called <a href="https://en.wikipedia.org/wiki/Garbage_collection_%28computer_science%29">garbage collection</a> (GC). |
| Garbage collection is a complex process, but generally it consists of locking the memory to avoid modification during garbage collection, finding the data that is no longer used (mark the garbage), and then freeing the memory associated with that data (sweep the marked garbage).</p> |
| </div> |
| <div class="paragraph"> |
| <p></p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="performance-tweak-perf-settings-types">Different types of memory</h4> |
| <div class="paragraph"> |
| <p>In order to understand the memory related settings, some understanding of Java’s memory architecture is essential. |
| The following figure provides an overview of Java’s memory architecture, and the different types of memory that are used:</p> |
| </div> |
| <div class="imageblock"> |
| <div class="content"> |
| <img src="./performance/java_memory.png" alt="java memory"> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p> |
| |
| The operating system (OS) has memory available, either as physical <a href="https://en.wikipedia.org/wiki/Random-access_memory">RAM</a>, or as <a href="https://en.wikipedia.org/wiki/Virtual_memory">virtual memory</a>. |
| When Java is executed, the Java program (<code>java</code> executable on Linux and macOS, <code>java.exe</code> on Windows), becomes one of the running <a href="https://en.wikipedia.org/wiki/Process_%28computing%29">processes</a>. |
| The process uses a part of the operating system’s memory to store its data. |
| This memory is called the <em>Java process heap</em>. |
| The <em>Java process heap</em> is divided into two parts, the <em>Java object heap</em> and <em>'Everything else'</em>. |
| The <em>Java object heap</em> contains all data actually used by the running Java program, which in our case is the Eclipse ESCET IDE and/or Eclipse ESCET command line scripts. |
| The <em>'Everything else'</em> part contains various data, mostly used by the JVM internally.</p> |
| </div> |
| <div class="paragraph"> |
| <p> |
| |
| |
| |
| |
| |
| |
| |
| |
| Java uses a generational garbage collector. |
| New data, called <em>objects</em> in Java, are created in the <em>young generation</em>, or more specifically, in its <em>allocation space</em> (also called <em>eden space</em>). |
| When the young generation becomes full, the garbage collector will remove all garbage (no longer used data) using a <em>minor collection</em>, which removes garbage from the young generation. |
| The garbage collector uses the survivor spaces to store the surviving objects. |
| Objects that survive a few minor collections are moved to the <em>old generation</em>, which stores the longer living objects, as well as the larger objects that don’t fit in the young generation, which is usually much smaller than the old generation. |
| When the old generation becomes full, the garbage collector performs a <em>major collection</em> removing garbage from the entire Java object heap, which is much more work, and thus much more costly than a minor collection.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The <em>'Everything else'</em> part of the Java process heap contains various data used internally by the JVM. |
| This includes the <em>'Metaspace'</em> with all the Java code of Eclipse and our own plugins, the values of constants, etc. |
| It also includes the <em>native code</em>, the highly optimized code generated for the specific <a href="https://en.wikipedia.org/wiki/Computer_architecture">architecture</a> of your machine, that can actually be executed on your processor. |
| Furthermore, it includes the <a href="https://en.wikipedia.org/wiki/Stack-based_memory_allocation">stacks</a> of all the <a href="https://en.wikipedia.org/wiki/Thread_%28computer_science%29">threads</a> that are running in parallel. |
| There is also a part that contains the data maintained by the garbage collector itself, for administrative purposes. |
| The 'Everything else' part contains various other types of data, that are irrelevant for the current discussion.</p> |
| </div> |
| <div class="paragraph"> |
| <p> |
| |
| |
| |
| </p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="performance-tweak-perf-settings-benefits">Benefits of increasing the available memory</h4> |
| <div class="paragraph"> |
| <p>If Java runs out of available memory, our applications running in Eclipse will terminate with an 'out of memory' error message. |
| In such cases, increasing the available memory will likely solve the problem. |
| However, even if you don’t run out of memory, increasing the amount of memory that is available to Java can significantly improve Java’s performance.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The garbage collector performs a minor collection when the young generation becomes 'full'. |
| Here, 'full' doesn’t necessarily mean 100%, as Java may e.g. try to keep the heap about 40% to 70% filled. |
| Increasing the size of the young generation makes it possible to allocate more new objects before the young generation becomes 'full'. |
| During garbage collection, program execution may become halted, to ensure that memory doesn’t change during the collection process. |
| The longer one can go without garbage collection, the less halting, and thus the greater the performance of the program.</p> |
| </div> |
| <div class="paragraph"> |
| <p> |
| |
| If an application uses a lot of data that lives for longer periods of time, the old generation may become mostly filled with data. |
| It then becomes harder and harder for the garbage collector to move objects from the young generation to the old generation. |
| This may be caused by <a href="https://en.wikipedia.org/wiki/Fragmentation_%28computing%29">fragmentation</a>, due to some objects from the old generation being removed by the garbage collector. |
| In such cases, if the <em>gaps</em> are too small to hold the new objects, the old generation may need to be <em>compacted</em>, a form of <a href="https://en.wikipedia.org/wiki/Defragmentation">defragmentation</a>. |
| After compaction, the single larger gap hopefully has more than enough free space to contain the new objects. |
| The compaction process is expensive, as a lot of objects need to moved. |
| If the situation gets really bad, Java may need to spend more time performing expensive garbage collection operations than it spends time on actually executing the program you’re running. |
| By increasing the size of the old generation to more than the application needs, a lot more free space is available, reducing the need for frequent compaction, thus significantly increasing the performance of the application.</p> |
| </div> |
| <div class="paragraph"> |
| <p>These are just some of the reasons why increasing the amount of available memory can improve program execution times, even though enough memory was already available to complete the given task. |
| In general, the more memory Java has, the better it performs.</p> |
| </div> |
| <div class="paragraph"> |
| <p> |
| |
| |
| </p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="performance-tweak-perf-settings-available">Available settings</h4> |
| <div class="paragraph"> |
| <p>The JVM has <a href="https://www.oracle.com/java/technologies/javase/vmoptions-jsp.html">way too many options</a> to list here, but the settings listed in this section are of particular practical relevance. |
| Most of the settings affect memory sizes. |
| Each setting is described using a name, a command line syntax (between parentheses), and a description. |
| The command line syntax is used to specify the setting, as explained in the <a href="#performance-tweak-perf-settings-change">Changing memory settings</a> section.</p> |
| </div> |
| <div class="paragraph"> |
| <p></p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>Initial Java object heap size (<code>-Xms<size></code>)</p> |
| <div class="paragraph"> |
| <p>The size of the Java object heap when Java starts. |
| Java will increase and/or decrease the size of the Java object heap as needed.</p> |
| </div> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p></p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>Maximum Java object heap size (<code>-Xmx<size></code>)</p> |
| <div class="paragraph"> |
| <p>The maximum size of the Java object heap. |
| Java will increase the size of the Java object heap as needed, but never to more than the amount indicated by this setting.</p> |
| </div> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p></p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>Minimum percentage of free heap space (<code>-XX:MinHeapFreeRatio=<n></code>)</p> |
| <div class="paragraph"> |
| <p>Java will increase the size of the Java object heap as needed. |
| Frequent heap resizing is costly. |
| To prevent frequent resizing, the JVM allocates more space than it really needs. |
| This way, a lot of new objects can be allocated before running out of space, which requires the heap to be increased again.</p> |
| </div> |
| <div class="paragraph"> |
| <p>This setting indicates the desired minimum percentage of free heap space after each garbage collection operation. |
| This is a desired percentage only, and if it conflicts with other settings, it is ignored. |
| For instance, if this setting is set to 40%, but 80% of the maximum heap size is in use, only 20% free space may be allocated.</p> |
| </div> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p></p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>Maximum percentage of free heap space (<code>-XX:MaxHeapFreeRatio=<n></code>)</p> |
| <div class="paragraph"> |
| <p>Java will decrease the size of the Java object heap if possible, to ensure that Java doesn’t keep claiming memory that it no longer needs. |
| Frequent heap resizing is costly. |
| To prevent frequent resizing, the JVM allocates more space than it really needs. |
| This way, a lot of new objects can be allocated before running out of space, which requires the heap to be increased again.</p> |
| </div> |
| <div class="paragraph"> |
| <p>This setting indicates the desired maximum percentage of free heap space after each garbage collection operation.</p> |
| </div> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p></p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>Ratio of young/old generation sizes (<code>-XX:NewRatio=<n></code>)</p> |
| <div class="paragraph"> |
| <p>The ratio (1:n) of the young generation size to the old generation size. |
| That is, with a ratio of 1:8, the old generation is 8 times as large as the young generation. |
| In the command line syntax, the <code>8</code> is specified.</p> |
| </div> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p></p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>Ratio of allocation/survivor space sizes (<code>-XX:SurvivorRatio=<n></code>)</p> |
| <div class="paragraph"> |
| <p>The ratio (1:n) of the survivor spaces size to the allocation space size. |
| That is, with a ratio of 1:8, the allocation space is 8 times as large as the survivor space. |
| In the command line syntax, the <code>8</code> is specified.</p> |
| </div> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p></p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>Use garbage collector overhead limit (<code>-XX:+UseGCOverheadLimit</code>)</p> |
| <div class="paragraph"> |
| <p>By default, the JVM uses a policy that limits the proportion of the VM’s time that is spent on the garbage collector. |
| If the limit is exceeded, the garbage collector has trouble doing its work (usually due to too little free memory), and performance is impacted so badly, that executed is practically halted. |
| Instead of continuing, the JVM will issue an 'out of memory' error.</p> |
| </div> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p></p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>Maximum code cache size (<code>-XX:ReservedCodeCacheSize=<size></code>)</p> |
| <div class="paragraph"> |
| <p>The maximum size of the code cache for native code.</p> |
| </div> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p></p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>Compile threshold (<code>-XX:CompileThreshold=<n></code>)</p> |
| <div class="paragraph"> |
| <p>By default, the JVM runs in mixed mode, which means that some code is interpreted, while other code is compiled to native code, which runs much faster. |
| Since compilation takes time as well, compilation is only performed for often used code.</p> |
| </div> |
| <div class="paragraph"> |
| <p>This setting indicates the number of method (a peace of Java code) invocations/branches before a method is compiled for improved performance.</p> |
| </div> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p></p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>Thread stack size (<code>-Xss<size></code>)</p> |
| <div class="paragraph"> |
| <p>The size of the stack of each thread.</p> |
| </div> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>The <code><size></code> part of the command line syntax is to be replaced by an actual size, in bytes. |
| The size can be postfixed with a <code>k</code> or <code>K</code> for <a href="https://en.wikipedia.org/wiki/Kibibyte">kibibytes</a>, an <code>m</code> or <code>M</code> for <a href="https://en.wikipedia.org/wiki/Mebibyte">mebibytes</a>, or a <code>g</code> or <code>G</code> for <a href="https://en.wikipedia.org/wiki/Gibibyte">gibibytes</a>. |
| For instance, <code>32k</code> is 32 kibibytes, which is equal to <code>32768</code>, which is 32,768 bytes.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The <code><n></code> part of the command line syntax is to be replaced by an integer number. |
| The values that are allowed are option specific.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The <code>+</code> part of the command line syntax indicates that the corresponding feature is to be enabled. |
| Replace the <code>+</code> by a <code>-</code> to disable the feature instead of enabling it.</p> |
| </div> |
| <div class="paragraph"> |
| <p> |
| |
| |
| |
| </p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="performance-tweak-perf-settings-change">Changing memory settings</h4> |
| <div class="paragraph"> |
| <p>There are several ways to supply the command line arguments for the settings to Java. |
| The easiest way to do it, when using Eclipse, is to modify the <code>eclipse.ini</code> file. |
| By default, it is located in your Eclipse ESCET installation directory, except for macOS, where instead it is in the <code>Eclipse.app/Contents/MacOS</code> directory inside the Eclipse ESCET installation directory.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Each of the settings you want to change should be added to the <code>eclipse.ini</code> text file, in the command line syntax. |
| Each setting must be put on a line <em>by itself</em>. |
| Furthermore, all these JVM settings must be put <em>after</em> the line that contains <code>-vmargs</code>. |
| Settings on lines before the <code>-vmargs</code> line are the settings for the launcher that starts Eclipse, rather than to the JVM.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Note that the default <code>eclipse.ini</code> file supplied with Eclipse may already contain some of the settings. |
| If so, don’t add the setting again. |
| Instead, change the value of the existing setting. |
| The settings that are present by default, as well as their values, may change from release to release.</p> |
| </div> |
| <div class="paragraph"> |
| <p>After modifying <code>eclipse.ini</code>, restart the Eclipse ESCET IDE or command line script for the changes to take effect.</p> |
| </div> |
| <div class="paragraph"> |
| <p> |
| |
| |
| |
| </p> |
| </div> |
| <div class="sect4"> |
| <h5 id="performance-miscellaneous-troubleshooting">Miscellaneous troubleshooting</h5> |
| <div class="paragraph"> |
| <p>If the <code>ECLIPSE_HOME</code> environment variable is defined, that directory is used instead of the default directory, to look for <code>eclipse.ini</code>. |
| However, most users should not be affected by this.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Using the <code>-vmargs</code> command line option replaces the similar settings from the <code>eclipse.ini</code> file. |
| For most users, this will not be applicable. |
| If <code>--launcher.appendVmargs</code> is specified either in the <code>eclipse.ini</code> file, or on the command line, the <code>-vmargs</code> settings of the command line are added to the <code>eclipse.ini</code> file <code>-vmargs</code> instead of replacing them.</p> |
| </div> |
| <div class="paragraph"> |
| <p> |
| </p> |
| </div> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="performance-tweak-perf-settings-practical">Practical hints to solve performance and memory problems</h4> |
| <div class="paragraph"> |
| <p> |
| In general, giving Java extra memory only makes it perform better. |
| As such, increasing the maximum Java object heap size (<code>-Xmx</code>), is generally a good idea, if you have enough free memory.</p> |
| </div> |
| <div class="paragraph"> |
| <p> |
| If you actually run out of memory, Java will emit a <code>java.lang.OutOfMemoryError</code>, with a message to indicate the type of memory that was insufficient. |
| Below some common out of memory error message are listed, with possible solutions:</p> |
| </div> |
| <div class="paragraph"> |
| <p> |
| </p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><code>java.lang.OutOfMemoryError: Java heap space</code></p> |
| <div class="paragraph"> |
| <p>The Java object heap needs more space. |
| Increase the maximum Java object heap size (<code>-Xmx</code> setting).</p> |
| </div> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p> |
| |
| </p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><code>java.lang.OutOfMemoryError: GC overhead limit exceeded</code></p> |
| <div class="paragraph"> |
| <p>The 'use garbage collector overhead limit' feature is enabled, and the garbage collector overhead limit was exceeded. |
| The best way to solve this, is to make sure the limit is not exceeded, by giving Java more memory, and thus making it easier for the garbage collector to do its work. |
| Increase the maximum Java object heap size (<code>-Xmx</code> setting).</p> |
| </div> |
| <div class="paragraph"> |
| <p>Alternatively, disable the 'use garbage collector overhead limit' feature (<code>-XX:-UseGCOverheadLimit</code> setting, note the <code>-</code> instead of the <code>+</code>). |
| However, this doesn’t solve the underlying problem, as the limit will still be exceeded. |
| Java will try to continue, and will either fail, or be very slow.</p> |
| </div> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p> |
| </p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><code>warning: CodeCache is full. |
| Compiler has been disabled.</code></p> |
| <div class="paragraph"> |
| <p>This message is not a <code>java.lang.OutOfMemoryError</code>, but may still be printed to the console. |
| It is usually followed by <code>warning: Try increasing the code cache size using -XX:ReservedCodeCacheSize=</code>. |
| The warnings indicate that the code cache for native code is full. |
| They already indicate the solution: increase the maximum size of the code cache (<code>-XX:ReservedCodeCacheSize</code> setting).</p> |
| </div> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p> |
| |
| </p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><code>java.lang.OutOfMemoryError: unable to create new native thread</code></p> |
| <div class="paragraph"> |
| <p>A new thread could not be created. |
| The best way to solve this problem is to decrease the maximum Java object heap size (<code>-Xmx</code> setting), to make room for the 'Everything else' part of the Java memory, including the stack of the new thread.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Alternatively, decrease the size of stacks on all threads (<code>-Xss</code> setting). |
| However, decreasing the thread stack size may cause more <code>java.lang.StackOverflowError</code> errors, and is thus not recommended.</p> |
| </div> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p> |
| |
| </p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="performance-tweak-perf-settings-heapstatus">Monitoring Eclipse heap status</h4> |
| <div class="paragraph"> |
| <p>In Eclipse, it is possible to observe the amount of Java object heap space that is being used. |
| In Eclipse, open the <em>Preferences</em> dialog, via <span class="menuseq"><b class="menu">Window</b> <i class="fa fa-angle-right caret"></i> <b class="menuitem">Preferences</b></span>. |
| Select the <em>General</em> category on the left, if not already selected. |
| On the right, make sure the <b class="menuref">Show heap status</b> option is checked, and click <b class="button">OK</b> to close the dialog.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The heap status should now be displayed in the bottom right corner of the Eclipse window:</p> |
| </div> |
| <div class="imageblock"> |
| <div class="content"> |
| <img src="./performance/eclipse_heap_status1.png" alt="eclipse heap status1"> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>This example shows that the Java object heap (not the Java process heap) is currently 147 MB in size. |
| Of that 147 MB, 62 MB are in use. |
| The entire graph (the gray background) indicates the total heap size (147 MB), while the dark gray part indicates the used part of the heap (62 MB).</p> |
| </div> |
| <div class="paragraph"> |
| <p>Clicking on the garbage can icon, to the right of the heap status, will trigger a major collection cycle of the garbage collector.</p> |
| </div> |
| <div class="paragraph"> |
| <p>By right clicking on the heap status, and enabling the <em>Show Max Heap</em> option, the heap status shows more information:</p> |
| </div> |
| <div class="imageblock"> |
| <div class="content"> |
| <img src="./performance/eclipse_heap_status2.png" alt="eclipse heap status2"> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>The text still shows the amount of used heap memory (74 MB) out of the total size of the current heap (147 MB). |
| The scale of the background colors however, is different. |
| The entire graph (the light gray background) now indicates the maximum heap size. |
| The orange part indicates the current heap size. |
| The dark gray part still indicates the part of the heap that is in use. |
| If the used part of the memory gets past the red bar, it will become red as well, to indicate that you are approaching the maximum allowed Java object heap size, and may need to increase it (<code>-Xmx</code> setting).</p> |
| </div> |
| <div class="paragraph"> |
| <p>Hover over the heap status to get the same information in a tooltip.</p> |
| </div> |
| <div class="paragraph"> |
| <p> |
| |
| </p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="performance-tweak-perf-settings-visualvm">Monitoring with VisualVM</h4> |
| <div class="paragraph"> |
| <p>VisualVM is a tool to monitor, troubleshoot, and profile running Java applications. |
| It can be downloaded from the <a href="https://visualvm.github.io/">VisualVM website</a>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Download the 'Standalone' version, and extract the archive somewhere on your system.</p> |
| </div> |
| <div class="paragraph"> |
| <p>On Windows, start <code>visualvm.exe</code> from the <code>bin</code> directory by double clicking on it. |
| On Linux, start <code>visualvm</code> from the <code>bin</code> directory. |
| On macOS, use the <code>.dmg</code> file as you would any other such file.</p> |
| </div> |
| <div class="paragraph"> |
| <p>After you start VisualVM for the first time, you may see some dialogs. |
| Just go through the steps until you get to the actual application.</p> |
| </div> |
| <div class="paragraph"> |
| <p>In VisualVM, you’ll see the currently running Java applications, for the local system:</p> |
| </div> |
| <div class="imageblock"> |
| <div class="content"> |
| <img src="./performance/visualvm_pid.png" alt="visualvm pid"> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Sometimes VisualVM can identify the Java applications, sometimes it can’t. |
| This may also depend on you operating system, and the version of VisualVM. |
| Find the application you want to know more about and double click it. |
| A new tab opens on the right. |
| The new tab has various tabs of its own:</p> |
| </div> |
| <div class="paragraph"> |
| <p> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| </p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><em>Overview</em>: provides various basic information, including the location of the JVM, its command line settings, etc.</p> |
| </li> |
| <li> |
| <p><em>Monitor</em>: provides a quick overview of among others the CPU usage, GC activity, Java object heap usage, number of loaded classes, and the number of running threads, over time.</p> |
| </li> |
| <li> |
| <p><em>Threads</em>: provides an overview of the running threads, and their status, over time. |
| The <b class="button">Thread Dump</b> button can be used to dump the stack traces of all currently running threads.</p> |
| </li> |
| <li> |
| <p><em>Sampler</em> and <em>Profiler</em>: provide CPU and memory <a href="https://en.wikipedia.org/wiki/Profiling_%28computer_programming%29">profiling</a>, over time, by using sampling and instrumentation respectively.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>The <em>Monitor</em> tab can be used to determine which type of memory should be increased. |
| The <em>Sampler</em> tab can be used to profile an application, and figure out where bottlenecks are. |
| This information can be used by the developers of the application to improve the performance of the application, by removing those bottlenecks.</p> |
| </div> |
| <div class="imageblock"> |
| <div class="content"> |
| <img src="./performance/visualvm_sshot.png" alt="visualvm sshot"> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p> |
| Via <span class="menuseq"><b class="menu">Tools</b> <i class="fa fa-angle-right caret"></i> <b class="menuitem">Plugins</b></span> you can access the <em>Plugins</em> window, where you manage the plugins. |
| Various plugins are available. |
| The <em>Visual GC</em> plugin is of particular interest. |
| After installing it, restart VisualVM, or close the tabs of the JVMs you’re monitoring and open them again. |
| You’ll get an extra tab for monitored JVMs, the <em>Visual GC</em> tab. |
| This tab is somewhat similar to the <em>Monitor</em> tab, but shows more detailed information about the garbage collector, its various generations, etc.</p> |
| </div> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="developer-chapter-index">Eclipse ESCET development</h2> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p>Thanks for your interest in Eclipse Supervisory Control Engineering Toolkit (Eclipse ESCET) project.</p> |
| </div> |
| <div class="paragraph"> |
| <p>For more information about the project, see:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="https://projects.eclipse.org/projects/technology.escet">Eclipse ESCET project home</a></p> |
| </li> |
| <li> |
| <p><a href="https://eclipse.org/escet">Eclipse ESCET website</a></p> |
| </li> |
| </ul> |
| </div> |
| <div id="develop-dev-list" class="paragraph"> |
| <p>Contact the project developers via the project’s 'dev' list.</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="https://accounts.eclipse.org/mailing-list/escet-dev">Eclipse ESCET 'dev' list</a></p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>For other means to interact with the Eclipse ESCET community and its developers, see the <a href="#contact-chapter-index">contact</a> section.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Further topics:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="#developer-development-process-chapter-index">Development process</a></p> |
| </li> |
| <li> |
| <p><a href="#developer-contributing-chapter-index">Contributing</a></p> |
| </li> |
| <li> |
| <p><a href="#developer-issue-tracking-chapter-index">Issue tracking</a></p> |
| </li> |
| <li> |
| <p><a href="#developer-dev-env-setup-chapter-index">Development environment setup</a></p> |
| </li> |
| <li> |
| <p><a href="#developer-git-repo-chapter-index">Git repository</a></p> |
| </li> |
| <li> |
| <p><a href="#developer-coding-standards-chapter-index">Coding standards</a></p> |
| </li> |
| <li> |
| <p><a href="#developer-building-and-testing-chapter-index">Building and testing</a></p> |
| </li> |
| <li> |
| <p><a href="#developer-release-process-chapter-index">Release process</a></p> |
| </li> |
| <li> |
| <p><a href="#developer-third-party-tools-chapter-index">Third party tools</a></p> |
| </li> |
| <li> |
| <p><a href="#developer-upgrade-instructions-chapter-index">Upgrade instructions</a></p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p></p> |
| </div> |
| <div class="sect2"> |
| <h3 id="developer-development-process-chapter-index">Development process</h3> |
| <div class="admonitionblock note"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <i class="fa icon-note" title="Note"></i> |
| </td> |
| <td class="content"> |
| If you want to contribute to the Eclipse ESCET project, please refer to the specific <a href="#developer-contributing-chapter-index">contributing</a> information. |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="paragraph"> |
| <p>The Eclipse ESCET project primarily uses GitLab for its development:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="https://gitlab.eclipse.org/eclipse/escet/escet">Eclipse ESCET GitLab</a></p> |
| </li> |
| </ul> |
| </div> |
| <div class="sect3"> |
| <h4 id="developer-discussion">Discussion</h4> |
| <div class="paragraph"> |
| <p>It is often a good idea to first discuss new ideas and features with the rest of the project developers, i.e. the project committers and the project community. |
| Discussions can take place on the project’s <a href="#developer-chapter-index">'dev' list</a>, especially for radical new ideas and new features that have not been discussed before.</p> |
| </div> |
| <div class="paragraph"> |
| <p></p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="developer-issue-tracking">Issue tracking</h4> |
| <div class="paragraph"> |
| <p>If the project committers and the community agree that it is a good idea to have the new feature, an issue should be created in the <a href="#developer-issue-tracking-chapter-index">issue tracker</a>. |
| For improvements where extensive discussion is not expected, as well as for obvious bugs, an issue can be created directly, without first discussing it on the 'dev' list. |
| The discussion can also continue in the issue itself, once the issue is created.</p> |
| </div> |
| <div class="paragraph"> |
| <p>When creating an issue, take the following into account:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>An issue must be created in the issue tracker for all development, however small. |
| This ensures we can link issues can commits to keep track of everything.</p> |
| </li> |
| <li> |
| <p>Issues are ideally kept relatively small in scope. |
| Bigger tasks can be split up into multiple issues, and follow-up issues can be created as needed. |
| This allows to separate concerns, and also to work in a more agile way, e.g.:</p> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>Issues can be addressed more quickly.</p> |
| </li> |
| <li> |
| <p>Merge requests can be reviewed more easily as they are not as big.</p> |
| </li> |
| <li> |
| <p>Merge issues are less likely to occur, as branches have a shorter lifespan.</p> |
| </li> |
| </ul> |
| </div> |
| </li> |
| <li> |
| <p>If a new feature is split up into multiple issues, these can be related together using an epic. |
| In such cases, add the issues to the epic to track the progress of the new feature using the epic.</p> |
| </li> |
| <li> |
| <p>Attach the appropriate <a href="https://gitlab.eclipse.org/eclipse/escet/escet/-/labels">predefined labels</a> to the issue:</p> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>Either something is broken ('Bug' label) or we want something more, different, better, etc ('Enhancement' label).</p> |
| </li> |
| <li> |
| <p>Add all relevant component labels (e.g. 'Chi' and 'CIF' labels). |
| Typically at least one such label should be present, but it is also possible to add multiple labels if the issue involves multiple components. |
| The components correspond to the directories in the root of our <a href="#developer-git-repo-chapter-index">Git repository</a>.</p> |
| </li> |
| <li> |
| <p>The Eclipse ESCET project committers can add the 'Help Wanted' label to an issue to indicate that they don’t have the time to work on the issue, and that help from the community is wanted.</p> |
| </li> |
| </ul> |
| </div> |
| </li> |
| <li> |
| <p>Link the issue to any other issues, as relevant, e.g. if an issue requires that another issue is addressed first.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p> |
| </p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="developer-releases-and-milestones">Releases and milestones</h4> |
| <div class="paragraph"> |
| <p>For every software version a GitLab milestone is created, to track its scope and progress. |
| First the scope is discussed and agreed upon. |
| Then, a GitLab milestone is created, the relevant issues are created if not yet present, and the issues are associated with the milestone. |
| The issues can then be picked up to be addressed.</p> |
| </div> |
| <div class="paragraph"> |
| <p>A single GitLab milestone is used per software version. |
| Each software version has one or more milestone releases, followed by one or more release candidates, and is completed by a final release.</p> |
| </div> |
| <div class="paragraph"> |
| <p>See also:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="https://gitlab.eclipse.org/eclipse/escet/escet/-/milestones">Eclipse ESCET milestones</a></p> |
| </li> |
| </ul> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="developer-working-on-issues">Working on issues</h4> |
| <div class="paragraph"> |
| <p>The process to work on issues is as follows:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>Unassigned issues can be picked up.</p> |
| </li> |
| <li> |
| <p>Assign yourself to the issue when you are working on an issue, such that others won’t start working on it as well.</p> |
| </li> |
| <li> |
| <p>Unassign yourself if you are no longer working on an issue, don’t plan to continue, and the issue is not finished.</p> |
| </li> |
| <li> |
| <p>Don’t unassign yourself after finishing the work, just close the issue.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p> |
| </p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="developer-working-with-branches">Working with branches</h4> |
| <div class="paragraph"> |
| <p>The Eclipse ESCET project roughly follows the <a href="https://nvie.com/posts/a-successful-git-branching-model/">GitFlow branching model</a>. |
| The <code>master</code> branch is thus for released content only, and the current development status is captured in the <code>develop</code> branch.</p> |
| </div> |
| <div class="paragraph"> |
| <p>If possible, we approach the somewhat heavy GitFlow branching model in a practical way, reducing overhead.</p> |
| </div> |
| <div class="paragraph"> |
| <p>When creating and working with branches, consider the following:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>Always work in a branch for the issue. |
| That is, never commit directly to the <code>develop</code> branch, but always use a merge request from a feature branch.</p> |
| </li> |
| <li> |
| <p>Branches for work on issues (feature branches) should be relatively short lived. |
| This makes it easier to keep the overview, allows for more agile development, and reduces the chance for merge conflicts.</p> |
| </li> |
| <li> |
| <p>The GitFlow branching model allows for sub teams that share work but don’t push that to 'origin' (yet). |
| It also allows feature branches that live only locally on a developer’s PC and not on 'origin'. |
| To be transparent, Eclipse Foundation open source projects don’t do this. |
| We push to our GitLab server regularly, to ensure that the community can see what the project is working on.</p> |
| </li> |
| <li> |
| <p>We have no strict branch naming rules. |
| You can Let GitLab create the branch for the issue. |
| For an issue with number #2 named 'Test', it will create a branch named <code>2-test</code>. |
| This includes the issue number, which makes it easy to relate a branch to an issue, without having to look inside the branch for commits (if there even are any). |
| It also includes the issue name, which is convenient as it indicates what the branch is about, without having to look up the issue.</p> |
| </li> |
| <li> |
| <p>There are many ways to create a branch. |
| One way is to create it from the GitLab issue. |
| On the web page for a GitLab issue, there is a <em>Create merge request</em> button. |
| Select the arrow to the right of it to show more options. |
| Select <em>Create branch</em>. |
| Adapt the <em>Branch name</em> and <em>Source</em> as needed. |
| Typically the defaults suffice. |
| Click the <em>Create branch</em> button to create the branch.</p> |
| </li> |
| <li> |
| <p>We prefer not to create a draft merge request with the creation of the branch, as then commits in the branch lead to commits on the merge requests, which lead to notification emails.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p></p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="developer-commits">Commits</h4> |
| <div class="paragraph"> |
| <p>As is standard for Git commits, the first line of the commit message must be a short summary, and must not exceed 72 characters.</p> |
| </div> |
| <div class="paragraph"> |
| <p>For the Eclipse ESCET project, this line must start with the issue number, to allow GitLab to link commits to issues. |
| For instance: <code>#1 commit summary</code>. |
| In case a commit relates to multiple issues, list each of them, e.g. <code>#1 #2 commit summary</code>. |
| Merge commits are exempt from this rule.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Furthermore, all commits must adhere to the requirements as defined by the Eclipse Foundation:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="https://www.eclipse.org/projects/handbook/#resources-commit">Git Commit Records</a> (Eclipse Foundation Project Handbook)</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>If you are not an Eclipse ESCET project committer, with write access to our Git repository, see the information on <a href="#developer-contributing-chapter-index">contributing</a> to the Eclipse ESCET project.</p> |
| </div> |
| <div class="paragraph"> |
| <p></p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="developer-merge-requests">Merge requests</h4> |
| <div class="paragraph"> |
| <p>Once the work on an issue is done and pushed to a branch, it must be reviewed before it is merged back. |
| Reviews are done via merge requests. |
| The process is as follows:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>Create a merge request for merging the branch. |
| You can create a merge request from the Eclipse ESCET Gitlab <a href="https://gitlab.eclipse.org/eclipse/escet/escet/-/branches">Branches page</a>. |
| Select the <em>Merge request</em> button next to the branch to be merged.</p> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>Typically a branch is created from and merged back to the <code>develop</code> branch, but this can be changed if needed.</p> |
| </li> |
| <li> |
| <p>Start the merge request title with the related issue number(s), to allow easier tracking of merge requests back to issues.</p> |
| </li> |
| <li> |
| <p>If you include <code>Closes #nnn</code> in the description of the merge request, with <code>nnn</code> an issue number, that issue will automatically be closed once the merge request is merged. |
| Use <code>Addresses #nnn</code> instead, if the merge request addresses part of the issue, but work remains, to prevent the issue from being closed. |
| Always include either of them to ensure the merge request is properly linked to the issues it addresses. |
| Include multiple of them if appropriate.</p> |
| </li> |
| <li> |
| <p>It is not mandatory to select <em>assignees</em>, <em>reviewers</em>, etc.</p> |
| </li> |
| </ul> |
| </div> |
| </li> |
| <li> |
| <p>The merge request is reviewed by the Eclipse ESCET project committers.</p> |
| </li> |
| <li> |
| <p>Improvements are made as necessary, reviewed again, etc, until the branch is considered to be ready to merge.</p> |
| </li> |
| <li> |
| <p>The branch is merged and removed.</p> |
| </li> |
| <li> |
| <p>If the branch fully addressed the associated issue or issues, it/they should be closed.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>If you are not an Eclipse ESCET project committer, with write access to our Git repository, see the information on <a href="#developer-contributing-chapter-index">contributing</a> to the Eclipse ESCET project.</p> |
| </div> |
| <div class="paragraph"> |
| <p> |
| </p> |
| </div> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="developer-contributing-chapter-index">Contributing</h3> |
| <div class="paragraph"> |
| <p>Thanks for your interest in Eclipse Supervisory Control Engineering Toolkit (Eclipse ESCET) project.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The following topics are discussed:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="#developer-contributing-contribute">How to contribute to Eclipse ESCET</a></p> |
| </li> |
| <li> |
| <p><a href="#developer-contributing-become-committer">How to become a committer</a></p> |
| </li> |
| </ul> |
| </div> |
| <div class="sect3"> |
| <h4 id="developer-contributing-contribute">How to contribute to Eclipse ESCET</h4> |
| <div class="paragraph"> |
| <p>It is often a good idea to first discuss your contribution with the project’s community and committers, before creating the actual code (e.g. patches), documentation, etc of your contribution. |
| Discussions can take place via an <a href="#developer-issue-tracking-chapter-index">issue</a> in the issue tracker, or on the project’s <a href="#developer-chapter-index">'dev' list</a>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>To contribute your actual contribution, e.g. code, documentation, examples, or anything else to the project, please first create an issue in the <a href="#developer-issue-tracking-chapter-index">issue tracker</a>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The easiest way to contribute the actual contribution, is to use GitLab:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>Ensure you’re logged in to the Eclipse Foundation GitLab:</p> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="https://gitlab.eclipse.org">Eclipse Foundation GitLab</a></p> |
| </li> |
| </ul> |
| </div> |
| </li> |
| <li> |
| <p>Clone the official Eclipse ESCET Git repository. |
| You can click the 'Fork' button at the top right of the page. |
| This creates a fork of the official repository under your own account.</p> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="https://gitlab.eclipse.org/eclipse/escet/escet">Official Eclipse ESCET Git repository</a></p> |
| </li> |
| </ul> |
| </div> |
| </li> |
| <li> |
| <p>Make your changes in the forked repository under your own account.</p> |
| </li> |
| <li> |
| <p>Create a merge request of those changes from the forked repository under your own account. |
| As the target, select the official Eclipse ESCET repository from which you forked earlier. |
| Typically, you should target the <code>develop</code> branch.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p></p> |
| </div> |
| <div class="paragraph"> |
| <p>Before your contribution can be accepted by the project team, you must electronically sign the Eclipse Contributor Agreement (ECA):</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="https://www.eclipse.org/legal/ECA.php">Eclipse Contributor Agreement (ECA)</a></p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>The non-committer that authored the commit, must have an Eclipse Foundation Account and must have a signed Eclipse Contributor Agreement (ECA) on file. |
| The name and email address of the commits must match the corresponding information on the Eclipse Foundation Account.</p> |
| </div> |
| <div class="paragraph"> |
| <p>For more information, including the specific format of commit messages, please see the Eclipse Foundation Project Handbook:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="https://www.eclipse.org/projects/handbook">Eclipse Foundation Project Handbook</a></p> |
| </li> |
| <li> |
| <p><a href="https://www.eclipse.org/projects/handbook/#resources-commit">Git Commit Records</a></p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>Always start a commit message with the issue number, e.g. <code>#1 Some commit message</code>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>A contribution by a non-committer will be reviewed by the project committers. |
| This includes adherence to the project’s <a href="#developer-coding-standards-chapter-index">coding standards</a>. |
| Discussions regarding the contribution will take place in the associated issue and/or merge request. |
| If the committers agree with the contribution, they will commit the contribution into the project’s Git repository.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Remember that contributions are always welcome, and contributions don’t have to be perfect. |
| The project’s developers can help to improve your contribution. |
| If you need any help, just ask the project’s developers using the issue or the project’s <a href="#develop-dev-list">'dev' list</a>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>See for more information our <a href="#developer-development-process-chapter-index">development process</a>.</p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="developer-contributing-become-committer">How to become a committer</h4> |
| <div class="paragraph"> |
| <p>The Eclipse Foundation operates on the principle of meritocracy. |
| Anybody can contribute to Eclipse ESCET as a contributor. |
| But the more that somebody contributes, the more responsibility they will earn. |
| To earn committer status, a contributor must demonstrate that they understand their responsibilities, both as an Eclipse Foundation committer in general and as a committer for the project in particular.</p> |
| </div> |
| <div class="paragraph"> |
| <p>A contributor can be elected to become a committer. |
| This starts with a nomination by an existing committer. |
| For further details on the process, see the <a href="https://www.eclipse.org/projects/handbook/#elections-committer">Committer Elections</a> section of the Eclipse Foundation Project Handbook.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Each project can define the criteria that are considered for nominations. |
| The criteria for the Eclipse ESCET project are as follows:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>Demonstrate a good grasp of the <a href="https://www.eclipse.org/projects/dev_process/">Eclipse Foundation Development Process</a>, including the <a href="https://www.eclipse.org/org/documents/Eclipse_IP_Policy.pdf">Eclipse Foundation Intellectual Property Policy</a>.</p> |
| </li> |
| <li> |
| <p>Provide several high-quality non-trivial contributions that demonstrate a good grasp of the code base, its structure and the underlying concepts.</p> |
| </li> |
| <li> |
| <p>Demonstrate a good grasp of the Eclipse ESCET way of working, including use of issues, merge requests, code style, build, tests, etc.</p> |
| </li> |
| <li> |
| <p>Demonstrate the ability to work together with the current committers and the wider community, in a positive, open and transparent manner.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>The more of these criteria that have been shown the better, but it is not a requirement to show all of these to the same degree. |
| In the end it is up to the existing committers to judge whether enough merit has been demonstrated to warrant a nomination.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The Eclipse Foundation also requires that nominations are supported by public evidence that demonstrates the merit. |
| This ensures that the process of electing new committers is transparent. |
| Furthermore, nominations and elections must be open, in that anybody that shows merit should be considered equally for nominations. |
| It must definitely not be based on employment status.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Obviously, the contributor must be willing and able to become a committer, and there must be an outlook that the contributor will remain active in the future.</p> |
| </div> |
| <div class="paragraph"> |
| <p>For more information, see also the following blog posts:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="https://blog.waynebeaton.ca/posts/opensource/repository/">Barriers for Entry</a> (Wayne Beaton, Director of Open Source Projects at Eclipse Foundation)</p> |
| </li> |
| <li> |
| <p><a href="https://blog.waynebeaton.ca/posts/opensource/hired-a-committer/">Make This Person We Hired a Committer</a> (Wayne Beaton, Director of Open Source Projects at Eclipse Foundation)</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p> |
| |
| </p> |
| </div> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="developer-issue-tracking-chapter-index">Issue tracking</h3> |
| <div class="paragraph"> |
| <p>The Eclipse ESCET project uses GitLab to track ongoing development and issues:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="https://gitlab.eclipse.org/eclipse/escet/escet/-/milestones">Eclipse ESCET milestones</a></p> |
| </li> |
| <li> |
| <p><a href="https://gitlab.eclipse.org/eclipse/escet/escet/-/issues">Eclipse ESCET issues</a></p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>Be sure to search for existing issues before you create another one. |
| Remember that contributions are always welcome!</p> |
| </div> |
| <div class="paragraph"> |
| <p>To contribute code (e.g. patches), documentation, or anything else, see the <a href="#developer-contributing-chapter-index">contributing</a> section.</p> |
| </div> |
| <div class="paragraph"> |
| <p>To understand how we work with issues, see our <a href="#developer-development-process-chapter-index">development process</a>.</p> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="developer-dev-env-setup-chapter-index">Development environment setup</h3> |
| <div class="paragraph"> |
| <p>Follow these instructions to set up an Eclipse ESCET development environment.</p> |
| </div> |
| <div class="paragraph"> |
| <p> |
| </p> |
| </div> |
| <div class="paragraph"> |
| <p>Get the Eclipse Installer:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>Go to <a href="https://www.eclipse.org/" class="bare">https://www.eclipse.org/</a> in a browser.</p> |
| </li> |
| <li> |
| <p>Click on the big <b class="button">Download</b> button at the top right.</p> |
| </li> |
| <li> |
| <p>Download Eclipse Installer, 64 bit edition, using the <b class="button">Download 64 bit</b> button.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p> |
| </p> |
| </div> |
| <div class="paragraph"> |
| <p>To create a development environment for the first time:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>Start the Eclipse Installer that you downloaded.</p> |
| </li> |
| <li> |
| <p>Use the hamburger menu at the top right to switch to advanced mode.</p> |
| </li> |
| <li> |
| <p>For Windows:</p> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>When asked to keep the installer in a permanent location, choose to do so. |
| Select a directory of your choosing.</p> |
| </li> |
| <li> |
| <p>The Eclipse installer will start automatically in advanced mode, from the new permanent location.</p> |
| </li> |
| </ul> |
| </div> |
| </li> |
| <li> |
| <p>For Linux:</p> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>The Eclipse installer will restart in advanced mode.</p> |
| </li> |
| </ul> |
| </div> |
| </li> |
| <li> |
| <p>Continue with non-first time instructions for setting up a development environment.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>To create a development environment for a non-first time:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>In the first wizard window:</p> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>Select <em>Eclipse Platform</em> from the big list at the top.</p> |
| </li> |
| <li> |
| <p>Select <em>2021-06</em> for <em>Product Version</em>.</p> |
| </li> |
| <li> |
| <p>For <em>Java 11+ VM</em> select <em>JRE 11.0.2 - http://download.eclipse.org/justj/jres/11/updates/release/11.0.2</em>.</p> |
| </li> |
| <li> |
| <p>Choose whether you want a P2 bundle pool (recommended).</p> |
| </li> |
| <li> |
| <p>Click <b class="button">Next</b>.</p> |
| </li> |
| </ul> |
| </div> |
| </li> |
| <li> |
| <p>In the second wizard window:</p> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>Use the green '+' icon at the top right to add the Oomph setup.</p> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>For <em>Catalog</em>, choose <em>Eclipse Projects</em>.</p> |
| </li> |
| <li> |
| <p>For <em>Resource URIs</em>, enter <code>https://gitlab.eclipse.org/eclipse/escet/escet/-/raw/develop/org.eclipse.escet.setup</code> and make sure there are no spaces before or after the URL.</p> |
| </li> |
| <li> |
| <p>Click <b class="button">OK</b>.</p> |
| </li> |
| </ul> |
| </div> |
| </li> |
| <li> |
| <p>Check the checkbox for <em>Eclipse ESCET</em>, from the big list. |
| It is under <em>Eclipse Projects</em> / <em><User></em>.</p> |
| </li> |
| <li> |
| <p>At the bottom right, select the <em>develop</em> stream.</p> |
| </li> |
| <li> |
| <p>Click <b class="button">Next</b>.</p> |
| </li> |
| </ul> |
| </div> |
| </li> |
| <li> |
| <p>In the third wizard window:</p> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>Enable the <em>Show all variables</em> option to show all options.</p> |
| </li> |
| <li> |
| <p>Choose a <em>Root install folder</em> and <em>Installation folder name</em>. |
| The new development environment will be put at <code><root_installation_folder>/<installation_folder_name></code>.</p> |
| </li> |
| <li> |
| <p>For <em>Eclipse Foundation account full name</em> fill in your full name (first and last name) matching the full name in your Eclipse Foundation account. |
| This will be used as name for Git commits.</p> |
| </li> |
| <li> |
| <p>For <em>Eclipse Foundation account email address</em> fill in the email address associated with your Eclipse Foundation account. |
| This will be used as email for Git commits.</p> |
| </li> |
| <li> |
| <p>Click <b class="button">Next</b>.</p> |
| </li> |
| </ul> |
| </div> |
| </li> |
| <li> |
| <p>In the fourth wizard window:</p> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>Select <b class="button">Finish</b>.</p> |
| </li> |
| </ul> |
| </div> |
| </li> |
| <li> |
| <p>Wait for the setup to complete and the development environment to be launched.</p> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>If asked, accept any licenses and certificates.</p> |
| </li> |
| </ul> |
| </div> |
| </li> |
| <li> |
| <p>Press <b class="button">Finish</b> in the Eclipse Installer to close the Eclipse Installer.</p> |
| </li> |
| <li> |
| <p>In the new development environment, observe Oomph executing the startup tasks (such as Git clone, importing projects, etc). |
| If this is not automatically shown, click the rotating arrows icon in the status bar (bottom right) of the new development environment.</p> |
| </li> |
| <li> |
| <p>Wait for the startup tasks to finish successfully.</p> |
| </li> |
| <li> |
| <p>NOTE: If you don’t open the Oomph dialog, the status bar icon icon may disappear when the tasks are successfully completed.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>If you have any issues during setting up the development environment, consider the following:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>Make sure to use a recent version of the Eclipse Installer. |
| These versions include a recent JRE, which includes up-to-date certificates, preventing issues when accessing https URLs.</p> |
| </li> |
| <li> |
| <p>You can set the following environment variables to force the use of IPv4, in case of any issues accessing/downloading remote files:</p> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlight"><code>_JAVA_OPTIONS=-Djava.net.preferIPv4Stack=true |
| _JPI_VM_OPTIONS=-Djava.net.preferIPv4Stack=true</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>After setting them, make sure to fully close the Eclipse Installer and then start it again, for the changes to be picked up.</p> |
| </div> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>In your new development environment, consider changing the following settings:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>For the <em>Package Explorer</em> <a href="#use-terminology-view">view</a>:</p> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>Enable the <em>Link with Editor</em> setting, using the <span class="image"><img src="./developer/link-with-editor.png" alt="link with editor"></span> icon.</p> |
| </li> |
| <li> |
| <p>Enable showing resources (files/folders) with names starting with a period. |
| Open the <em>View Menu</em> (<span class="image"><img src="./developer/view-menu.png" alt="view menu"></span>) and choose <b class="menuref">Filters…​</b>. |
| Uncheck the <code>.* resources</code> option and click <b class="button">OK</b>.</p> |
| </li> |
| </ul> |
| </div> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p></p> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="developer-git-repo-chapter-index">Git repository</h3> |
| <div class="paragraph"> |
| <p>The Eclipse ESCET project maintains the following source code repositories:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><code>https://gitlab.eclipse.org/eclipse/escet/escet.git</code></p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>These can also be accessed via a web interface:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="https://gitlab.eclipse.org/eclipse/escet/escet">Eclipse ESCET GitLab</a></p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p> |
| </p> |
| </div> |
| <div class="paragraph"> |
| <p>The software is written in the <a href="https://www.oracle.com/java/">Java</a> programming language, as a collection of <a href="https://www.eclipse.org/pde/">Eclipse plugins</a>, and using the <a href="https://www.eclipse.org/modeling/emf/">Eclipse Modeling Framework</a> (EMF).</p> |
| </div> |
| <div class="paragraph"> |
| <p>For ease of programming, the <a href="https://eclipse.org">Eclipse IDE</a> is recommended. |
| See also the section on <a href="#developer-dev-env-setup-chapter-index">setting up a development environment</a>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>To contribute code (e.g. patches), documentation, or anything else, see the <a href="#developer-contributing-chapter-index">contributing</a> section.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The way we work with our Git repository is explained as part of our <a href="#developer-development-process-chapter-index">development process</a>.</p> |
| </div> |
| <div class="sect3"> |
| <h4 id="developer-repository-structure">Repository structure</h4> |
| <div class="paragraph"> |
| <p>In the Eclipse ESCET source code repository (Git repository), three layers are distinguished:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>The top layer contains user-oriented languages for designing controllers. |
| Currently there are two modeling languages in this layer, <a href="#intro-chapter-cif">CIF</a> and <a href="#intro-chapter-chi">Chi</a>.</p> |
| <div class="paragraph"> |
| <p>The third language in the top layer is <a href="#intro-chapter-tooldef">ToolDef</a>, a cross-platform scripting language to run tests, and to automate the various tools that need to be executed while designing a controller.</p> |
| </div> |
| </li> |
| <li> |
| <p>The middle layer contains developer oriented support code. |
| It has a language of its own, named <a href="#intro-chapter-setext">SeText</a>. |
| This language implements an LALR(1) parser generator with a few twists to make it easy to use in a Java environment and to connect it to an Eclipse text editor.</p> |
| <div class="paragraph"> |
| <p>The other part of the middle layer is common functionality shared between the languages.</p> |
| </div> |
| </li> |
| <li> |
| <p>The bottom layer is mostly configuration to attach the software to the Eclipse platform, including build and release engineering.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>This document describes the structure of the top and middle layers. |
| For the bottom layer, standard Eclipse and Maven/Tycho tools are used, which are described elsewhere.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The three layers are not further distinguished in the repository. |
| Instead, different parts are stored in different sub-directories from the root.</p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="developer-language-directories">Language directories</h4> |
| <div class="paragraph"> |
| <p>Each language has its own subdirectory in the root, <code>/cif</code> and <code>/chi</code> for the <a href="#intro-chapter-cif">CIF</a> and <a href="#intro-chapter-chi">Chi</a> modeling languages, <code>/tooldef</code> for the <a href="#intro-chapter-tooldef">ToolDef</a> language, and <code>/setext</code> for the <a href="#intro-chapter-setext">SeText</a> language.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Within a language directory, a directory exists for each part of the code (often equivalent to a plugin), with the same name as the plugin. |
| The pattern of a plugin name is <code>org.eclipse.escet.<language>.<plugin-name></code> where the plugin-name in different directories has the same meaning. |
| A non-exhaustive list:</p> |
| </div> |
| <table class="tableblock frame-all grid-all stretch"> |
| <colgroup> |
| <col style="width: 20%;"> |
| <col style="width: 80%;"> |
| </colgroup> |
| <thead> |
| <tr> |
| <th class="tableblock halign-left valign-top">Plugin name</th> |
| <th class="tableblock halign-left valign-top">Description</th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>documentation</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">User-oriented documentation about the language, such as a user manual or a reference manual.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>metamodel</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Ecore metamodel back bone of the language. |
| Model classes for the central data structure that all tools of the language use. |
| Often generated using modeling tools such as Sirius, but manually written classes exist as well.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>metamodel.java</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Generated Java constructor and walker classes for the Ecore metamodel data structure.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>parser</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">SeText input, and generated or manually written code to parse an input file and convert it to an tree of classes that can be given to the type checker.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>typechecker</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Implementation of the type checker to check the parsed input, and annotate it with derived information, resulting in an model instance that can be used by all tools of the language.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>io</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Text file loading, parsing, and type checking, and possibly writing result specifications.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>texteditor</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Code for editing source files of the language in an text Eclipse editor, with folding, syntax highlighting, and reporting of errors and warnings in the specification.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>tests</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Collection of tests to check the tools for the language. |
| Typically a set of input specifications, a set of expected output files, and a <a href="#intro-chapter-tooldef">ToolDef</a> script to run the tests. |
| These tests can be seen as integration tests.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code><plugin-name>.tests</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Unit tests for that specific plugin.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>codegen</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Code generator to convert the input specification to a runnable model.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>runtime</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Support libraries used by the runnable model.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>tooldefs</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Interface definitions to make tools of the language available for <a href="#intro-chapter-tooldef">ToolDef</a>.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>common</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Common functionality used by many tools of the language.</p></td> |
| </tr> |
| </tbody> |
| </table> |
| <div class="paragraph"> |
| <p>Other plugin names are often tools with the same name.</p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="developer-middle-layer-common-functionality">Middle layer common functionality</h4> |
| <div class="paragraph"> |
| <p>The common code between all languages is stored in the <code>/common</code> directory, again with full name of the plugin as sub-directory names. |
| These plugins contain:</p> |
| </div> |
| <table class="tableblock frame-all grid-all stretch"> |
| <colgroup> |
| <col style="width: 33.3333%;"> |
| <col style="width: 66.6667%;"> |
| </colgroup> |
| <thead> |
| <tr> |
| <th class="tableblock halign-left valign-top">Plugin name</th> |
| <th class="tableblock halign-left valign-top">Description</th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>org.eclipse.escet.common.app.framework</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Common <a href="#app-framework-chapter-index">application framework</a>.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>org.eclipse.escet.common.app.framework.appsview.ui</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">The <a href="#use-apps-view">Applications view</a>. |
| User interface of the active applications.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>org.eclipse.escet.common.box</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Library to generate formatted code-like text.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>org.eclipse.escet.common.eclipse.ui</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Common Eclipse User Interface code.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>org.eclipse.escet.common.emf</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Common <em>EMF</em> code.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>org.eclipse.escet.common.emf.ecore.codegen</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Code generators from <em>Ecore</em> files.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>org.eclipse.escet.common.emf.ecore.validation</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Common <em>EMF</em> validation code.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>org.eclipse.escet.common.emf.ecore.xmi</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Common <em>EMF</em> <em>XMI</em> serialization code.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>org.eclipse.escet.common.java</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Common <em>Java</em> functions and classes, in particular the <em>Lists</em>, <em>Sets</em>, <em>Maps</em> and <em>Strings</em> classes.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>org.eclipse.escet.common.position.common</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Common functions for (text-file) positions in source files.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>org.eclipse.escet.common.position.metamodel</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">The Ecore metamodel for (text-file) positions in source files.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>org.eclipse.escet.common.raildiagrams</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Rail diagram generator. Produces syntax diagrams.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>org.eclipse.escet.common.svg</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Common <em>SVG</em> library for viewing and manipulating <em>SVG</em> trees.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>org.eclipse.escet.common.typechecker</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Common type checker functionality.</p></td> |
| </tr> |
| </tbody> |
| </table> |
| <div class="paragraph"> |
| <p> |
| </p> |
| </div> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="developer-coding-standards-chapter-index">Coding standards</h3> |
| <div class="paragraph"> |
| <p>The Eclipse ESCET <a href="#developer-dev-env-setup-chapter-index">development environment</a> has some features that allow developing high quality contributions:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>A Java formatter profile is included. |
| It allows to automatically format Java code for consistency and convenience.</p> |
| </li> |
| <li> |
| <p>The <a href="https://checkstyle.org/eclipse-cs">Eclipse Checkstyle Plugin</a> and a Checkstyle configuration are included. |
| They can be used to detect various other issues in Java code and other files.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>For all contributions to the Eclipse ESCET project, check the following:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>All Java code should be formatted using the provided formatting profile.</p> |
| </li> |
| <li> |
| <p>All contributions should be checked using the provided Checkstyle configuration.</p> |
| </li> |
| <li> |
| <p>All contributions should be free of warnings and errors, when working with them in the Eclipse ESCET development environment.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>Remember that <a href="#developer-contributing-chapter-index">contributions</a> are always welcome, and contributions don’t have to be perfect. |
| The project’s developers can help to improve your contribution, and ensure it adheres to these coding standards.</p> |
| </div> |
| <div class="paragraph"> |
| <p>For any questions regarding these coding standards, please <a href="#developer-chapter-index">contact</a> the project’s developers.</p> |
| </div> |
| <div class="paragraph"> |
| <p> |
| |
| |
| |
| |
| </p> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="developer-building-and-testing-chapter-index">Building and testing</h3> |
| <div class="paragraph"> |
| <p>The Eclipse ESCET software can be built using Maven/Tycho. |
| The build will build every individual plugin and feature, as well as the update site, product and all documentation. |
| Manually run it in one of the following ways:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>In an Eclipse-based <a href="#developer-dev-env-setup-chapter-index">development environment</a>, select <span class="menuseq"><b class="menu">Run</b> <i class="fa fa-angle-right caret"></i> <b class="menuitem">Run Configurations…​</b></span> to open the <em>Run Configurations</em> dialog. |
| From the list at the left, under <em>Maven Build</em>, select the <em>build</em> launch configuration, and click the <b class="button">Run</b> button to run the build.</p> |
| <div class="paragraph"> |
| <p>Additional launch configurations are available to build documentation projects separately.</p> |
| </div> |
| </li> |
| <li> |
| <p>On Windows, in a command prompt, with the root of the Git repository as current directory, enter <code>.\build.cmd</code> and press <kbd>ENTER</kbd>. |
| This requires Maven to be available on your system (to be on your <code>PATH</code>). |
| Make sure to use the same Java and Maven versions as for the Eclipse-based development environment.</p> |
| </li> |
| <li> |
| <p>On Linux/macOS, in a shell, with the root of the Git repository as current directory, enter <code>./build.sh</code> and press <kbd>ENTER</kbd>. |
| This requires Maven to be available on your system (to be on your <code>PATH</code>). |
| Make sure to use the same Java and Maven versions as for the Eclipse-based development environment.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>Builds are in certain cases also automatically executed on our build server:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="https://ci.eclipse.org/escet/">Eclipse ESCET Jenkins server</a></p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>If they are not automatically executed, login to Jenkins, open the desired build and select <b class="menuref">Scan GitLab Project Now</b> to force GitLab to scan for new branches, commits, etc.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Run tests in one of the following ways:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>As part of the build, all tests will be performed as well.</p> |
| </li> |
| <li> |
| <p>Launch configurations to run the integration/regression tests for a specific language are also available, under the <em>JUnit Plug-in Test</em> section of the <em>Run Configurations</em> dialog.</p> |
| </li> |
| </ul> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="developer-release-process-chapter-index">Release process</h3> |
| <div class="paragraph"> |
| <p>The process for working on, and releasing a new version of the Eclipse ESCET tools, involves the following steps:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>Prepare the Git repository for the next version (not a milestone or release candidate):</p> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>Run in the root of the Git repository the command <code>./mvn_escet.sh org.eclipse.tycho:tycho-versions-plugin:set-version -DnewVersion=<new-version></code>, where <code><new-version></code> is replaced by the new version, e.g. <code>0.2.0.qualifier</code>. |
| This replaces most version numbers automatically. |
| Check all changes to ensure no versions are updated that should not be updated.</p> |
| </li> |
| <li> |
| <p>Verify that the <code>feature</code> <code>url</code> and <code>version</code> of all <code>org.eclipse.escet.*</code> features in <code>org.eclipse.escet.product/category.xml</code> are properly updated. |
| The old version should no longer be present. |
| This should be automatic.</p> |
| </li> |
| <li> |
| <p>Verify that the <code>product</code> <code>version</code> in <code>org.eclipse.escet.product/escet.product</code> is properly updated. |
| The old version should no longer be present. |
| This should be automatic.</p> |
| </li> |
| <li> |
| <p>Verify that the <code>feature</code> <code>version</code> of the product feature in <code>org.eclipse.escet.product/escet.product</code> is properly updated. |
| The old version should no longer be present. |
| This should be automatic.</p> |
| </li> |
| <li> |
| <p>Verify that the <code>Bundle-Version</code> of all <code>MANIFEST.MF</code> files in <code>org.eclipse.escet.*</code> projects are properly updated. |
| The old version should no longer be present. |
| This should be automatic.</p> |
| </li> |
| <li> |
| <p>Manually replace in all <code>MANIFEST.MF</code> files the regex <code>org\.eclipse\.escet\.([a-z0-9\.]+);bundle-version="<old-version>"</code> by <code>org.eclipse.escet.\1;bundle-version="<new-version>"</code>, where <code><old-version></code> and <code><new-version></code> are replaced by actual versions, e.g. <code>0.1.0</code>. |
| Check for unintended changes. |
| Search for the old version in all manifests to ensure none remain.</p> |
| </li> |
| <li> |
| <p>In all documentation sets, add a new section to the release notes for the new release, before the existing releases:</p> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlight"><code>=== Version 0.2 |
| |
| TBD</code></pre> |
| </div> |
| </div> |
| </li> |
| <li> |
| <p>Verify that the <code><version></code> of a POM and its parent in each <code>pom.xml</code> are properly updated. |
| The old version should no longer be present. |
| This should mostly be automatic. |
| Manually adapt it where necessary.</p> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>Manually adapt the version in <code>org.eclipse.escet.configuration/pom.xml</code>.</p> |
| </li> |
| <li> |
| <p>Manually adapt the parent version in <code>org.eclipse.escet.root/pom.xml</code>. |
| Also remove the version for the pom itself, to prevent a warning that the version of the pom and its parent are identical.</p> |
| </li> |
| </ul> |
| </div> |
| </li> |
| <li> |
| <p>Manually adapt the <code><version></code> of the target platform in <code>org.eclipse.escet.configuration/pom.xml</code>.</p> |
| </li> |
| <li> |
| <p>Verify that the <code>version</code> of all <code>feature.xml</code> files in <code>org.eclipse.escet.*</code> projects .xml` are properly updated. |
| The old version should no longer be present. |
| This should mostly be automatic. |
| Manually adapt it where necessary.</p> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>Manually adapt the <code>version</code> of the <code>org.eclipse.escet.license.mit</code> feature.</p> |
| </li> |
| </ul> |
| </div> |
| </li> |
| <li> |
| <p>Manually replace in all <code>feature.xml</code> files the literal text <code>license-feature-version="<old-version>"</code> by <code>license-feature-version="<new-version>"</code>, where <code><old-version></code> and <code><new-version></code> are replaced by actual versions, e.g. <code>0.1.0.qualifier</code>. |
| Check for unintended changes.</p> |
| </li> |
| <li> |
| <p>Manually replace in all <code>feature.xml</code> files the regex <code><import feature="([^"]+)" version="<old-version>"/></code> by <code><import feature="\1" version="<new-version>"/></code>, where <code><old-version></code> and <code><new-version></code> are replaced by actual versions, e.g. <code>0.1.0.qualifier</code>. |
| Check for unintended changes.</p> |
| </li> |
| <li> |
| <p>Manually search for the old version in all <code>features.xml</code> files to ensure none remain.</p> |
| </li> |
| <li> |
| <p>Search the entire Git repository (all projects) for the old version number and update anything that still requires updating.</p> |
| </li> |
| <li> |
| <p>Test that the <a href="#developer-building-and-testing-chapter-index">build works</a>.</p> |
| </li> |
| </ul> |
| </div> |
| </li> |
| <li> |
| <p>Prepare for the next release in the <code>develop</code> branch until it is ready to be released.</p> |
| </li> |
| <li> |
| <p>Create a GitLab merge request from <code>develop</code> to <code>master</code>, and merge it. |
| Since <code>master</code> is a protected branch for the Eclipse ESCET GitLab, a GitLab merge request is the only way to update it.</p> |
| </li> |
| <li> |
| <p>Check that the build on <code>master</code> succeeds in Jenkins.</p> |
| </li> |
| <li> |
| <p>Add a tag on the commit in <code>master</code> that is to be released. |
| Only version tags with a specific syntax will be picked up by Jenkins to be released. |
| For instance, use <code>v0.1</code>, <code>v0.1.1</code>, <code>v2.0</code>, etc for releases, <code>v0.1-M1</code> for a milestone build, or <code>v0.1-RC1</code> for a release candidate.</p> |
| <div class="paragraph"> |
| <p>Add the tag via GitLab, at <a href="https://gitlab.eclipse.org/eclipse/escet/escet/-/tags/new" class="bare">https://gitlab.eclipse.org/eclipse/escet/escet/-/tags/new</a>. |
| Use the <em>Tag name</em> also as <em>Message</em>. |
| Make sure to select <code>master</code> as branch from which to create the tag. |
| For the <em>Release notes</em>, use a short text inspired by the release plan.</p> |
| </div> |
| <div class="paragraph"> |
| <p>As an example, consider milestone 1 of release v0.1: see <a href="https://projects.eclipse.org/projects/technology.escet/releases/0.1" class="bare">https://projects.eclipse.org/projects/technology.escet/releases/0.1</a> for the release plan, <a href="https://gitlab.eclipse.org/eclipse/escet/escet/-/tags/v0.1-M1" class="bare">https://gitlab.eclipse.org/eclipse/escet/escet/-/tags/v0.1-M1</a> for the tag and <a href="https://gitlab.eclipse.org/eclipse/escet/escet/-/releases/v0.1-M1" class="bare">https://gitlab.eclipse.org/eclipse/escet/escet/-/releases/v0.1-M1</a> for the GitLab release record.</p> |
| </div> |
| </li> |
| <li> |
| <p>Edit the GitLab release record, adding the GitLab milestone to the release record. |
| Save the changes.</p> |
| </li> |
| <li> |
| <p>Jenkins will automatically pick up the new tag. |
| Log in to Jenkins and manually trigger a build for the tag. |
| Jenkins will then automatically build and release a new version from that tag.</p> |
| </li> |
| <li> |
| <p>All releases can be downloaded at <a href="https://download.eclipse.org/escet/" class="bare">https://download.eclipse.org/escet/</a>. |
| For a version <code>v0.1</code>, the downloads will be located at <code>https://download.eclipse.org/escet/v0.1</code>.</p> |
| <div class="paragraph"> |
| <p>Note that according to the Eclipse Foundation Wiki page <a href="https://wiki.eclipse.org/IT_Infrastructure_Doc">IT Infrastructure Doc</a>, "Once your files are on the <code>download.eclipse.org</code> server, they are immediately available to the general public. |
| However, for release builds, we ask that you wait at least four hours for our mirror sites to fetch the new files before linking to them. |
| It typically takes a day or two for all the mirror sites to synchronize with us and get new files."</p> |
| </div> |
| <div class="paragraph"> |
| <p>That same wiki page also notes that "Although you can link directly to <code>download.eclipse.org/yourfile.zip</code>, you can also use the <em>Find a Mirror</em> script […​]. |
| Using this script allows you to view download statistics and allows users to pick a nearby mirror site for their download." It further indicates that "P2 repositories are not normally accessed via the mirror selection script." The <em>Find a Mirror</em> script also transparently handles files moved from <code>download.eclipse.org</code> to <code>archive.eclipse.org</code>.</p> |
| </div> |
| </li> |
| <li> |
| <p>Jenkins will automatically push the website for the new release to the website Git repository, in a directory for the specific release. |
| For a version <code>v0.1</code>, the website can be accessed at <code>https://www.eclipse.org/escet/v0.1</code>. |
| It may take a few minutes for the Git repository to be synced to the webserver and for the website for the new version to become available.</p> |
| </li> |
| <li> |
| <p>If the website for the new release is to be the standard visible website for the project (at <code><a href="https://www.eclipse.org/escet" class="bare">https://www.eclipse.org/escet</a></code>), it has to be manually replaced. |
| This is to ensure that a bugfix release for an older version doesn’t override the standard visible website. |
| The following steps explain how to 'promote' a website for a specific version to become the standard visible website:</p> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>Make sure you’ve uploaded your SSH public key to Eclipse Gerrit. |
| This is a one-time only step. |
| Go to <a href="https://git.eclipse.org/r/" class="bare">https://git.eclipse.org/r/</a>. |
| Sign in using your Eclipse Foundation committer account. |
| Use the gear icon at the top right to access your account settings. |
| Under <em>SSH Keys</em> add your SSH public key. |
| Also make note of your <em>username</em>, <em>Full name</em> and <em>Email</em> address.</p> |
| </li> |
| <li> |
| <p>Clone the Eclipes ESCET website Git repository using <code>git clone ssh://<username>@git.eclipse.org:29418/www.eclipse.org/escet.git</code>. |
| Make sure to replace <code><username></code> by your Eclipse Foundation committer account <em>username</em>.</p> |
| </li> |
| <li> |
| <p>In the cloned repository, remove all files/folders in the root of the Git repository pertaining to the current standard visible website. |
| Be sure not to remove any of the directories with websites for specific releases.</p> |
| </li> |
| <li> |
| <p>Copy the files/folders from the directory with the website for the release that you want to make the standard visible website, and put them in the root of the Git repository.</p> |
| </li> |
| <li> |
| <p>Add all changes to be committed, e.g. by using <code>git add -A</code>.</p> |
| </li> |
| <li> |
| <p>Make sure to use the <em>Full name</em> and <em>Email</em> address of your Eclipse Foundation committer account. |
| E.g. use <code>git config --local user.name "<full_name>"</code> and <code>git config --local user.email "<email>"</code>, replacing <code><full_name></code> and <code><email></code> by the appropriate information matching your Eclipse Foundation committer account.</p> |
| </li> |
| <li> |
| <p>Commit the changes. |
| Use as commit message <code>Set standard visible website to release <version>.</code>, replacing <code><version></code> by the release version that will become the new standard visible website. |
| Make sure to sign off the commit to pass Eclipse Foundation automatic commit validation. |
| E.g. use the following to commit the changes: |
| <code>git commit -s -m "Set standard visible website to release v0.1."</code>.</p> |
| </li> |
| <li> |
| <p>Push the changes to the Git server. |
| E.g. use <code>git push</code>. |
| If successful you should see the changes at the Git server’s web view, at <a href="https://git.eclipse.org/c/www.eclipse.org/escet.git/" class="bare">https://git.eclipse.org/c/www.eclipse.org/escet.git/</a>.</p> |
| </li> |
| <li> |
| <p>It may take a few minutes for the Git repository to be synced to the webserver, and for the new standard visible website to become available. |
| The standard visible website can be accessed at <code><a href="https://www.eclipse.org/escet" class="bare">https://www.eclipse.org/escet</a></code>. |
| Depending on browser cache settings and other factors, it may be necessary to force refresh your browser for it to pick up the changes on the server.</p> |
| </li> |
| </ul> |
| </div> |
| </li> |
| <li> |
| <p>Remove/archive old releases:</p> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>For every release (not a milestone or release candidate), remove all milestones and release candidates of the previous version and older. |
| E.g. for <code>v0.2</code>, remove <code>v0.1-M1</code>, <code>v0.1-M2</code>, <code>v0.1-RC1</code>, etc. |
| Also archive all releases older than the current and previous release. |
| E.g. for <code>v0.3</code> archive <code>v0.1</code> and older, but keep <code>v0.2</code>.</p> |
| <div class="paragraph"> |
| <p>Consider whether archiving or removing P2 update sites will lead to issues for users. |
| See for more information the Eclipse Foundation Wiki page <a href="https://wiki.eclipse.org/Equinox/p2/p2.mirrorsURL#Moving_a_repo_to_archive.eclipse.org">Moving a repo to archive.eclipse.org</a>.</p> |
| </div> |
| </li> |
| <li> |
| <p>Old websites can be removed in a similar way to the above instructions to change the default website. |
| Only remove the directory for the milestone or release candidate.</p> |
| </li> |
| <li> |
| <p>Older downloads can be archived. |
| Go to <a href="https://download.eclipse.org/escet/" class="bare">https://download.eclipse.org/escet/</a>. |
| Make sure you’re logged in. |
| This should make check-boxes appear. |
| Select the folders to archive and click the <em>Archive</em> button. |
| It may take a few minutes for archiving to complete.</p> |
| </li> |
| <li> |
| <p>Archived downloads can be removed. |
| Go to <a href="https://archive.eclipse.org/escet/" class="bare">https://archive.eclipse.org/escet/</a>. |
| Make sure you’re logged in. |
| This should make check-boxes appear. |
| Select the folders to delete and click the <em>Delete</em> button. |
| It may take a few minutes for deleting to complete.</p> |
| </li> |
| </ul> |
| </div> |
| </li> |
| </ul> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="developer-third-party-tools-chapter-index">Third party tools</h3> |
| <div class="paragraph"> |
| <p>As part of development for the Eclipse ESCET project, several third party tools are used. |
| They are used to e.g. run scripts, generate files, etc.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The following third party tools are used to run scripts:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>Bash, to run <code>.bash</code> scripts.</p> |
| </li> |
| <li> |
| <p>GNU utilities, to use in scripts, e.g. <code>cat</code>, <code>cp</code>, <code>diff</code>, <code>dirname</code>, <code>find</code>, <code>grep</code>, <code>mv</code>, <code>readlink</code>, <code>rm</code>, <code>sed</code>, <code>sort</code> and <code>wc</code>.</p> |
| </li> |
| <li> |
| <p>Perl, to run <code>.pl</code> scripts.</p> |
| </li> |
| <li> |
| <p>Python, version 3, to run <code>.py</code> scripts.</p> |
| </li> |
| <li> |
| <p>Shell, to run <code>.sh</code> scripts.</p> |
| </li> |
| <li> |
| <p>Windows command prompt, to run <code>.cmd</code> scripts.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>The following third party tools are used to build:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>Maven, to run the main build from a console.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>The following third party tools are used to generate/convert images:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><code>bbox_add.pl</code> Perl script, used in conjunction with LaTeX, obtained from <a href="http://www.inference.org.uk/mackay/perl/bbox_add.pl" class="bare">http://www.inference.org.uk/mackay/perl/bbox_add.pl</a>.</p> |
| </li> |
| <li> |
| <p><code>eps2png</code> Perl script, used in conjunction with LaTeX, obtained from <a href="https://metacpan.org/pod/eps2png" class="bare">https://metacpan.org/pod/eps2png</a>.</p> |
| </li> |
| <li> |
| <p>Gnuplot, to generate images.</p> |
| </li> |
| <li> |
| <p>ImageMagic, used in conjunction with LaTeX, including <code>convert</code>.</p> |
| </li> |
| <li> |
| <p>Inkscape, to convert <code>.svg</code> images.</p> |
| </li> |
| <li> |
| <p>LaTeX, to generate images, including <code>dvips</code>, <code>latex</code>, <code>pdfcrop</code> and <code>pdflatex</code>.</p> |
| </li> |
| <li> |
| <p>Make, run <code>Makefile</code> builds, to generate images.</p> |
| </li> |
| <li> |
| <p>LaTeX <code>rail</code> package, including <code>rail</code>.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>The following third party tools are used to build some of the documentation:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>LaTeX, including <code>bibtex</code> and <code>pdflatex</code>.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>The following third party tools are used to generate test classes and package them into a JAR file, for certain tests:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>Java Development Kit (JDK), version 7 or higher, including <code>javac</code> and <code>jar</code>.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>Most of these tools are not needed to run a build or run the tests, as the generated files (e.g. images) are committed into Git.</p> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="developer-upgrade-instructions-chapter-index">Upgrade instructions</h3> |
| <div class="paragraph"> |
| <p>To upgrade to a new Eclipse Platform/IDE/SDK version:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>New development environment</p> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="#developer-dev-env-setup-chapter-index">Set up a new development environment</a> for the new Eclipse IDE version.</p> |
| </li> |
| </ul> |
| </div> |
| </li> |
| <li> |
| <p>Version updates</p> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>Look up Orbit version for the new Eclipse Platform/IDE/SDK release, see <a href="https://download.eclipse.org/tools/orbit/downloads/" class="bare">https://download.eclipse.org/tools/orbit/downloads/</a>.</p> |
| </li> |
| <li> |
| <p>Update Oomph setup (<code>org.eclipse.escet.setup</code>), configuring new Eclipse IDE and Orbit versions.</p> |
| </li> |
| <li> |
| <p>Update <code>dev-env-setup.asciidoc</code> to match new Eclipse version.</p> |
| </li> |
| <li> |
| <p>Update <code>org.eclipse.platform</code> version for the product feature (<code>org.eclipse.escet.product.feature/feature.xml</code>).</p> |
| </li> |
| <li> |
| <p>Update Eclipse and Orbit update site URLs in product (<code>org.eclipse.escet.product/escet.product</code>).</p> |
| </li> |
| </ul> |
| </div> |
| </li> |
| <li> |
| <p>Update target platform and address any issues</p> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>Let Oomph regenerate the target platform, and commit any changes.</p> |
| </li> |
| <li> |
| <p>Force a rebuild in Eclipse (<span class="menuseq"><b class="menu">Project</b> <i class="fa fa-angle-right caret"></i> <b class="menuitem">Clean…​</b></span>).</p> |
| </li> |
| <li> |
| <p>Check workspace for any errors/warnings and address them if any.</p> |
| </li> |
| <li> |
| <p>Check <em>New and Noteworthy</em> (release notes) of the new Eclipse version for changes and adapt as necessary.</p> |
| </li> |
| </ul> |
| </div> |
| </li> |
| <li> |
| <p>Java formatter profile</p> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>Navigate to <span class="menuseq"><b class="menu">Window</b> <i class="fa fa-angle-right caret"></i> <b class="menuitem">Preferences</b></span>.</p> |
| </li> |
| <li> |
| <p>Ensure the Oomph preference recorder is enabled, using the corresponding button at the bottom left of the dialog.</p> |
| </li> |
| <li> |
| <p>In the dialog, navigate to <span class="menuseq"><b class="menu">Java</b> <i class="fa fa-angle-right caret"></i> <b class="submenu">Code Style</b> <i class="fa fa-angle-right caret"></i> <b class="submenu">Formatter</b> <i class="fa fa-angle-right caret"></i> <b class="submenu">Eclipse ESCET profile</b> <i class="fa fa-angle-right caret"></i> <b class="menuitem">Edit…​</b></span>.</p> |
| </li> |
| <li> |
| <p>Make a dummy change to the Eclipse ESCET Java formatter profile and close the profile editing dialog by clicking <b class="button">OK</b>.</p> |
| </li> |
| <li> |
| <p>Close the preferences dialog by clicking <b class="button">Apply and Close</b>.</p> |
| </li> |
| <li> |
| <p>An Oomph preference recorder dialog will appear that can be dismissed by clicking <b class="button">Cancel</b>.</p> |
| </li> |
| <li> |
| <p>Repeat the previous steps to revert the dummy change until the Oomph preference recorder dialog appears again.</p> |
| </li> |
| <li> |
| <p>Select the relevant preferences, note their names, and copy the values from the bottom text box to an external text editor.</p> |
| </li> |
| <li> |
| <p>Close the Oomph preference recorder dialog by clicking <b class="button">Cancel</b>.</p> |
| </li> |
| <li> |
| <p>Open the Oomph setup (<code>org.eclipse.escet.setup</code>) and look for the relevant preferences.</p> |
| </li> |
| <li> |
| <p>Right click such a preference and choose <b class="menuref">Show Properties View</b>.</p> |
| </li> |
| <li> |
| <p>In the properties view, get the current values of the preferences, and compare them to the new values using your favorite diff tool.</p> |
| </li> |
| <li> |
| <p>Replace the current values of the preferences by the new values.</p> |
| </li> |
| <li> |
| <p>Don’t forget to save the updated Oomph setup.</p> |
| </li> |
| <li> |
| <p>In case of formatting profile changes, reformat all Java code using the new formatter profile.</p> |
| </li> |
| </ul> |
| </div> |
| </li> |
| <li> |
| <p>Java errors/warnings settings</p> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>Right click the <code>org.eclipse.escet.common.java</code> project in the Package Explorer view and choose <b class="menuref">Properties</b>.</p> |
| </li> |
| <li> |
| <p>In the properties dialog, select <span class="menuseq"><b class="menu">Java Compiler</b> <i class="fa fa-angle-right caret"></i> <b class="menuitem">Errors/Warnings</b></span>.</p> |
| </li> |
| <li> |
| <p>Make a dummy change and apply it by clicking <em>Apply and Close</em>.</p> |
| </li> |
| <li> |
| <p>Click <em>Yes</em> when asked to <em>Rebuild the project now to apply the changes of the Error/Warning settings?</em>.</p> |
| </li> |
| <li> |
| <p>Revert the dummy change, using again the same steps.</p> |
| </li> |
| <li> |
| <p>In case of changes to <code>*.prefs</code> files in the <code>.settings</code> directory of that project, configure the new settings as desired.</p> |
| </li> |
| <li> |
| <p>Run <code>misc/java-code-style/copy_here.bash ../../common/org.eclipse.escet.common.java</code> from <code>misc/java-code-style</code> to copy the new settings to the central place.</p> |
| </li> |
| <li> |
| <p>Run <code>misc/java-code-style/copy_there.bash</code> from <code>misc/java-code-style</code> to copy the new settings to all relevant projects.</p> |
| </li> |
| <li> |
| <p>Force a rebuild in Eclipse (<span class="menuseq"><b class="menu">Project</b> <i class="fa fa-angle-right caret"></i> <b class="menuitem">Clean…​</b></span>) and check for any warnings/errors, addressing them if any.</p> |
| </li> |
| </ul> |
| </div> |
| </li> |
| <li> |
| <p>Update Maven version</p> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>Check the embedded Maven version, by navigating to <span class="menuseq"><b class="menu">Run</b> <i class="fa fa-angle-right caret"></i> <b class="menuitem">Run Configurations…​</b></span>, selecting the <em>build</em> launch configuration under <em>Maven Build</em>, and observing the <em>Maven Runtime</em> version.</p> |
| </li> |
| <li> |
| <p>Ensure the Maven version in <code>Jenkinsfile</code> matches the embedded Maven version.</p> |
| </li> |
| <li> |
| <p>Ensure the Maven version in <code>misc/license-check-dependencies/Jenkinsfile</code> matches the embedded Maven version.</p> |
| </li> |
| </ul> |
| </div> |
| </li> |
| <li> |
| <p>Validation</p> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>Run a <a href="#developer-building-and-testing-chapter-index">Maven build</a>.</p> |
| </li> |
| <li> |
| <p>Ensure no errors or warnings during Maven build.</p> |
| </li> |
| </ul> |
| </div> |
| </li> |
| <li> |
| <p>Dependency information</p> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>Run <code>misc/license-check-dependencies/license-check-dependencies.sh</code> and update <code>DEPENDENCIES.txt</code> according to the output.</p> |
| </li> |
| <li> |
| <p>Run <code>misc/license-check-dependencies/license-check-dependencies.sh</code> again, to ensure <code>DEPENDENCIES.txt</code> is up-to-date.</p> |
| </li> |
| </ul> |
| </div> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>To upgrade to a new Tycho version:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>Update version in <code>org.eclipse.escet.root/.mvn/extensions.xml</code>.</p> |
| </li> |
| <li> |
| <p>Update version in <code>org.eclipse.escet.configuration/pom.xml</code>.</p> |
| </li> |
| <li> |
| <p>Check Tycho release notes for changes and adapt as necessary.</p> |
| </li> |
| <li> |
| <p>Run a <a href="#developer-building-and-testing-chapter-index">Maven build</a>.</p> |
| </li> |
| <li> |
| <p>Ensure no errors or warnings during Maven build.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>To upgrade to a new Java version:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>For major Java versions (e.g. 11 to 12):</p> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>Update <code>Bundle-RequiredExecutionEnvironment</code> for all plug-in manifests.</p> |
| </li> |
| <li> |
| <p>Update <code>JRE_CONTAINER</code> in all <code>.classpath</code> files.</p> |
| </li> |
| <li> |
| <p>Update <code>JRE_CONTAINER</code> in all launch configurations (<code>.launch</code> files).</p> |
| </li> |
| <li> |
| <p>Update Java versions in <code>org.eclipse.jdt.core.prefs</code> files.</p> |
| </li> |
| <li> |
| <p>Update <code>osgi.requiredJavaVersion</code> in the product (<code>org.eclipse.escet.product/escet.product</code>).</p> |
| </li> |
| <li> |
| <p>Update Java version for <code>executionEnvironment</code> in <code>org.eclipse.escet.configuration/pom.xml</code>.</p> |
| </li> |
| <li> |
| <p>Update Java version in <code>Jenkinsfile</code>.</p> |
| </li> |
| <li> |
| <p>Update Java version in <code>misc/license-check-dependencies/Jenkinsfile</code>.</p> |
| </li> |
| </ul> |
| </div> |
| </li> |
| <li> |
| <p>For any Java versions (e.g. 11 to 12, or 11.0.1 to 11.0.2):</p> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>Update the JustJ version (<code>eclipse.justj.version.*</code> variables) in the Oomph setup (<code>org.eclipse.escet.setup</code>).</p> |
| </li> |
| <li> |
| <p>Regenerate the target platform file using Oomph.</p> |
| </li> |
| <li> |
| <p>Update the JustJ version in the product (<code>org.eclipse.escet.product/escet.product</code>).</p> |
| </li> |
| <li> |
| <p>Update <code>dev-env-setup.asciidoc</code> to match new Java version.</p> |
| </li> |
| <li> |
| <p>Force a rebuild in Eclipse (<span class="menuseq"><b class="menu">Project</b> <i class="fa fa-angle-right caret"></i> <b class="menuitem">Clean…​</b></span>) and check for any warnings/errors, addressing them if any.</p> |
| </li> |
| <li> |
| <p>Run a <a href="#developer-building-and-testing-chapter-index">Maven build</a>.</p> |
| </li> |
| <li> |
| <p>Ensure no errors or warnings during Maven build.</p> |
| </li> |
| <li> |
| <p>Run <code>misc/license-check-dependencies/license-check-dependencies.sh</code> and update <code>DEPENDENCIES.txt</code> according to the output.</p> |
| </li> |
| <li> |
| <p>Run <code>misc/license-check-dependencies/license-check-dependencies.sh</code> to ensure <code>DEPENDENCIES.txt</code> is up-to-date.</p> |
| </li> |
| </ul> |
| </div> |
| </li> |
| </ul> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="app-framework-chapter-index">Application framework</h2> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p>The Eclipse ESCET application framework provides common functionality for applications within the Eclipse ESCET toolkit. |
| The following topics explain the framework in more detail:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="#app-framework-introduction">Introduction</a></p> |
| </li> |
| <li> |
| <p><a href="#app-framework-standalone-vs-eclipse">Stand-alone execution versus Eclipse IDE</a></p> |
| </li> |
| <li> |
| <p><a href="#app-framework-application-class">The Application class</a></p> |
| </li> |
| <li> |
| <p><a href="#app-framework-exception-framework">The exception framework</a></p> |
| </li> |
| <li> |
| <p><a href="#app-framework-exit-codes">Exit codes</a></p> |
| </li> |
| <li> |
| <p><a href="#app-framework-io-framework">The I/O framework</a></p> |
| </li> |
| <li> |
| <p><a href="#app-framework-option-framework">The option framework</a></p> |
| </li> |
| <li> |
| <p><a href="#app-framework-compiler-framework">The compiler framework</a></p> |
| </li> |
| <li> |
| <p><a href="#app-framework-implement-your-application">How to implement your own application</a></p> |
| </li> |
| <li> |
| <p><a href="#app-framework-registration">Application registration</a></p> |
| </li> |
| <li> |
| <p><a href="#app-framework-execution">Execution</a></p> |
| </li> |
| </ul> |
| </div> |
| <div class="sect2"> |
| <h3 id="app-framework-introduction">Introduction</h3> |
| <div class="paragraph"> |
| <p>The Eclipse ESCET application framework provides common functionality for applications within the Eclipse ESCET toolkit. |
| It has several goals:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>Provide a uniform end-user experience, for example in the form of uniform option dialogs.</p> |
| </li> |
| <li> |
| <p>Hide technical details from the end user, for example in the form of crash reports and user friendly error messages, instead of stack traces.</p> |
| </li> |
| <li> |
| <p>Provide support for applications to run both as a stand-alone Java program (say, from the command line), as well as within the Eclipse environment.</p> |
| </li> |
| <li> |
| <p>Provide the basic functionality needed by most applications, to reduce the overhead needed for developers to develop an application.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>The documentation for this framework describes the issues that the application framework attempts to solve, and the way it solves them. |
| It also provides guidance in implementing applications using the application framework.</p> |
| </div> |
| <div class="paragraph"> |
| <p> |
| </p> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="app-framework-standalone-vs-eclipse">Stand-alone execution versus Eclipse IDE</h3> |
| <div class="paragraph"> |
| <p>One of the goals of the application framework is to make it easier to allow applications to run as stand-alone Java command line applications, as well as run within the Eclipse IDE. |
| The main problem faced when supporting general applications to run within Eclipse, is that such applications all run within the same instance of the Java Virtual Machine (JVM). |
| In fact, a single application may have multiple instances running at the same time, within a single instance of the IDE. |
| The following sections address the issues that arise when running within the IDE, and how the application framework handles them.</p> |
| </div> |
| <div class="paragraph"> |
| <p></p> |
| </div> |
| <div class="sect3"> |
| <h4 id="app-framework-app-static-information">Application static information</h4> |
| <div class="paragraph"> |
| <p>Within Java programs, members can be defined with the <code>static</code> modifier. |
| Since multiple instances of an application may be running simultaneously, within a single instance of the IDE, one should avoid using static variables that contain information that is specific to a single instance of the application. |
| For instance, assume an application that maintains an integer counter, used to generate unique identifiers. |
| If defined in a class as follows:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlight"><code class="language-java" data-lang="java">public static int count = 0;</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>and incremented when needed, the first instance of the application will run just fine. |
| Variable <code>count</code> starts at zero, and is incremented over and over again. |
| When a second instance of the application starts however, the static variable keeps its value, as the new application is started within the same Eclipse instance, and thus within the same JVM. |
| The count won’t start from zero, thus leading to different results for the application.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The conclusion is that one should be careful to avoid static variables that hold information specific to an application instance.</p> |
| </div> |
| <div class="paragraph"> |
| <p></p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="app-framework-application-options">Application options</h4> |
| <div class="paragraph"> |
| <p>Applications often have settings, and they are generally passed as command line arguments. |
| GUI applications however, often use a dialog to configure the options instead. |
| To allow applications within the application framework to work in both scenarios, all applications should use the option framework.</p> |
| </div> |
| <div class="paragraph"> |
| <p>See also the <a href="#app-framework-option-framework">option framework</a> section.</p> |
| </div> |
| <div class="paragraph"> |
| <p> |
| |
| </p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="app-framework-stdin-stdout-stderr">Stdin, stdout, and stderr</h4> |
| <div class="paragraph"> |
| <p>Command line applications generally obtain input from stdin, and write output to stdout and/or stderr streams. |
| For applications running within the IDE, those streams are connected to the Eclipse application (IDE) as a whole, and not to the applications running within the IDE. |
| To provide a uniform I/O interface, the application framework includes an I/O framework.</p> |
| </div> |
| <div class="paragraph"> |
| <p>See also the <a href="#app-framework-io-framework">I/O framework</a> section.</p> |
| </div> |
| <div class="paragraph"> |
| <p> |
| </p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="app-framework-guis-and-swt">Graphical User Interfaces (GUIs) and SWT</h4> |
| <div class="paragraph"> |
| <p>The Eclipse IDE uses the Standard Widget Toolkit (SWT) for its graphical user interface (GUI). |
| To be compatible with the Eclipse IDE, all GUI applications should use SWT as well. |
| In order for GUI applications to work seamlessly within the Eclipse IDE as well as stand-alone, the application framework automatically registers the main SWT display thread for stand-alone applications, and uses the Eclipse SWT display thread when running within the Eclipse IDE. |
| This reduces the burden of having to register the main SWT display threads, but also avoids blocking and other thread related issues.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Using the <em>GUI</em> option, the GUI can be enabled or disabled. |
| If disabled, headless execution mode is used, which disables creation of a SWT display thread, and thus disables all GUI functionality, including the option dialog.</p> |
| </div> |
| <div class="paragraph"> |
| <p></p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="app-framework-app-termination">Application termination</h4> |
| <div class="paragraph"> |
| <p>Within Java, the <code>System.exit</code> method can be used to immediately terminate an application, by terminating the JVM. |
| For applications running within the Eclipse IDE, this not only terminates the application, but the IDE as well. |
| As such, the <code>System.exit</code> method should never be used in applications that are intended to be executed within the IDE.</p> |
| </div> |
| <div class="paragraph"> |
| <p></p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="app-framework-sigint">SIGINT</h4> |
| <div class="paragraph"> |
| <p>Stand-alone applications can typically be started from a the command line terminal window. |
| Pressing <span class="keyseq"><kbd>Ctrl</kbd>+<kbd>C</kbd></span> at such a command line terminal window terminates the currently running application (on Unix-based systems, this generates a SIGINT). |
| Applications running within the Eclipse IDE however, don’t run in an actual command line terminal. |
| Instead, they run within the IDE, and the stdin, stdout, and stderr streams are coupled to the Eclipse console view. |
| The Eclipse console view does not support termination using the <span class="keyseq"><kbd>Ctrl</kbd>+<kbd>C</kbd></span> key combination. |
| Instead, <span class="keyseq"><kbd>Ctrl</kbd>+<kbd>C</kbd></span> is used to copy console output to the clipboard. |
| To remedy this situation, application framework applications running within Eclipse get a <em>Terminate</em> button with their console within the IDE, to allow for easy termination.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Furthermore, the application framework allows termination requests via the <code>AppEnv.terminate</code> method. |
| Application framework applications and threads should regularly call the <code>AppEnv.isTerminationRequested</code> method to see whether they should terminate.</p> |
| </div> |
| <div class="paragraph"> |
| <p>See also the <a href="#use-apps-view-termination">termination features</a> of the <a href="#use-apps-view">Applications</a> <a href="#use-terminology-view">view</a>.</p> |
| </div> |
| <div class="paragraph"> |
| <p></p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="app-framework-exceptions">Exceptions</h4> |
| <div class="paragraph"> |
| <p>Exceptions are Java feature that allows applications to report error conditions. |
| Exceptions can generally be divided into two categories: internal errors, and end-user errors. |
| Internal errors should generally not happen, and make the application crash. |
| The application framework provides crash reports for end users to report crashes due to internal errors. |
| The application framework also provides exception classes for end-user errors, to provide nice error messages, instead of stack traces.</p> |
| </div> |
| <div class="paragraph"> |
| <p>See also the <a href="#app-framework-exception-framework">exception framework</a> section.</p> |
| </div> |
| <div class="paragraph"> |
| <p></p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="app-framework-system-properties">System properties</h4> |
| <div class="paragraph"> |
| <p>Java uses system properties (<code>System.getProperty</code> method etc). |
| Those properties are global to the entire JVM, meaning they are shared between applications running within the Eclipse IDE. |
| The application framework provides functionality to maintain system properties on a per application basis, turning them into application properties. |
| All application framework applications should use the <code>getProp*</code> and <code>setProp*</code> methods in the <code>AppEnv</code> class instead of the property related methods in the <code>System</code> class. |
| This ensures that the application properties are used instead of the global system properties.</p> |
| </div> |
| <div class="paragraph"> |
| <p> |
| </p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="app-framework-filepaths-and-current-working-dir">File paths and current working directory</h4> |
| <div class="paragraph"> |
| <p>One of the standard system properties in Java is the <code>user.dir</code> property, which refers to the current working directory, or more precisely, the directory from which the JVM was started. |
| Java doesn’t allow changing the current working directory. |
| The application framework however, maintains the current working directory on a per application basis. |
| Changing the current working directory is also supported. |
| Application framework applications should use the methods in the <code>org.eclipse.escet.common.app.framework.Paths</code> class to get and set the current working directory, to resolve relative paths, etc. |
| These methods also allow both Windows (<code>\</code>) and Unix (<code>/</code>) separators to be used in paths, on all platforms, transparently.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Furthermore, within the Eclipse IDE, the concept of a <a href="#use-terminology-workspace">workspace</a> is introduced. |
| In order to allow importing of resources from other projects etc, it may be nice to allow end users to specify platform paths (plug-in paths or workspace paths). |
| Eclipse Modeling Framework (EMF) URIs, besides local file system paths, provide functionality for platform URIs as well. |
| EMF URIs can for instance be used to load models that are instances of an Ecore. |
| The <code>Paths</code> class mentioned above features methods to create such EMF URIs, from various sources. |
| Those methods also feature smart handling of <code>platform:/auto/...</code> paths, an addition to platform URIs, added by the application framework. |
| Such URIs are first resolved in the workspace, and if they can’t be found there, they are resolved in the plug-ins. |
| This allows for easier debugging, as the workspace always overrides the plug-ins.</p> |
| </div> |
| <div class="paragraph"> |
| <p></p> |
| </div> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="app-framework-application-class">The Application class</h3> |
| <div class="paragraph"> |
| <p>The <code>org.eclipse.escet.common.app.framework.Application<T></code> class is the main class of the application framework. |
| All application should inherit from this abstract class. |
| The generic parameter <code><T></code> is further explained in the section about the <a href="#app-framework-io-framework">I/O framework</a>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The next sections introduce the specific parts of the application framework. |
| After that, you’ll find a section on how to implement your own application, using the application framework.</p> |
| </div> |
| <div class="paragraph"> |
| <p></p> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="app-framework-exception-framework">The exception framework</h3> |
| <div class="paragraph"> |
| <p>The application framework contains the exception framework. |
| Its main goal is to hide stack traces from end users. |
| Exceptions can generally be divided into two categories: internal errors, and end-user errors.</p> |
| </div> |
| <div class="paragraph"> |
| <p></p> |
| </div> |
| <div class="sect3"> |
| <h4 id="app-framework-enduser-exceptions">End-user exceptions</h4> |
| <div class="paragraph"> |
| <p>All exceptions that should be presented to the end user are considered end-user exceptions. |
| These messages should be written in terms that the end user should be able to understand. |
| For end-user exceptions, the exception framework does not display stack traces (at least not by default). |
| All end-user exceptions must implement the <code>org.eclipse.escet.common.app.framework.exceptions.EndUserException</code> interface, and may inherit from the <code>org.eclipse.escet.common.app.framework.exceptions.ApplicationException</code> class. |
| All applications that use the application framework must satisfy these requirements when the error message is to be presented to end users. |
| It is recommended to reuse existing application framework exceptions whenever possible.</p> |
| </div> |
| <div class="paragraph"> |
| <p></p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="app-framework-internal-exceptions">Internal exceptions</h4> |
| <div class="paragraph"> |
| <p>All exceptions that are not to be presented to end users are considered to be internal exceptions. |
| Internal exceptions crash the application and are always considered to be bugs. |
| The application framework generates crash reports for internal errors, so that end users can easily report them. |
| Also, stack traces are not shown on the console. |
| They are however present in the crash report, along with among others information about the system, the Java version used, the application that crashed (name, version, etc), and if the OSGi framework is running, the available plug-ins etc.</p> |
| </div> |
| <div class="paragraph"> |
| <p> |
| </p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="app-framework-chained-excpetions">Chained exceptions</h4> |
| <div class="paragraph"> |
| <p>Java supports the concept of <em>chained exceptions</em>. |
| The end-user exceptions of the application framework support this as well. |
| If an uncaught end-user exception needs to be presented to the end user, the message of the exception is printed to the console, prefixed with the <code>ERROR:</code> text. |
| All the causes of the exception are printed as well, each on a line of their own. |
| Those messages are prefixed with the <code>CAUSE:</code> text. |
| For exceptions that provide an end-user readable message, only that message is printed after the <code>CAUSE:</code> text. |
| For other exceptions, the simple name of the exception class, enclosed in parentheses, is printed between the <code>CAUSE:</code> text and the exception message. |
| All end-user exceptions (the ones inheriting from the <code>org.eclipse.escet.common.app.framework.exceptions.ApplicationException</code> class), as well as all other exceptions explicitly designed as such (by implementing the <code>org.eclipse.escet.common.app.framework.exceptions.EndUserException</code> interface) are considered to provide readable messages. |
| For other exceptions, it is assumed that they don’t. |
| This includes all exceptions provided by Java itself.</p> |
| </div> |
| <div class="paragraph"> |
| <p></p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="app-framework-development-mode">Development mode</h4> |
| <div class="paragraph"> |
| <p>Developers can enable the development mode option (<code>DevModeOption</code> class) to always get stack traces for all internal exceptions (thus for crashes, but not for end-user exceptions), instead of crash reports. |
| For more information, see the <a href="#app-framework-option-framework">option framework</a> section.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The development mode option is ideal for automated tests, where a stack trace on stderr is much more ideal than a crash report.</p> |
| </div> |
| <div class="paragraph"> |
| <p></p> |
| </div> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="app-framework-exit-codes">Exit codes</h3> |
| <div class="paragraph"> |
| <p>Application framework applications can terminate with the following exit codes:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><code>0</code>: Application finished without errors.</p> |
| </li> |
| <li> |
| <p><code>1</code>: Application finished after reporting an error to the end user.</p> |
| </li> |
| <li> |
| <p><code>2</code>: Application crashed after running out of memory.</p> |
| </li> |
| <li> |
| <p><code>3</code>: Application crashed for any reason other than running out of memory.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>Note that applications themselves should always return a zero exit code. |
| The other exit codes are generated automatically by the exception framework when applicable.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Any exceptions to these rules should generally be avoided, but otherwise must be clearly documented for end users.</p> |
| </div> |
| <div class="paragraph"> |
| <p> |
| </p> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="app-framework-io-framework">The I/O framework</h3> |
| <div class="paragraph"> |
| <p>To provide a uniform I/O interface, the application framework includes an I/O framework. |
| This framework is sometimes also called the output framework, as it mainly handles output. |
| The main goals of this framework are:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>Provide uniform stdin, stdout, and stderr support for applications running on the command line, or within the Eclipse IDE.</p> |
| </li> |
| <li> |
| <p>Provide a general framework for output, based on output components that can be registered and unregistered.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p></p> |
| </div> |
| <div class="sect3"> |
| <h4 id="app-framework-output-components">Output components</h4> |
| <div class="paragraph"> |
| <p>The I/O framework works with output components. |
| All output that the application generates, is given to the output components. |
| Each output component can decide for itself what to do with that output. |
| All applications include at least a <code>StreamOutputComponent</code>, that redirects stream output to the console. |
| For stand-alone applications, this means redirection to stdout and stderr. |
| For application running within the Eclipse IDE, this means redirection to a <em>Console</em> <a href="#use-terminology-view">view</a>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Applications that only need to provide error, warning, normal, and debug textual output, the default output component interface (<code>IOutputComponent</code>) suffices. |
| Applications that want to provide additional (typed) output, should create a derived interface that inherits from <code>IOutputComponent</code>, and extends the interface with additional callback methods. |
| For an example of this, see the <code>org.eclipse.escet.cif.simulator.output.SimulatorOutputComponent</code> interface.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The <code>OutputComponentBase</code> class can be used as a base class for output components. |
| It implements the full <code>IOutputComponent</code> interface, but does nothing with the output that is generated by the application. |
| Derived classes can easily override one or more methods to process output.</p> |
| </div> |
| <div class="paragraph"> |
| <p></p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="app-framework-output-provider">Output provider</h4> |
| <div class="paragraph"> |
| <p>Each instance of an application has its own output provider. |
| The output provider keeps track of the output components that are registered, and allows sending of output to the output components through static methods.</p> |
| </div> |
| <div class="paragraph"> |
| <p>If an application uses the default <code>IOutputComponent</code> as its output interface, an instance of <code>OutputProvider<IOutputComponent></code> can be used. |
| This will suffice for most applications. |
| If an extended output component interface is defined, the <code>OutputProvider</code> class should be extended to provide additional static methods. |
| For an example of this, see the <code>org.eclipse.escet.cif.simulator.output.SimulatorOutputComponent</code> class.</p> |
| </div> |
| <div class="paragraph"> |
| <p>For details on how and where to create an instance of the output provider for an application, see the section on <a href="#app-framework-implement-your-application">how to implement your own application</a>.</p> |
| </div> |
| <div class="paragraph"> |
| <p> |
| </p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="app-framework-stdout-and-stderr">Stdout and stderr</h4> |
| <div class="paragraph"> |
| <p>Command line applications generally write output to stdout and/or stderr streams. |
| For applications running within the Eclipse IDE, those streams are connected to the Eclipse IDE as a whole, and not to the applications running within Eclipse. |
| The I/O framework solves this issue, by providing a uniform I/O interface.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The <code>org.eclipse.escet.common.app.framework.output.OutputProvider<T></code> class provides several static methods that can be used to generate output. |
| Several forms of output are supported by default:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>Error output is automatically generated by the exception framework, for uncaught exceptions. |
| It is however possible to manually generate error output, by using the <code>OutputProvider.err</code> method. |
| This could for instance be useful if multiple error messages are to be outputted.</p> |
| </li> |
| <li> |
| <p>Warning output can be generated by applications, by using the <code>OutputProvider.warn</code> method. |
| The application framework counts the number of warnings generated by an application, and the count can be retrieved using the <code>OutputProvider.getWarningCount</code> method.</p> |
| </li> |
| <li> |
| <p>Normal output can be generated by applications, by using the <code>OutputProvider.out</code> method. |
| To support structured output, the I/O frame maintains an indentation level, which can be increased and decreased one level at a time.</p> |
| </li> |
| <li> |
| <p>Debug output can be generated by applications, by using the <code>OutputProvider.dbg</code> method. |
| To support structured output, the I/O frame maintains an indentation level, which can be increased and decreased one level at a time.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>One of the default options of the application framework is the output mode option (<code>OutputModeOption</code> class). |
| It can be used to control what output gets forwarded to the output components. |
| For performance reasons, it may be useful to query whether certain output gets forwarded. |
| The <code>OutputProvider</code> class provides the <code>dowarn</code>, <code>doout</code>, and <code>dodbg</code> methods for this.</p> |
| </div> |
| <div class="paragraph"> |
| <p>It should now be clear that application should never access <code>System.out</code> and <code>System.err</code> directly. |
| Instead, they should use the output provider.</p> |
| </div> |
| <div class="paragraph"> |
| <p></p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="app-framework-stdin">Stdin</h4> |
| <div class="paragraph"> |
| <p>There is no equivalent to the <code>OutputProvider</code> for stdin. |
| Instead, use the <code>AppEnv.getStreams()</code> method to obtain the streams for the current application. |
| The <code>AppEnv.getStreams().IN</code> streams can be used to read data from the stdin stream associated with the current application.</p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="app-framework-buffering-flushing">Buffering and flushing</h4> |
| <div class="paragraph"> |
| <p>The I/O framework buffers all input and output streams by default, and also automatically performs line based flushing for output and error streams.</p> |
| </div> |
| <div class="paragraph"> |
| <p></p> |
| </div> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="app-framework-option-framework">The option framework</h3> |
| <div class="paragraph"> |
| <p>Applications often have settings, and they are generally passed as command line arguments. |
| GUI applications however, often use a dialog to configure the options instead. |
| To allow applications within the application framework to work in both scenarios, the application framework provides the option framework.</p> |
| </div> |
| <div class="paragraph"> |
| <p></p> |
| </div> |
| <div class="sect3"> |
| <h4 id="app-framework-option-class">The option class</h4> |
| <div class="paragraph"> |
| <p>All options of applications that use the application framework, should be specified as application framework options. |
| Each option is a derived class of the <code>org.eclipse.escet.common.app.framework.options.Option<T></code> class. |
| The generic type parameter <code><T></code> indicates that options are strongly typed with respect to their values.</p> |
| </div> |
| <div class="paragraph"> |
| <p> |
| |
| </p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="app-framework-cli-options-and-option-dialog">Command line options and the option dialog</h4> |
| <div class="paragraph"> |
| <p>The option framework requires all options to work via the command line, but options can also support the option dialog. |
| It is recommended for all options to support the option dialog. |
| The option framework process options as follows:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>All registered options are first initialized to their default values.</p> |
| </li> |
| <li> |
| <p>The pre-options hook for the application is fired.</p> |
| </li> |
| <li> |
| <p>The command line options are parsed.</p> |
| </li> |
| <li> |
| <p>If the command line options enabled the option dialog option (a standard application framework option that controls whether the option dialog is to be shown), the option dialog is shown. |
| The option values as processed so far, are shown to the user in this dialog. |
| The user can modify the options via the dialog and choose <b class="button">OK</b> to continue.</p> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>If the user chose <b class="button">Cancel</b> in the option dialog, terminate the application.</p> |
| </li> |
| <li> |
| <p>All registered options are reset to their default values. |
| This also clears the remaining arguments option, if any.</p> |
| </li> |
| <li> |
| <p>The options set in the dialog are parsed. |
| This overwrites the values of all options.</p> |
| </li> |
| </ul> |
| </div> |
| </li> |
| <li> |
| <p>The post-processing hook is fired for all options that have it.</p> |
| </li> |
| <li> |
| <p>All option values are checked (validated).</p> |
| </li> |
| <li> |
| <p>The post-options hook for the application is fired.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p></p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="app-framework-option-categories">Option categories</h4> |
| <div class="paragraph"> |
| <p>Options can be ordered into categories. |
| Categories can be combined into a hierarchical structure. |
| This allows the option dialog to show options per category, and allows the command line help message to show command line option help per category. |
| In both cases, this adds structure to the possibly large amount of options, and makes it easier for end users to find the option they are looking for.</p> |
| </div> |
| <div class="paragraph"> |
| <p></p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="app-framework-instantiating-options">Instantiating options</h4> |
| <div class="paragraph"> |
| <p>For every option, there may be at most one instance. |
| Therefore, never use the constructors of options directly. |
| Instead use the following:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlight"><code class="language-java" data-lang="java">Options.getInstance(MyOption.class)</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>to get an instance of an option.</p> |
| </div> |
| <div class="paragraph"> |
| <p> |
| </p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="app-framework-getting-setting-option-values">Getting and setting option values</h4> |
| <div class="paragraph"> |
| <p>Applications don’t have access to the command line arguments. |
| The option framework automatically process the command line arguments based on the options registered for the application. |
| Applications always retrieve the values of options through static methods defined in the option classes.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Options are usually set via command line arguments, or via the option dialog. |
| It is however also possible to set option values at run-time:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlight"><code class="language-java" data-lang="java">Options.set(MyOption.class, <value>);</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p></p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="app-framework-option-processing-order">Option processing order</h4> |
| <div class="paragraph"> |
| <p>If possible, options should not depend on the order in which they are parsed. |
| If the value of one option depends on the value of another option, use the post-processing hook to achieve consistency.</p> |
| </div> |
| <div class="paragraph"> |
| <p></p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="app-framework-cli-option-syntax">Command line option syntax</h4> |
| <div class="paragraph"> |
| <p>All options have a long form (<code>--option</code>), optionally with a value (<code>--option=VALUE</code>). |
| They can also have short form (<code>-o</code>), optionally with a value (<code>-oVALUE</code> or <code>-o VALUE</code>). |
| All arguments that do not start with a dash symbol (<code>-</code>) are considered to be the 'remaining arguments'. |
| It is possible to register one option that processes those remaining arguments. |
| Such special options have <code>*</code> as long option name.</p> |
| </div> |
| <div class="paragraph"> |
| <p></p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="app-framework-implement-new-options">Implementing your own options</h4> |
| <div class="paragraph"> |
| <p>Simply derive from the <code>Option</code> class, and study its API to implement your own options. |
| You can also look at existing options for best practices. |
| Furthermore, the option framework provides several options that can be used in applications:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><code>BooleanOption</code>: convenience base class for boolean options.</p> |
| </li> |
| <li> |
| <p><code>FilesOption</code>: multiple remaining arguments input file paths option.</p> |
| </li> |
| <li> |
| <p><code>InputFileOption</code>: single remaining argument input file path option.</p> |
| </li> |
| <li> |
| <p><code>OutputFileOption</code>: output file path option (<code>--output</code> / <code>-o</code>).</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p> |
| |
| |
| |
| |
| |
| </p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="app-framework-standard-options">Standard options</h4> |
| <div class="paragraph"> |
| <p>The application framework provides several options that must be registered for every application:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><code>DevModeOption</code>: option to enable/disable development mode. |
| Developers can enable this option to get stack traces in case of internal exceptions, instead of crash reports. |
| See also the chapter on the exception framework.</p> |
| </li> |
| <li> |
| <p><code>HelpOption</code>: option to show the application help text at the console.</p> |
| </li> |
| <li> |
| <p><code>LicenseOption</code>: option to print the license text of the application at the console, and terminate the application.</p> |
| </li> |
| <li> |
| <p><code>OptionDialogOption</code>: option to show the option dialog.</p> |
| </li> |
| <li> |
| <p><code>OutputModeOption</code>: option to control the amount of output produced by the application. |
| See also the <a href="#app-framework-io-framework">I/O framework</a> section.</p> |
| </li> |
| <li> |
| <p><code>GuiOption</code>: option to disable the GUI (enabled headless execution mode). |
| See also the section on <a href="#app-framework-guis-and-swt">GUIs and SWT</a>.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>See also the section on <a href="#app-framework-implement-your-application">how to implement your own application</a>.</p> |
| </div> |
| <div class="paragraph"> |
| <p></p> |
| </div> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="app-framework-compiler-framework">The compiler framework</h3> |
| <div class="paragraph"> |
| <p>For performance reasons, it can be better to generate and compile code at runtime, than to use an interpreter. |
| The Java compiler supports this. |
| However, in an Eclipse/OSGi environment, some additional effort is required to make it all work. |
| The application framework contains a compiler framework in the <code>org.eclipse.escet.common.app.framework.javacompiler</code> package. |
| It supports in-memory compilation of in-memory code, with full transparent OSGi support. |
| That is, whether used from inside the Eclipse IDE, or from a stand-alone application, the compiler framework takes care of the details. |
| The framework supports various representations of in-memory code, and can be extended with additional representations.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The compiler framework requires the use of a Java Development Kit (JDK). |
| A Java Runtime Environment (JRE) is not sufficient.</p> |
| </div> |
| <div class="paragraph"> |
| <p></p> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="app-framework-implement-your-application">How to implement your own application</h3> |
| <div class="paragraph"> |
| <p>This section more or less explains step by step how to implement your own application, by using the application framework.</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>Decide whether it is enough to use the <code>IOutputComponent</code> interface, or that you need more. |
| See also the <a href="#app-framework-io-framework">I/O framework</a> section.</p> |
| </li> |
| <li> |
| <p>Create a new class, deriving from <code>Application</code>.</p> |
| </li> |
| <li> |
| <p>Add a <code>main</code> method to your application class. |
| For instance:</p> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlight"><code class="language-java" data-lang="java">/** |
| * Application main method. |
| * |
| * @param args The command line arguments supplied to the application. |
| */ |
| public static void main(String[] args) { |
| MyApp app = new MyApp(); |
| app.run(args); |
| }</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>This allows for standalone execution.</p> |
| </div> |
| </li> |
| <li> |
| <p>Add constructors as needed. |
| You’ll probably want to implement some or most of the constructors provided by the <code>Application</code> class. |
| In order to support standalone execution, the following constructor is required:</p> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlight"><code class="language-java" data-lang="java">/** Constructor for the {@link MyApp} class. */ |
| public MyApp() { |
| // Nothing to do here. |
| }</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>In order to support the ToolDef <code>app</code> tool, which can be used to run application framework applications from ToolDef scripts, the following constructor is required:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlight"><code class="language-java" data-lang="java">/** |
| * Constructor for the {@link MyApp} class. |
| * |
| * @param streams The streams to use for input, output, and error streams. |
| */ |
| public MyApp(AppStreams streams) { |
| super(streams); |
| }</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>This constructor is also required by the <code>ChildAppStarter</code> class, to support starting one application framework application from another application framework application.</p> |
| </div> |
| </li> |
| <li> |
| <p>Implement the mandatory methods <code>getAppName</code> and <code>getAppDescription</code>.</p> |
| </li> |
| <li> |
| <p>Implement mandatory method <code>getProvider</code>. |
| If you use <code>IOutputComponent</code>, then you can implement it as follows:</p> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlight"><code class="language-java" data-lang="java">return new OutputProvider<>();</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>If you don’t use <code>IOutputComponent</code>, return a new instance of a derived class of <code>OutputProvider</code> that implements the derived interface of <code>IOutputComponent</code>.</p> |
| </div> |
| </li> |
| <li> |
| <p>If you don’t use <code>IOutputComponent</code>, override the <code>getStreamOutputComponent</code> method, and return a new instance of a derived class of <code>StreamOutputComponent</code> that implements the derived interface of <code>IOutputComponent</code>. |
| Such a class usually ignores all other output, and thus behaves exactly as <code>StreamOutputComponent</code>, but implements the full output interface of the application.</p> |
| </li> |
| <li> |
| <p>Implement mandatory method <code>getAllOptions</code>. |
| You’ll need to return an option category that wraps the actual option categories of the application. |
| Use the <code>getGeneralOptionCategory</code> to obtain the default application options category, which must always be the first category of options for your application. |
| An example of an implementation of this method:</p> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlight"><code class="language-java" data-lang="java">@Override |
| @SuppressWarnings("rawtypes") |
| protected OptionCategory getAllOptions() { |
| OptionCategory generalOpts = getGeneralOptionCategory(); |
| |
| OptionCategory debugOpts = |
| new OptionCategory("Debug", "Debugging options.", list(), |
| list(Options.getInstance(DebugOption.class))); |
| |
| OptionCategory options = |
| new OptionCategory("My Application Options", |
| "All options for My Application.", |
| list(generalOpts, debugOpts), list()); |
| |
| return options; |
| }</code></pre> |
| </div> |
| </div> |
| </li> |
| <li> |
| <p>Implement mandatory method <code>runInternal</code> with the actual application code.</p> |
| </li> |
| <li> |
| <p>Override optional method <code>getHelpMessageNotes</code> if applicable.</p> |
| </li> |
| <li> |
| <p>Override optional methods <code>preOptions</code> and <code>postOptions</code> if applicable.</p> |
| </li> |
| <li> |
| <p>Override optional method <code>getAppVersion</code> if applicable.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="sect3"> |
| <h4 id="app-framework-runinternal-method">The runInternal method</h4> |
| <div class="paragraph"> |
| <p>Some things to consider when implementing the <code>runInternal</code> method:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>If you want to support stand-alone execution, register all Eclipse Modeling Framework (EMF) metamodels with the EMF metamodel registry. |
| Also register any parsers, constraints, etc. |
| For instance:</p> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlight"><code class="language-java" data-lang="java">if (!Platform.isRunning()) { |
| // Register languages and parsers for stand-alone execution. |
| LanguageRegistry.register...(...) |
| }</code></pre> |
| </div> |
| </div> |
| </li> |
| <li> |
| <p>The start of the <code>runInternal</code> method is a good place to add output components, as all options have been fully processed at this point. |
| Output components can be registered by using the application’s output provider (though static methods).</p> |
| </li> |
| <li> |
| <p>The code in this method and all code directly or indirectly executed by this method, should regularly call the <code>AppEnv.isTerminationRequested</code> method, to find out whether the application should be terminated.</p> |
| </li> |
| <li> |
| <p>For the return code of this method, always use value zero, to indicate successful termination. |
| Other exit codes are automatically generated by the exception framework, if applicable. |
| See also the <a href="#app-framework-exit-codes">exit codes</a> section.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p></p> |
| </div> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="app-framework-registration">Application registration</h3> |
| <div class="paragraph"> |
| <p>Applications that use the application framework maintain their own data. |
| This includes options, output components (via an output provider), streams, etc. |
| Only a single application can be registered for each thread. |
| Only once the application terminates and automatically unregisters itself, can a new application register itself in that thread. |
| To run multiple applications in parallel, simply run them on different threads.</p> |
| </div> |
| <div class="paragraph"> |
| <p> |
| </p> |
| </div> |
| <div class="sect3"> |
| <h4 id="app-framework-multi-threaded-apps">Multi-threaded applications</h4> |
| <div class="paragraph"> |
| <p>All data stored for the application is wrapped in the <code>AppEnvData</code> class, and stored by the <code>AppEnv</code> class, on a per-thread basis. |
| If your application uses multiple threads, you need to register each thread with the application framework. |
| Use the <code>AppEnv.registerThread</code> method for this. |
| This method requires the current application environment data as parameter, which may be obtained by using the <code>AppEnv.getData</code> method. |
| To avoid managed memory leaks, always unregister threads once they are no longer used, by using the <code>AppEnv.unregisterThread</code> method.</p> |
| </div> |
| <div class="paragraph"> |
| <p></p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="app-framework-unit-tests">Unit tests</h4> |
| <div class="paragraph"> |
| <p>If unit tests use methods that depend on the application being registered, then the unit test will need to register an application. |
| Examples of method using the application framework are methods that use options, or produce output via the application framework. |
| Especially for unit tests, the <code>AppEnv.registerSimple</code> method can be used to register a dummy application. |
| This method uses a default application environment, without an actual application, registers a default stream output provider, sets the output mode to errors and warnings only (no normal or debug output), and disables development mode. |
| It can be used in a unit test class as follows:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlight"><code class="language-java" data-lang="java">/***/ @BeforeClass |
| public static void oneTimeSetUp() { |
| AppEnv.registerSimple(); |
| } |
| |
| /***/ @AfterClass |
| public static void oneTimeTearDown() { |
| AppEnv.unregisterApplication(); |
| }</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>If any options are used, they will need to be available as well. |
| For instance, one could add the following to the <code>oneTimeSetUp</code> method, or at the start of the actual unit test method:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlight"><code class="language-java" data-lang="java">Options.set(SomeOption.class, <value>);</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p></p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="app-framework-running-app-from-other-app">Running an application from another application</h4> |
| <div class="paragraph"> |
| <p>As noted above, only a single application can be registered for a single thread. |
| To start one application from another application, simply run the second application in a fresh thread. |
| In the new thread, do the following:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>Construct the child application, using a constructor with the <code>AppStreams</code> argument, to pass along the streams from the parent application.</p> |
| </li> |
| <li> |
| <p>Set the current working directory to the current working directory of the parent application.</p> |
| </li> |
| <li> |
| <p>Obtain the Eclipse IDE console (if any) from the parent application, and couple it the child application.</p> |
| </li> |
| <li> |
| <p>Run the child application.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>After the child application thread finishes, make sure you:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>Restore the coupling between the Eclipse IDE console (if any) and the parent application.</p> |
| </li> |
| <li> |
| <p>If the child application finished due to a termination request, request termination for the parent application.</p> |
| </li> |
| <li> |
| <p>Decide what to do with the exit code of the child application. |
| If it is non-zero, you’ll probably want to terminate the parent application.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>To make it easier to follow this approach, the <code>ChildAppStarter.exec</code> methods can be used.</p> |
| </div> |
| <div class="paragraph"> |
| <p></p> |
| </div> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="app-framework-execution">Execution</h3> |
| <div class="paragraph"> |
| <p>Application framework applications can be executed in the following ways:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>As plain Java application, from the command line.</p> |
| <div class="paragraph"> |
| <p>Using the <em>GUI</em> option, the application can be executed either with full GUI support, or as headless application.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The OSGi framework will not be running, and the Eclipse workbench will not be available.</p> |
| </div> |
| </li> |
| <li> |
| <p>As application within the Eclipse IDE, with full GUI support.</p> |
| <div class="paragraph"> |
| <p>The OSGi framework will be running, and the Eclipse workbench will be available.</p> |
| </div> |
| </li> |
| <li> |
| <p>As headless Eclipse application.</p> |
| <div class="paragraph"> |
| <p>Using the <em>GUI</em> option, the application can be executed either with full GUI support, or as headless application.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The OSGi framework will be running, but the Eclipse workbench will not be available.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The <code>org.eclipse.escet.common.app.framework.AppEclipseApplication</code> application can be provided to the <code>-application</code> command line argument of Eclipse to start any application framework application. |
| This functionality is implemented by the <code>org.eclipse.escet.common.app.framework.AppEclipseApplication</code> which provides a generic implementation of Eclipse’s <code>IApplication</code> interface that supports execution of any application framework application.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The following command line arguments are expected:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>The name of the plug-in (OSGi bundle) that provides the application.</p> |
| </li> |
| <li> |
| <p>The full/absolute name of the Java class that implements the application. |
| Must extend the <code>Application</code> class and have a parameterless constructor.</p> |
| </li> |
| <li> |
| <p>The remaining command line arguments are the command line arguments for the application itself.</p> |
| </li> |
| </ul> |
| </div> |
| </li> |
| </ul> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="rail-chapter-index">Rail diagram generator</h2> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p>The Eclipse ESCET rail diagram generator makes it easy to generate pretty and simple to understand syntax specifications. |
| The following topics explain the rail diagram generator in more detail:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="#rail-introduction">Introduction</a></p> |
| </li> |
| <li> |
| <p><a href="#rail-examples">Examples</a></p> |
| </li> |
| <li> |
| <p><a href="#rail-customizing-output">Customizing output</a></p> |
| </li> |
| <li> |
| <p><a href="#rail-lexical-syntax">Lexical syntax</a></p> |
| </li> |
| <li> |
| <p><a href="#rail-grammar">Grammar</a></p> |
| </li> |
| </ul> |
| </div> |
| <div class="sect2"> |
| <h3 id="rail-introduction">Introduction</h3> |
| <div class="paragraph"> |
| <p>Making pretty syntax specifications easy.</p> |
| </div> |
| <div class="paragraph"> |
| <p>For languages, an often used specification of the grammar of the language in a user manual is some form of (E)BNF rules. |
| However for people not used to reading them, it may be hard to understand what the rules say.</p> |
| </div> |
| <div class="paragraph"> |
| <p>An alternative is to use <a href="https://en.wikipedia.org/wiki/Syntax_diagram">syntax diagrams</a> also known as <em>railroad diagrams</em>. |
| These diagrams are often easier to understand for users that do not know (E)BNF.</p> |
| </div> |
| <div class="paragraph"> |
| <p>A disadvantage of the syntax diagrams is that the diagrams have to be created. |
| For a full language the number of diagrams can grow to over 50 pictures. |
| To reduce the effort in creating them, tools have been developed by several persons. |
| The tools vary in required program environment, accepted input, and quality of the output.</p> |
| </div> |
| <div class="paragraph"> |
| <p>We are very fond of the <a href="https://www.ctan.org/pkg/rail">CTAN rail package</a>. |
| It is written in TeX, and uses a C program to parse its input. |
| We used it for all our languages. |
| It is very good for creating diagrams in PDF documents, but much less useful in an Eclipse environment with online help web pages. |
| Competitors did not seem to fit much better either, so the decision was made to make a Java program that behaves in much the same way as the <em>CTAN rail package</em>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Files containing input for the Eclipse ESCET rail diagram generator use a <code>.rr</code> file extension by convention.</p> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="rail-examples">Examples</h3> |
| <div class="paragraph"> |
| <p>Here a number of examples are provided for those that hate reading. |
| The input of the program is similar to EBNF with an extra feature for repetition.</p> |
| </div> |
| <div class="sect3"> |
| <h4 id="rail-diagrams-and-sequences">Diagrams and sequences</h4> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlight"><code class="language-raildiagram" data-lang="raildiagram">DiagramName : A B C |
| ;</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>A diagram starts with its name, a colon, the syntax that should be shown (in this case the sequence <code>A</code>, <code>B</code>, <code>C</code>), and finally, a semicolon as terminator. |
| This gives the following result.</p> |
| </div> |
| <div class="imageblock"> |
| <div class="content"> |
| <img src="./rail/sequence.png" alt="Sequence"> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>As rail diagrams are read from left to right, following a line without taking a sharp turn, the resulting image is not a surprise.</p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="rail-choices">Choices</h4> |
| <div class="paragraph"> |
| <p>The second primitive is choice, where you pick one of the given alternatives. |
| As with EBNF, this is written with the pipe symbol <code>|</code>, like:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlight"><code class="language-raildiagram" data-lang="raildiagram">OneOfThem : A | B C | D ;</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>This results in:</p> |
| </div> |
| <div class="imageblock"> |
| <div class="content"> |
| <img src="./rail/choice.png" alt="Choice"> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Note that as sequence has higher priority than choice, the <code>B</code> and <code>C</code> sequence forms one alternative. |
| You can use parentheses to break the priority chain, e.g.:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlight"><code class="language-raildiagram" data-lang="raildiagram">SequentialChoice : ( A | B ) ( C | D ) ;</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>This gives a sequence of choices:</p> |
| </div> |
| <div class="imageblock"> |
| <div class="content"> |
| <img src="./rail/choice2.png" alt="Sequence of choice"> |
| </div> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="rail-optional">Optional</h4> |
| <div class="paragraph"> |
| <p>An optional part of the syntax can be described in multiple ways:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlight"><code class="language-raildiagram" data-lang="raildiagram">OptionalA1: () | A; |
| |
| OptionalA2: A? ;</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>This results in:</p> |
| </div> |
| <div class="imageblock"> |
| <div class="content"> |
| <img src="./rail/optional.png" alt="Optional"> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>It should be clear that using the dedicated optional syntax (<code>?</code>) is often more convenient than using the choice syntax.</p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="rail-repetition">Repetition</h4> |
| <div class="paragraph"> |
| <p>The core repetition primitive is alternating between two nodes:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlight"><code class="language-raildiagram" data-lang="raildiagram">Alternating : A + B ;</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>This results in:</p> |
| </div> |
| <div class="imageblock"> |
| <div class="content"> |
| <img src="./rail/alternating.png" alt="Alternating between A and B"> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>You can make one (or both) of the paths empty, which results in the normal EBNF repetition semantics. |
| Below, node <code>A</code> must occur at least once, while node <code>B</code> may also be skipped.</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlight"><code class="language-raildiagram" data-lang="raildiagram">EmptyAlternating : ( A + () ) |
| ( () + B ) |
| ( () | ( B + () ) ) ;</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>This gives:</p> |
| </div> |
| <div class="imageblock"> |
| <div class="content"> |
| <img src="./rail/emptyalternating.png" alt="A+ and B*"> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>The third repetition is an alternative for the <code>B</code> sequence. |
| It avoids the caveat with repetition due to the right-to-left visiting order of the bottom path, made more clearly visible in the following example:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlight"><code class="language-raildiagram" data-lang="raildiagram">ABCD : (A B) + (C D) ;</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>It results in:</p> |
| </div> |
| <div class="imageblock"> |
| <div class="content"> |
| <img src="./rail/abcd.png" alt="ABCD"> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>It describes EBNF <code>AB(CDAB)*</code>, and the tool translates it correctly, but the bottom path does not read nicely, as you have to read that part from right to left.</p> |
| </div> |
| <div class="paragraph"> |
| <p>It is advised to avoid this case by changing the diagram. |
| Limit the second part of the <code>+</code> operator to one node, possibly by introducing an additional non-terminal.</p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="rail-splitting-long-sequences">Splitting long sequences</h4> |
| <div class="paragraph"> |
| <p>For rules that have a long sequence, the width of the diagram grows quickly beyond the width of the page. |
| The best way to deal with that is to change the diagram, for example by moving a part of the sequence to a new non-terminal.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The program however does offer a quick fix around the problem at the cost of a less readable diagram. |
| An example is shown below:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlight"><code class="language-raildiagram" data-lang="raildiagram">Abcdefgh : A B \\ |
| D E F \\ |
| G \\ |
| H |
| ;</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>This gives:</p> |
| </div> |
| <div class="imageblock"> |
| <div class="content"> |
| <img src="./rail/abcdefgh.png" alt="ABCDEFGH"> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>The double backslash breaks the ‘line’ and it continues below on the next line. |
| You cannot break the empty sequence, and each row must have at least one node.</p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="rail-referencing-a-path-in-the-diagram">Referencing a path in the diagram</h4> |
| <div class="paragraph"> |
| <p>When explaining a diagram, it can be useful to refer to a path in the diagram. |
| The program has a bracketed string for that:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlight"><code class="language-raildiagram" data-lang="raildiagram">Recursion : [nest] Recursion |
| | [exit] () |
| ;</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Now you can say that the <code>[nest]</code> path recursively applies the rule, while the <code>[exit]</code> path ends the recursion.</p> |
| </div> |
| <div class="imageblock"> |
| <div class="content"> |
| <img src="./rail/refpath.png" alt="Recursion"> |
| </div> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="rail-terminals-and-meta-terminals">Terminals and meta-terminals</h4> |
| <div class="paragraph"> |
| <p>Until now, all names in the diagrams are considered to be non-terminals. |
| This is the default behavior. |
| Terminals in the diagram do not have a name, but show the concrete syntax instead. |
| There are three ways to write terminals.</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlight"><code class="language-raildiagram" data-lang="raildiagram">Terminals : 'single' |
| | "double" |
| | OTHER |
| | Identifier |
| ;</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>The first and second option are simply writing the literal text inside single or double quotes. |
| There are no escape sequences for special characters here. |
| The third option is to use the name of a terminal, in this case <code>OTHER</code>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The <code>Identifier</code> alternative in the diagram is a hybrid. |
| It represent all valid identifiers in the input. |
| The diagram however does not state its exact syntax as with normal terminals. |
| It is also not exactly a non-terminal. |
| The program has a third class of tokens for these, known as <em>meta-terminals</em>. |
| It allows the designer to attach a different layout to such tokens.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The <code>OTHER</code> and <code>Identifier</code> names in the input file need a translation to displayed text. |
| This translation is specified in a properties file like:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlight"><code class="language-properties" data-lang="properties">terminal.token.OTHER: else |
| meta-terminal.token.Identifier: Name</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>The result is shown below. |
| By default, terminals and meta-terminals are rendered using rounded boxes. |
| If this behavior is not desired, layout and many other settings can be overridden in the properties file, see the <a href="#rail-customizing-output">Customizing output</a> section for details.</p> |
| </div> |
| <div class="imageblock"> |
| <div class="content"> |
| <img src="./rail/terminals.png" alt="Terminals"> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="rail-customizing-output">Customizing output</h3> |
| <div class="paragraph"> |
| <p>The program can take a properties file to translate terminals and non-terminals. |
| The same file can also contain settings to modify shape, color, fonts, and spacing of almost everything.</p> |
| </div> |
| <div class="sect3"> |
| <h4 id="rail-property-syntax">Syntax of the properties file</h4> |
| <div class="paragraph"> |
| <p>The properties file used by the program is a normal Java properties file. |
| Its syntax is described in the <a href="https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/util/Properties.html#load(java.io.Reader)">Java 11 API Specification</a>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>In short:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>It is a file format that consists of lines of text.</p> |
| </li> |
| <li> |
| <p>Empty lines are allowed and are skipped.</p> |
| </li> |
| <li> |
| <p>Lines beginning with <code>#</code> or <code>!</code> are considered to be comment lines and are ignored.</p> |
| </li> |
| <li> |
| <p>Data lines contain key/value pairs.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>Here, a key of a data line is a sequence of words, separated by a dot, for example, <code>terminal.token.Identifier</code>. |
| The key is followed by an optional but recommended separator character, either <code>:</code> or <code>=</code>. |
| The remainder of the line is the value part, where leading and trailing white space is removed.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The properties file format uses <code>\</code> as continuation character to the next line and also as escape character.</p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="rail-kinds-of-values">Kinds of values</h4> |
| <div class="paragraph"> |
| <p>In the tables below, the properties keys recognized by the program are listed along with an example and an expected value.</p> |
| </div> |
| <div class="paragraph"> |
| <p>This table lists the used expected values, and gives some more information about them.</p> |
| </div> |
| <table class="tableblock frame-all grid-all stretch"> |
| <colgroup> |
| <col style="width: 20%;"> |
| <col style="width: 20%;"> |
| <col style="width: 60%;"> |
| </colgroup> |
| <thead> |
| <tr> |
| <th class="tableblock halign-left valign-top">Type name</th> |
| <th class="tableblock halign-left valign-top">Examples</th> |
| <th class="tableblock halign-left valign-top">Description</th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Boolean</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>yes</code>, <code>true</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Boolean value to enable or disable a flag.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">RGB color</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>151 7 230</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Three integer numbers between <code>0</code> and <code>255</code> inclusive, separated by spaces.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Real</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>0.31</code><br> |
| <code>10</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Real value, usually with ‘pixel’ unit. |
| Note that as the output medium is limited in handling fractions, best results are usually obtained with integer values only.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Font name</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>Serif</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Name of the font to use. |
| The program currently supports the <code>Dialog</code>, <code>DialogInput</code>, <code>Monospaced</code>, <code>Serif</code>, and <code>SansSerif</code> fonts.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Font height</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>12</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Integer number specifying the point size of the font.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Font style</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>plain</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Style of the font. |
| The program currently supports <code>plain</code>, <code>bold</code>, and <code>italics</code> styles.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Text</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>literal</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Arbitrary text to display for a token.</p></td> |
| </tr> |
| </tbody> |
| </table> |
| </div> |
| <div class="sect3"> |
| <h4 id="rail-global-settings">Global settings</h4> |
| <div class="paragraph"> |
| <p>The following settings affect background and the rail line.</p> |
| </div> |
| <table class="tableblock frame-all grid-all stretch"> |
| <colgroup> |
| <col style="width: 20%;"> |
| <col style="width: 20%;"> |
| <col style="width: 60%;"> |
| </colgroup> |
| <thead> |
| <tr> |
| <th class="tableblock halign-left valign-top">Property name</th> |
| <th class="tableblock halign-left valign-top">Value type</th> |
| <th class="tableblock halign-left valign-top">Description</th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>diagram.background.color</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">RGB color</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Color of the background of the generated image.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>rail.linewidth</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Real</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Width of the rail line.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>rail.color</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">RGB color</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Color of the rail line.</p></td> |
| </tr> |
| </tbody> |
| </table> |
| </div> |
| <div class="sect3"> |
| <h4 id="rail-diagram-settings">Diagram settings</h4> |
| <div class="paragraph"> |
| <p>The diagram settings configure the global layout of an image. |
| At the top is a header line with the name of the rule, below it are one or more railroad pictures with some additional rail at both ends.</p> |
| </div> |
| <table class="tableblock frame-all grid-all stretch"> |
| <colgroup> |
| <col style="width: 33.3333%;"> |
| <col style="width: 16.6666%;"> |
| <col style="width: 50.0001%;"> |
| </colgroup> |
| <thead> |
| <tr> |
| <th class="tableblock halign-left valign-top">Property name</th> |
| <th class="tableblock halign-left valign-top">Value type</th> |
| <th class="tableblock halign-left valign-top">Description</th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>rule.padding.top</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Real</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Amount of space above the header line.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>rule.padding.left</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Real</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Amount of space left of the header line.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>rule.padding.bottom</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Real</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Amount of space between the last railroad picture and the bottom of the diagram.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>rule.padding.right</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Real</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Minimum amount of space right of the header line.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>rule.diagram.padding.top</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Real</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Amount of space above each railroad picture.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>rule.diagram.padding.left</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Real</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Amount of space left of each railroad picture.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>rule.diagram.lead.width</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Real</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Horizontal length of the rail line before the railroad picture.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>rule.diagram.trail.width</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Real</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Horizontal length of the rail line after the railroad picture.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>diagram-header.text.color</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">RGB color</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Color of the diagram header text.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>diagram-header.text.font</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Font name</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Font of the diagram header text.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>diagram-header.text.font.size</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Font height</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Font size in points of the diagram header text.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>diagram-header.text.font.style</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Font style</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Style of the diagram header text.</p></td> |
| </tr> |
| </tbody> |
| </table> |
| </div> |
| <div class="sect3"> |
| <h4 id="rail-empty-node">Empty node</h4> |
| <div class="paragraph"> |
| <p>Each kind of node has a number of settings as well, starting with the simplest node, <code>()</code>.</p> |
| </div> |
| <table class="tableblock frame-all grid-all stretch"> |
| <colgroup> |
| <col style="width: 33.3333%;"> |
| <col style="width: 16.6666%;"> |
| <col style="width: 50.0001%;"> |
| </colgroup> |
| <thead> |
| <tr> |
| <th class="tableblock halign-left valign-top">Property name</th> |
| <th class="tableblock halign-left valign-top">Value type</th> |
| <th class="tableblock halign-left valign-top">Description</th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>empty.width</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Real</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Horizontal length of the empty node.</p></td> |
| </tr> |
| </tbody> |
| </table> |
| </div> |
| <div class="sect3"> |
| <h4 id="rail-branch-label">Branch label</h4> |
| <div class="paragraph"> |
| <p>The bracketed string <code>[refname]</code> node configuration settings are listed below.</p> |
| </div> |
| <table class="tableblock frame-all grid-all stretch"> |
| <colgroup> |
| <col style="width: 33.3333%;"> |
| <col style="width: 16.6666%;"> |
| <col style="width: 50.0001%;"> |
| </colgroup> |
| <thead> |
| <tr> |
| <th class="tableblock halign-left valign-top">Property name</th> |
| <th class="tableblock halign-left valign-top">Value type</th> |
| <th class="tableblock halign-left valign-top">Description</th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>branch-label.padding.left</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Real</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Amount of space at the left of the label text.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>branch-label.padding.right</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Real</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Amount of space at the right of the label text.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>branch-label.padding.top</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Real</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Amount of space above the label text.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>branch-label.padding.bottom</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Real</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Amount of space between the label text and the rail line.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>branch-label.min-width</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Real</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Minimum horizontal length of the label node.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>branch-label.text.color</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">RGB color</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Color of the label text.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>branch-label.text.font</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Font name</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Font used for the label text.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>branch-label.text.font.size</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Font height</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Font size in pt of the label text.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>branch-label.text.font.style</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Font style</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Font style of the label text.</p></td> |
| </tr> |
| </tbody> |
| </table> |
| </div> |
| <div class="sect3"> |
| <h4 id="rail-name-node">Name node</h4> |
| <div class="paragraph"> |
| <p>A name node is a string of text within a box. |
| The text is often a single name, and the box may have rounded corners. |
| At the left and right of the box, a rail line is connected.</p> |
| </div> |
| <div class="paragraph"> |
| <p>First the configuration of the rail lines, followed by the configuration settings of the box and the text.</p> |
| </div> |
| <table class="tableblock frame-all grid-all stretch"> |
| <colgroup> |
| <col style="width: 33.3333%;"> |
| <col style="width: 16.6666%;"> |
| <col style="width: 50.0001%;"> |
| </colgroup> |
| <thead> |
| <tr> |
| <th class="tableblock halign-left valign-top">Property name</th> |
| <th class="tableblock halign-left valign-top">Value type</th> |
| <th class="tableblock halign-left valign-top">Description</th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>name.rail.entry.width</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Real</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Horizontal length of the rail line at the left of the box.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>name.rail.exit.width</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Real</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Horizontal length of the rail line at the right of the box.</p></td> |
| </tr> |
| </tbody> |
| </table> |
| <div class="paragraph"> |
| <p>There are three configurations for name and box. |
| One for terminals, one for meta-terminals, and one for non-terminals. |
| The structure of the settings is the same for all three, their default values are a little different, in particular in choices of corner radius and font.</p> |
| </div> |
| <div class="sect4"> |
| <h5 id="rail-terminal-text-and-box-properties">Terminal text and box properties</h5> |
| <table class="tableblock frame-all grid-all stretch"> |
| <colgroup> |
| <col style="width: 33.3333%;"> |
| <col style="width: 16.6666%;"> |
| <col style="width: 50.0001%;"> |
| </colgroup> |
| <thead> |
| <tr> |
| <th class="tableblock halign-left valign-top">Property name</th> |
| <th class="tableblock halign-left valign-top">Value type</th> |
| <th class="tableblock halign-left valign-top">Description</th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>terminal.name.padding.horizontal</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Real</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Amount of horizontal space between the text and the box around the text.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>terminal.name.padding.vertical</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Real</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Amount of vertical space between the text and the box around the text.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>terminal.corner.radius</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Real</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Radius of the corners of the box. |
| <code>0</code> means a rectangular box.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>terminal.box.color</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">RGB color</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Color of the line of the box.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>terminal.box.linewidth</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Real</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Width of the line of the box.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>terminal.text.color</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">RGB color</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Color of the terminal text.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>terminal.text.font</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Font name</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Font used for the terminal text.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>terminal.text.font.size</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Font height</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Height of the terminal text.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>terminal.text.font.style</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Font style</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Style of the terminal text.</p></td> |
| </tr> |
| </tbody> |
| </table> |
| </div> |
| <div class="sect4"> |
| <h5 id="rail-meta-terminal-text-and-box-properties">Meta-terminal text and box properties</h5> |
| <table class="tableblock frame-all grid-all stretch"> |
| <colgroup> |
| <col style="width: 33.3333%;"> |
| <col style="width: 16.6666%;"> |
| <col style="width: 50.0001%;"> |
| </colgroup> |
| <thead> |
| <tr> |
| <th class="tableblock halign-left valign-top">Property name</th> |
| <th class="tableblock halign-left valign-top">Value type</th> |
| <th class="tableblock halign-left valign-top">Description</th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>meta-terminal.name.padding.horizontal</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Real</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Amount of horizontal space between the text and the box around the text.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>meta-terminal.name.padding.vertical</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Real</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Amount of vertical space between the text and the box around the text.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>meta-terminal.corner.radius</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Real</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Radius of the corners of the box. |
| <code>0</code> means a rectangular box.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>meta-terminal.box.color</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">RGB color</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Color of the line of the box.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>meta-terminal.box.linewidth</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Real</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Width of the line of the box.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>meta-terminal.text.color</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">RGB color</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Color of the meta-terminal text.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>meta-terminal.text.font</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Font name</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Font used for the meta-terminal text.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>meta-terminal.text.font.size</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Font height</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Height of the meta-terminal text.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>meta-terminal.text.font.style</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Font style</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Style of the meta-terminal text.</p></td> |
| </tr> |
| </tbody> |
| </table> |
| </div> |
| <div class="sect4"> |
| <h5 id="rail-non-terminal-text-and-box-properties">Non-terminal text and box properties</h5> |
| <table class="tableblock frame-all grid-all stretch"> |
| <colgroup> |
| <col style="width: 33.3333%;"> |
| <col style="width: 16.6666%;"> |
| <col style="width: 50.0001%;"> |
| </colgroup> |
| <thead> |
| <tr> |
| <th class="tableblock halign-left valign-top">Property name</th> |
| <th class="tableblock halign-left valign-top">Value type</th> |
| <th class="tableblock halign-left valign-top">Description</th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>nonterminal.name.padding.horizontal</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Real</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Amount of horizontal space between the text and the box around the text.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>nonterminal.name.padding.vertical</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Real</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Amount of vertical space between the text and the box around the text.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>nonterminal.corner.radius</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Real</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Radius of the corners of the box. |
| <code>0</code> means a rectangular box.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>nonterminal.box.color</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">RGB color</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Color of the line of the box.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>nonterminal.box.linewidth</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Real</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Width of the line of the box.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>nonterminal.text.color</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">RGB color</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Color of the non-terminal text.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>nonterminal.text.font</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Font name</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Font used for the non-terminal text.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>nonterminal.text.font.size</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Font height</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Height of the non-terminal text.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>nonterminal.text.font.style</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Font style</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Style of the non-terminal text.</p></td> |
| </tr> |
| </tbody> |
| </table> |
| </div> |
| <div class="sect4"> |
| <h5 id="rail-token-text-translations">Token text translations</h5> |
| <div class="paragraph"> |
| <p>In the diagram input files, token names may be used, but terminals often contain other symbols. |
| The translation between the token name and the text it should display can also be configured.</p> |
| </div> |
| <div class="paragraph"> |
| <p>There are three groups of settings. |
| Different settings within a group only differ in the name of the token that they translate. |
| Such a name is listed here as <code><token-name></code>.</p> |
| </div> |
| <table class="tableblock frame-all grid-all stretch"> |
| <colgroup> |
| <col style="width: 28.5714%;"> |
| <col style="width: 14.2857%;"> |
| <col style="width: 57.1429%;"> |
| </colgroup> |
| <thead> |
| <tr> |
| <th class="tableblock halign-left valign-top">Property name</th> |
| <th class="tableblock halign-left valign-top">Value type</th> |
| <th class="tableblock halign-left valign-top">Description</th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>terminal.token.<token-name></code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Text</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">The literal text to display in the diagram for terminal token <code><token-name></code>.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>meta-terminal.<token-name></code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Text</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">The literal text to display in the diagram for meta-terminal token <code><token-name></code>.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>nonterminal.token.<token-name></code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Text</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">The literal text to display in the diagram for non-terminal token <code><token-name></code>.</p></td> |
| </tr> |
| </tbody> |
| </table> |
| <div class="paragraph"> |
| <p>All tokens must have a different name. |
| Both terminals and meta-terminals token lists are assumed to be complete. |
| The non-terminal list is fully optional, and the default choice if a token name cannot be found. |
| All missing entries use the token name as their text.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Note that the property file reader applies some interpretation to the text as well so what you enter in the file may not be what you get. |
| Please check the <a href="#rail-property-syntax">property file syntax</a> section for details.</p> |
| </div> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="rail-sequence">Sequence</h4> |
| <div class="paragraph"> |
| <p>A sequence connects one or more child diagram nodes in one or more rows such that they are all visited in sequential order.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Its configuration settings cover the elements around the child nodes.</p> |
| </div> |
| <table class="tableblock frame-all grid-all stretch"> |
| <colgroup> |
| <col style="width: 33.3333%;"> |
| <col style="width: 16.6666%;"> |
| <col style="width: 50.0001%;"> |
| </colgroup> |
| <thead> |
| <tr> |
| <th class="tableblock halign-left valign-top">Property name</th> |
| <th class="tableblock halign-left valign-top">Value type</th> |
| <th class="tableblock halign-left valign-top">Description</th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>sequence.padding.first-row.prefix</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Real</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Amount of space before the first child at the first row.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>sequence.padding.other-row.prefix</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Real</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Amount of space left of the left connecting vertical line to a next row.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>sequence.padding.row.suffix</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Real</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">If there is more than one row, the minimal amount of space between the right vertical line connecting a next row, and the vertical line up to the exit.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>sequence.padding.interrow</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Real</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Minimal amount of space between the bottom of a row, and the connecting horizontal line to the next row beneath it. |
| Also, the minimal amount of space between the same horizontal line and the top of the next row.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>sequence.arc-radius</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Real</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Radius of the arcs connecting horizontal lines with vertical lines.</p></td> |
| </tr> |
| </tbody> |
| </table> |
| </div> |
| <div class="sect3"> |
| <h4 id="rail-choice">Choice</h4> |
| <div class="paragraph"> |
| <p>The choice node expresses a choice between one of the child diagram nodes.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Its configurable properties are:</p> |
| </div> |
| <table class="tableblock frame-all grid-all stretch"> |
| <colgroup> |
| <col style="width: 33.3333%;"> |
| <col style="width: 16.6666%;"> |
| <col style="width: 50.0001%;"> |
| </colgroup> |
| <thead> |
| <tr> |
| <th class="tableblock halign-left valign-top">Property name</th> |
| <th class="tableblock halign-left valign-top">Value type</th> |
| <th class="tableblock halign-left valign-top">Description</th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>choice.arc-radius</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Real</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Radius of the arcs connecting horizontal lines with vertical lines.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>choice.padding.vertical</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Real</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Minimal amount of vertical space between two child diagrams.</p></td> |
| </tr> |
| </tbody> |
| </table> |
| <div class="paragraph"> |
| <p>Note that the space between the first and second child is not only influenced by the <code>choice.padding.vertical</code> setting, but also influenced by the <code>choice.arc-radius</code>, as two arcs have to fit vertically as well.</p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="rail-repetition-2">Repetition</h4> |
| <div class="paragraph"> |
| <p>The repetition node <code>A + B</code> expresses an alternating execution sequence <code>A(BA)*</code>. |
| The <code>A</code> child node is referred to as <em>forward</em>, as its execution runs normally from left to right in the diagram, while the <code>B</code> child is referred to as <em>backward</em> as its execution normally runs from right to left. |
| The repetition is also known as <em>loop</em> due to the circular shape of the node.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Its configuration settings are:</p> |
| </div> |
| <table class="tableblock frame-all grid-all stretch"> |
| <colgroup> |
| <col style="width: 33.3333%;"> |
| <col style="width: 16.6666%;"> |
| <col style="width: 50.0001%;"> |
| </colgroup> |
| <thead> |
| <tr> |
| <th class="tableblock halign-left valign-top">Property name</th> |
| <th class="tableblock halign-left valign-top">Value type</th> |
| <th class="tableblock halign-left valign-top">Description</th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>loop.arc-radius</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Real</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Radius of the arcs connecting horizontal lines with vertical lines.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>loop.padding.vertical</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Real</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Amount of vertical space between the nodes of the forward and backward sequences.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>loop.padding.left</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Real</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Amount of space left of the left vertical line.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>loop.padding.right</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Real</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Amount of space right of the right vertical line.</p></td> |
| </tr> |
| </tbody> |
| </table> |
| <div class="paragraph"> |
| <p>The <code>loop.padding.left</code> and <code>loop.padding.right</code> become important when a diagram contains a sequence of repetitions. |
| If you set the left and right padding to <code>0</code>, the following may happen:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlight"><code class="language-raildiagram" data-lang="raildiagram">SequenceLoops : (A + B) (C + D) ;</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>This results in:</p> |
| </div> |
| <div class="imageblock"> |
| <div class="content"> |
| <img src="./rail/sequence_loops.png" alt="Sequence of loops"> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Other nodes all have some space at either end, making it less apparent in those cases.</p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="rail-debugging">Debugging</h4> |
| <div class="paragraph"> |
| <p>A diagram is actually a tree of simpler diagrams where at each node in the tree a set of position equations is solved for positioning all elements in its sub-tree. |
| This happens in two sweeps through the tree. |
| First a bottom-up computation of size and relative position of elements in their sub-tree is performed. |
| In the second top-down sweep assignment of horizontal and vertical absolute offsets to all nodes is performed, giving all elements their final absolute position in the diagram. |
| Output is produced by a walk over all nodes in the tree, and copying the elements with their absolute positions to the output.</p> |
| </div> |
| <div class="paragraph"> |
| <p>There are several flags for generating detailed output of the above process to support debugging at several points in the computations.</p> |
| </div> |
| <div class="sect4"> |
| <h5 id="rail-hierarchy">Hierarchy</h5> |
| <div class="paragraph"> |
| <p>To view the tree hierarchy in the diagram, the <code>debug.structure</code> flag can be used.</p> |
| </div> |
| <table class="tableblock frame-all grid-all stretch"> |
| <colgroup> |
| <col style="width: 33.3333%;"> |
| <col style="width: 16.6666%;"> |
| <col style="width: 50.0001%;"> |
| </colgroup> |
| <thead> |
| <tr> |
| <th class="tableblock halign-left valign-top">Property name</th> |
| <th class="tableblock halign-left valign-top">Value type</th> |
| <th class="tableblock halign-left valign-top">Description</th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>debug.structure</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Boolean</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Dump internal structure of the diagram.</p></td> |
| </tr> |
| </tbody> |
| </table> |
| </div> |
| <div class="sect4"> |
| <h5 id="rail-constraint-solving">Constraint solving</h5> |
| <div class="paragraph"> |
| <p>Positions are computed by solving two sets of constraint equations at each node in the tree, one for horizontal positioning, and one for vertical positioning. |
| The <code>debug.equations</code> flag shows the variables and equations, the <code>debug.solver</code> shows the solving process. |
| Due to the large number of variables and equations in a typical diagram, enabling these settings produces a lot of detailed debug output.</p> |
| </div> |
| <table class="tableblock frame-all grid-all stretch"> |
| <colgroup> |
| <col style="width: 33.3333%;"> |
| <col style="width: 16.6666%;"> |
| <col style="width: 50.0001%;"> |
| </colgroup> |
| <thead> |
| <tr> |
| <th class="tableblock halign-left valign-top">Property name</th> |
| <th class="tableblock halign-left valign-top">Value type</th> |
| <th class="tableblock halign-left valign-top">Description</th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>debug.equations</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Boolean</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Dump positioning equations for the graphical elements.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>debug.solver</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Boolean</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Dump reasoning and deciding edge position values for the graphical elements.</p></td> |
| </tr> |
| </tbody> |
| </table> |
| </div> |
| <div class="sect4"> |
| <h5 id="rail-coordinates">Coordinates</h5> |
| <div class="paragraph"> |
| <p>To debug problems in produced output, the following flags are useful. |
| The <code>debug.rel_coordinates</code> flag shows position information at each level of the tree separately, this is mostly useful to find problems at a single level of a diagram. |
| The <code>debug.abs_coordinates</code> flag shows the same position information, except all coordinates use the same top-left origin, enabling verification of positions between different levels in the hierarchy.</p> |
| </div> |
| <table class="tableblock frame-all grid-all stretch"> |
| <colgroup> |
| <col style="width: 33.3333%;"> |
| <col style="width: 16.6666%;"> |
| <col style="width: 50.0001%;"> |
| </colgroup> |
| <thead> |
| <tr> |
| <th class="tableblock halign-left valign-top">Property name</th> |
| <th class="tableblock halign-left valign-top">Value type</th> |
| <th class="tableblock halign-left valign-top">Description</th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>debug.rel_coordinates</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Boolean</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Dump coordinates of the graphical elements and child node positions within each element.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>debug.abs_coordinates</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Boolean</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Dump absolute coordinates of the graphical elements and child node positions of the diagram.</p></td> |
| </tr> |
| </tbody> |
| </table> |
| <div class="paragraph"> |
| <p>Note that positions are stated as inclusive horizontal and vertical edge positions everywhere. |
| This means that element <code>x[1—​1], y[1—​2]</code> is one unit wide horizontally, and two units vertically. |
| Also, an element <code>x[2—​7], y[1—​2]</code> is directly next to the previous element, there is no space between them.</p> |
| </div> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="rail-default-property-values">Default property values</h4> |
| <div class="paragraph"> |
| <p>The default values for the various properties are as follows:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlight"><code class="language-properties" data-lang="properties"># Background. |
| diagram.background.color: 255 255 255 |
| |
| # Rail. |
| rail.linewidth: 1.0 |
| rail.color: 0 0 0 |
| |
| # Diagram rule. |
| rule.padding.top: 10 |
| rule.padding.left: 10 |
| rule.padding.bottom: 10 |
| rule.padding.right: 10 |
| rule.diagram.padding.top: 10 |
| rule.diagram.padding.left: 10 |
| rule.diagram.lead.width: 20 |
| rule.diagram.trail.width: 20 |
| |
| # Choice. |
| choice.arc-radius: 10 |
| choice.padding.vertical: 5 |
| |
| # Loop. |
| loop.arc-radius: 10 |
| loop.padding.vertical: 5 |
| loop.padding.left: 5 |
| loop.padding.right: 5 |
| |
| # Sequence. |
| sequence.padding.first-row.prefix: 0 |
| sequence.padding.other-row.prefix: 5 |
| sequence.padding.row.suffix: 5 |
| sequence.padding.interrow: 8 |
| sequence.arc-radius: 10 |
| |
| # Branch label. |
| branch-label.padding.left: 5 |
| branch-label.padding.right: 5 |
| branch-label.padding.top: 5 |
| branch-label.padding.bottom: 5 |
| branch-label.min-width: 5 |
| branch-label.text.color: 0 0 0 |
| branch-label.text.font: SansSerif |
| branch-label.text.font.size: 16 |
| branch-label.text.font.style: plain |
| |
| # Empty node. |
| empty.width: 10 |
| |
| # Name node, width of the entry and exit connections. |
| name.rail.entry.width: 5 |
| name.rail.exit.width: 5 |
| |
| # Header font and text. |
| diagram-header.text.color: 0 0 0 |
| diagram-header.text.font: SansSerif |
| diagram-header.text.font.size: 16 |
| diagram-header.text.font.style: bold |
| |
| # 'terminal' name properties. |
| terminal.name.padding.horizontal: 5 |
| terminal.name.padding.vertical: 5 |
| terminal.corner.radius: 12 |
| terminal.box.color: 0 0 0 |
| terminal.box.linewidth: 1.0 |
| terminal.text.color: 0 0 0 |
| terminal.text.font: Monospaced |
| terminal.text.font.size: 18 |
| terminal.text.font.style: plain |
| |
| # 'meta-terminal' name properties. |
| meta-terminal.name.padding.horizontal: 5 |
| meta-terminal.name.padding.vertical: 5 |
| meta-terminal.corner.radius: 12 |
| meta-terminal.box.color: 0 0 0 |
| meta-terminal.box.linewidth: 1.0 |
| meta-terminal.text.color: 0 0 0 |
| meta-terminal.text.font: SansSerif |
| meta-terminal.text.font.size: 16 |
| meta-terminal.text.font.style: plain |
| |
| # 'nonterminal' name properties. |
| nonterminal.name.padding.horizontal: 5 |
| nonterminal.name.padding.vertical: 5 |
| nonterminal.corner.radius: 0 |
| nonterminal.box.color: 0 0 0 |
| nonterminal.box.linewidth: 1.0 |
| nonterminal.text.color: 0 0 0 |
| nonterminal.text.font: SansSerif |
| nonterminal.text.font.size: 16 |
| nonterminal.text.font.style: italic |
| |
| # Token text properties: |
| # terminal.token.<tokname>: <toktext>, should always be fully specified. |
| # meta-terminal.<tokname>: <toktext>, should always be fully specified. |
| # nonterminal.token.<tokname>: <toktext>, with <toktext> optional, default value is <tokname>. |
| |
| # Debugging support, ordered by topic. |
| debug.structure: false |
| debug.equations: false |
| debug.solver: false |
| debug.rel_coordinates: false |
| debug.abs_coordinates: false</code></pre> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="rail-lexical-syntax">Lexical syntax</h3> |
| <div class="sect3"> |
| <h4 id="rail-whitespace">Whitespace</h4> |
| <div class="paragraph"> |
| <p>Spaces, tabs, and new line characters are supported as whitespace. |
| Whitespace is ignored (except in the literals described below), but can be used to separate tokens as well as for layout purposes. |
| The use of tab characters is allowed, but should be avoided if possible, as layout will be different for text editors with different tab settings. |
| You may generally format the input as you see fit, and start on a new line when desired.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Examples:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlight"><code class="language-raildiagram" data-lang="raildiagram"># Normal layout. |
| DiagramName : A B C |
| ; |
| |
| # Alternative layout. |
| DiagramName |
| : A |
| B C |
| ;</code></pre> |
| </div> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="rail-comments">Comments</h4> |
| <div class="paragraph"> |
| <p>Comments start with a hash symbol (<code>#</code>) and end at the end of the line. |
| Comments are ignored.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Examples:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlight"><code class="language-raildiagram" data-lang="raildiagram">DiagramName : A B C ; # Comment</code></pre> |
| </div> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="rail-terminals">Terminals</h4> |
| <div class="paragraph"> |
| <p>The following terminals are defined:</p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1"><code>Identifier</code></dt> |
| <dd> |
| <p>An identifier. |
| Defined by the regular expression: <code>[\-A-Za-z0-9_]+</code>. |
| They thus consist of dashes (<code>-</code>), letters, digits and underscores (<code>_</code>).</p> |
| <div class="paragraph"> |
| <p>Examples:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlight"><code class="language-raildiagram" data-lang="raildiagram">Expression |
| ABC_DEF |
| ABC-DEF</code></pre> |
| </div> |
| </div> |
| </dd> |
| <dt class="hdlist1"><code>BracketedString</code></dt> |
| <dd> |
| <p>A bracketed string. |
| Defined by the regular expression: |
| <code>\[([^\\\]\n]|\\[\\\]])*\]</code>. |
| They are thus enclosed in square brackets (<code>[</code> and <code>]</code>). |
| They must be on a single line and must thus not include new line characters (<code>\n</code>, Unicode U+0A). |
| To include a closing bracket (<code>]</code>), it must be escaped as <code>\]</code>. |
| Since a backslash (<code>\</code>) serves as escape character, to include a backslash it must be escaped as <code>\\</code>.</p> |
| <div class="paragraph"> |
| <p>Examples:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlight"><code class="language-raildiagram" data-lang="raildiagram">[literal] |
| [line-break] |
| [abc\]def] |
| [abc\\def]</code></pre> |
| </div> |
| </div> |
| </dd> |
| <dt class="hdlist1"><code>SingleQuotedString</code></dt> |
| <dd> |
| <p>A single-quoted string literal. |
| Defined by the regular expression: |
| <code>'([^\\'\n]|\\[\\'])*\'</code>. |
| These literals are enclosed in single quotes (<code>'</code>). |
| They must be on a single line and must thus not include new line characters (<code>\n</code>, Unicode U+0A). |
| To include a single quote (<code>'</code>) in a string literal, it must be escaped as <code>\'</code>. |
| Since a backslash (<code>\</code>) serves as escape character, to include a backslash in a string literal it must be escaped as <code>\\</code>.</p> |
| <div class="paragraph"> |
| <p>Examples:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlight"><code class="language-raildiagram" data-lang="raildiagram">'hello world' |
| 'abc\'def' |
| 'abc\\def'</code></pre> |
| </div> |
| </div> |
| </dd> |
| <dt class="hdlist1"><code>DoubleQuotedString</code></dt> |
| <dd> |
| <p>A double-quoted string literal. |
| Defined by the regular expression: |
| <code>\"([^\\\"\n]|\\[\\\"])*\"</code>. |
| These literals are enclosed in double quotes (<code>"</code>). |
| They must be on a single line and must thus not include new line characters (<code>\n</code>, Unicode U+0A). |
| To include a double quote (<code>"</code>) in a string literal, it must be escaped as <code>\"</code>. |
| Since a backslash (<code>\</code>) serves as escape character, to include a backslash in a string literal it must be escaped as <code>\\</code>.</p> |
| <div class="paragraph"> |
| <p>Examples:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlight"><code class="language-raildiagram" data-lang="raildiagram">"hello world" |
| "abc\"def" |
| "abc\\def"</code></pre> |
| </div> |
| </div> |
| </dd> |
| </dl> |
| </div> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="rail-grammar">Grammar</h3> |
| <div class="paragraph"> |
| <p>The toplevel grammar rule of the application is <code>Specification</code>. |
| It is a sequence of rules, each terminated by a semicolon. |
| One specification creates one output file.</p> |
| </div> |
| <div class="imageblock"> |
| <div class="content"> |
| <img src="./rail/spec.png" alt="Specification"> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>A <code>Rule</code> is a possibly named railroad.</p> |
| </div> |
| <div class="imageblock"> |
| <div class="content"> |
| <img src="./rail/rule.png" alt="Rule"> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>A <code>Railroad</code> is one or more choice alternatives.</p> |
| </div> |
| <div class="imageblock"> |
| <div class="content"> |
| <img src="./rail/diagram.png" alt="Railroad"> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>The <code>BracketedString</code> like <code>[a]</code> can be used to denote specific points in the diagram allowing you to refer to such points from the explanatory text.</p> |
| </div> |
| <div class="paragraph"> |
| <p>An <code>Alternative</code> has a <code>sequence</code> of one or more factors. |
| The optional <code>?</code> character makes a factor optional. |
| By appending the <code>[loop]</code> part, the sequence can be repeated. |
| The <code>+</code> requires at least one sequence, the <code>*</code> also allows <code>0</code> repetitions, resulting in an empty sequence. |
| The second <code>Factor</code> defines the syntax on the way back to the start. |
| Note that parentheses are required in the second <code>Factor</code> if is it more than one node.</p> |
| </div> |
| <div class="imageblock"> |
| <div class="content"> |
| <img src="./rail/alternative.png" alt="Alternative"> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Note that together with <code>|</code> above and the empty sequence <code>()</code> below, you can write all loops using the <code>+</code> infix operator. |
| The <a href="#rail-examples">Examples</a> section explains this as well.</p> |
| </div> |
| <div class="paragraph"> |
| <p>In an alternative, <code>Factor</code> is a single token:</p> |
| </div> |
| <div class="imageblock"> |
| <div class="content"> |
| <img src="./rail/factor.png" alt="Factor"> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>The <code>[literal1]</code> and <code>[literal2]</code> choices show the text of the string. |
| Surrounding quotes are dropped. |
| There are two forms of literals to simplify using single or double quote literals in the diagrams. |
| The <code>[sub-diagram]</code> choice allows nesting of sequence, choice, and repetition, enabling construction of more complicated diagrams. |
| The <code>[epsilon]</code> choice is the empty sequence. |
| The <code>[sub-rule]</code> choice enables giving the name of another diagram to process.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Finally, the <code>[line-break]</code> choice can be used to split a long sequence of factors into multiple rows. |
| In general, its use should be avoided as it often leads to less pretty diagrams. |
| Instead, try to re-organize rules or diagrams.</p> |
| </div> |
| <div class="paragraph"> |
| <p></p> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="release-notes-chapter-index">Eclipse ESCET release notes</h2> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p>The release notes for the releases of the Eclipse ESCET tools, as part of the Eclipse ESCET project, are listed below in reverse chronological order.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The release notes may refer to issues, the details for which can be found at the Eclipse ESCET <a href="https://gitlab.eclipse.org/eclipse/escet/escet/-/issues">GitLab issues page</a>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>See also the release notes for the specific tools for more information:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="https://www.eclipse.org/escet/cif/#release-notes-chapter-index">CIF release notes</a></p> |
| </li> |
| <li> |
| <p><a href="https://www.eclipse.org/escet/chi/#release-notes-chapter-index">Chi release notes</a></p> |
| </li> |
| <li> |
| <p><a href="https://www.eclipse.org/escet/tooldef/#release-notes-chapter-index">ToolDef release notes</a></p> |
| </li> |
| <li> |
| <p><a href="https://www.eclipse.org/escet/setext/#setext-readme-release-notes">SeText release notes</a></p> |
| </li> |
| </ul> |
| </div> |
| <div class="sect2"> |
| <h3 id="version-0-2">Version 0.2</h3> |
| <div class="paragraph"> |
| <p>Improvements and fixes:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>Various documentation updates, including simpler installation instructions (issues #30 and #31).</p> |
| </li> |
| <li> |
| <p>Java 11 is now included in the release and Java thus no longer needs to be installed separately (issues #29 and #30).</p> |
| </li> |
| <li> |
| <p>The Eclipse ESCET IDE now includes the Eclipse Marketplace (issue #71).</p> |
| </li> |
| <li> |
| <p>Linux command line scripts now work properly from any directory rather than only from the <code>bin</code> directory that contains them (issue #88).</p> |
| </li> |
| <li> |
| <p>macOS releases are now packaged as <code>.dmg</code> files and with proper entitlements (issue #31).</p> |
| </li> |
| <li> |
| <p>Eclipse ESCET downloads now contain a folder in the root of the archive, to properly support unpacking in e.g. a downloads directory (issue #87).</p> |
| </li> |
| <li> |
| <p>This release is based on Eclipse 2021-06 (issues #28 and #121).</p> |
| </li> |
| <li> |
| <p>Improved Eclipse ESCET download filenames (issues #87 and #92).</p> |
| </li> |
| <li> |
| <p>Improved Eclipse ESCET version numbers in documentation, plugin/feature versions, and Eclipse ESCET IDE about dialog (issues #92 and #103).</p> |
| </li> |
| <li> |
| <p>Non-release builds now indicate they are a development build in the Eclipse About dialog (issue #26).</p> |
| </li> |
| <li> |
| <p>Eclipse ESCET downloads for Linux previously included an 'executable' <code>about.html</code> file (issue #90).</p> |
| </li> |
| <li> |
| <p>Crash reports now indicate where and how to report issues (issue #33).</p> |
| </li> |
| </ul> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="version-0-1">Version 0.1</h3> |
| <div class="paragraph"> |
| <p>The first release of the Eclipse ESCET project and toolkit. |
| This release is based on the initial contribution by the Eindhoven University of Technology (TU/e).</p> |
| </div> |
| <div class="paragraph"> |
| <p>Most notable changes compared to the last TU/e release:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>A JDK is no longer bundled with the downloads. |
| A JDK must be installed separately and manually. |
| Future releases will again include a JDK.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>This release is based on the Eclipse IDE version 2020-06 and supports Java 8.</p> |
| </div> |
| <div class="paragraph"> |
| <p></p> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="contact-chapter-index">Contact information</h2> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p>Thanks for your interest in Eclipse Supervisory Control Engineering Toolkit (Eclipse ESCET) project.</p> |
| </div> |
| <div class="paragraph"> |
| <p>You can interact with the Eclipse ESCET community and its developers in various ways:</p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1"><a href="https://www.eclipse.org/forums/index.php/f/527/">Eclipse ESCET forum</a></dt> |
| <dd> |
| <p>If you have any questions regarding the Eclipse ESCET project, any of its tools, or how to use them, feel free to ask them on the project forum.</p> |
| </dd> |
| <dt class="hdlist1"><a href="#developer-issue-tracking-chapter-index">Issue tracking</a></dt> |
| <dd> |
| <p>If you wish to browse existing issues or report new ones, then see the issue tracking section for more information.</p> |
| </dd> |
| <dt class="hdlist1"><a href="#developer-chapter-index">Developer information</a></dt> |
| <dd> |
| <p>If you specifically want to contact the Eclipse ESCET developers concerning development related activities, want to contribute to the Eclipse ESCET project, or want to browse the source code, then see the developer information.</p> |
| </dd> |
| </dl> |
| </div> |
| <div class="paragraph"> |
| <p></p> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="legal-chapter-index">Legal</h2> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p>The material in this documentation is Copyright (c) 2010, 2021 Contributors to the Eclipse Foundation.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Eclipse ESCET and ESCET are trademarks of the Eclipse Foundation. |
| Eclipse, and the Eclipse Logo are registered trademarks of the Eclipse Foundation. |
| Other names may be trademarks of their respective owners.</p> |
| </div> |
| <div class="paragraph"> |
| <p><strong>License</strong></p> |
| </div> |
| <div class="paragraph"> |
| <p>The Eclipse Foundation makes available all content in this document ("Content"). |
| Unless otherwise indicated below, the Content is provided to you under the terms and conditions of the MIT License. |
| A copy of the MIT License is available at <a href="https://opensource.org/licenses/MIT" class="bare">https://opensource.org/licenses/MIT</a>. |
| For purposes of the MIT License, "Software" will mean the Content.</p> |
| </div> |
| <div class="paragraph"> |
| <p>If you did not receive this Content directly from the Eclipse Foundation, the Content is being redistributed by another party ("Redistributor") and different terms and conditions may apply to your use of any object code in the Content. |
| Check the Redistributor’s license that was provided with the Content. |
| If no such license exists, contact the Redistributor. |
| Unless otherwise indicated below, the terms and conditions of the MIT License still apply to any source code in the Content and such source code may be obtained at <a href="http://www.eclipse.org" class="bare">http://www.eclipse.org</a>.</p> |
| </div> |
| </div> |
| </div> |
| </div> |
| <script type="text/x-mathjax-config"> |
| MathJax.Hub.Config({ |
| messageStyle: "none", |
| tex2jax: { |
| inlineMath: [["\\(", "\\)"]], |
| displayMath: [["\\[", "\\]"]], |
| ignoreClass: "nostem|nolatexmath" |
| }, |
| asciimath2jax: { |
| delimiters: [["\\$", "\\$"]], |
| ignoreClass: "nostem|noasciimath" |
| }, |
| TeX: { equationNumbers: { autoNumber: "none" } } |
| }) |
| MathJax.Hub.Register.StartupHook("AsciiMath Jax Ready", function () { |
| MathJax.InputJax.AsciiMath.postfilterHooks.Add(function (data, node) { |
| if ((node = data.script.parentNode) && (node = node.parentNode) && node.classList.contains("stemblock")) { |
| data.math.root.display = "block" |
| } |
| return data |
| }) |
| }) |
| </script> |
| <script src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.9/MathJax.js?config=TeX-MML-AM_HTMLorMML"></script> |
| <!-- |
| Copyright (c) 2010, 2021 Contributors to the Eclipse Foundation |
| |
| See the NOTICE file(s) distributed with this work for additional |
| information regarding copyright ownership. |
| |
| This program and the accompanying materials are made available under the terms |
| of the MIT License which is available at https://opensource.org/licenses/MIT |
| |
| SPDX-License-Identifier: MIT |
| --> |
| |
| <div id="footer"> |
| <div id="footer-text"> |
| <a href="https://www.eclipse.org">Eclipse Home</a> |
| | |
| <a href="https://www.eclipse.org/legal/privacy.php">Privacy Policy</a> |
| | |
| <a href="https://www.eclipse.org/legal/termsofuse.php">Terms of Use</a> |
| | |
| <a href="https://www.eclipse.org/legal/copyright.php">Copyright Agent</a> |
| | |
| <a href="https://www.eclipse.org/legal">Eclipse Legal</a> |
| </div> |
| </div> |
| </body> |
| </html> |
