1<!DOCTYPE html> 2<html lang="en"> 3<head> 4<meta charset="UTF-8"> 5<!--[if IE]><meta http-equiv="X-UA-Compatible" content="IE=edge"><![endif]--> 6<meta name="viewport" content="width=device-width, initial-scale=1.0"> 7<meta name="generator" content="Asciidoctor 1.5.8"> 8<meta name="author" content="Rene Rivera, Vladimir Prus, Steven Watanabe"> 9<meta name="copyright" content="Copyright 2018 Rene Rivera; Copyright 2006, 2014 Vladimir Prus"> 10<title>B2 User Manual</title> 11<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"> 12<style> 13/* Asciidoctor default stylesheet | MIT License | http://asciidoctor.org */ 14/* Uncomment @import statement below to use as custom stylesheet */ 15/*@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";*/ 16article,aside,details,figcaption,figure,footer,header,hgroup,main,nav,section,summary{display:block} 17audio,canvas,video{display:inline-block} 18audio:not([controls]){display:none;height:0} 19script{display:none!important} 20html{font-family:sans-serif;-ms-text-size-adjust:100%;-webkit-text-size-adjust:100%} 21a{background:transparent} 22a:focus{outline:thin dotted} 23a:active,a:hover{outline:0} 24h1{font-size:2em;margin:.67em 0} 25abbr[title]{border-bottom:1px dotted} 26b,strong{font-weight:bold} 27dfn{font-style:italic} 28hr{-moz-box-sizing:content-box;box-sizing:content-box;height:0} 29mark{background:#ff0;color:#000} 30code,kbd,pre,samp{font-family:monospace;font-size:1em} 31pre{white-space:pre-wrap} 32q{quotes:"\201C" "\201D" "\2018" "\2019"} 33small{font-size:80%} 34sub,sup{font-size:75%;line-height:0;position:relative;vertical-align:baseline} 35sup{top:-.5em} 36sub{bottom:-.25em} 37img{border:0} 38svg:not(:root){overflow:hidden} 39figure{margin:0} 40fieldset{border:1px solid silver;margin:0 2px;padding:.35em .625em .75em} 41legend{border:0;padding:0} 42button,input,select,textarea{font-family:inherit;font-size:100%;margin:0} 43button,input{line-height:normal} 44button,select{text-transform:none} 45button,html input[type="button"],input[type="reset"],input[type="submit"]{-webkit-appearance:button;cursor:pointer} 46button[disabled],html input[disabled]{cursor:default} 47input[type="checkbox"],input[type="radio"]{box-sizing:border-box;padding:0} 48button::-moz-focus-inner,input::-moz-focus-inner{border:0;padding:0} 49textarea{overflow:auto;vertical-align:top} 50table{border-collapse:collapse;border-spacing:0} 51*,*::before,*::after{-moz-box-sizing:border-box;-webkit-box-sizing:border-box;box-sizing:border-box} 52html,body{font-size:100%} 53body{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;-moz-osx-font-smoothing:grayscale;-webkit-font-smoothing:antialiased} 54a:hover{cursor:pointer} 55img,object,embed{max-width:100%;height:auto} 56object,embed{height:100%} 57img{-ms-interpolation-mode:bicubic} 58.left{float:left!important} 59.right{float:right!important} 60.text-left{text-align:left!important} 61.text-right{text-align:right!important} 62.text-center{text-align:center!important} 63.text-justify{text-align:justify!important} 64.hide{display:none} 65img,object,svg{display:inline-block;vertical-align:middle} 66textarea{height:auto;min-height:50px} 67select{width:100%} 68.center{margin-left:auto;margin-right:auto} 69.stretch{width:100%} 70.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} 71div,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;direction:ltr} 72a{color:#2156a5;text-decoration:underline;line-height:inherit} 73a:hover,a:focus{color:#1d4b8f} 74a img{border:none} 75p{font-family:inherit;font-weight:400;font-size:1em;line-height:1.6;margin-bottom:1.25em;text-rendering:optimizeLegibility} 76p aside{font-size:.875em;line-height:1.35;font-style:italic} 77h1,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} 78h1 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} 79h1{font-size:2.125em} 80h2{font-size:1.6875em} 81h3,#toctitle,.sidebarblock>.content>.title{font-size:1.375em} 82h4,h5{font-size:1.125em} 83h6{font-size:1em} 84hr{border:solid #dddddf;border-width:1px 0 0;clear:both;margin:1.25em 0 1.1875em;height:0} 85em,i{font-style:italic;line-height:inherit} 86strong,b{font-weight:bold;line-height:inherit} 87small{font-size:60%;line-height:inherit} 88code{font-family:"Droid Sans Mono","DejaVu Sans Mono",monospace;font-weight:400;color:rgba(0,0,0,.9)} 89ul,ol,dl{font-size:1em;line-height:1.6;margin-bottom:1.25em;list-style-position:outside;font-family:inherit} 90ul,ol{margin-left:1.5em} 91ul li ul,ul li ol{margin-left:1.25em;margin-bottom:0;font-size:1em} 92ul.square li ul,ul.circle li ul,ul.disc li ul{list-style:inherit} 93ul.square{list-style-type:square} 94ul.circle{list-style-type:circle} 95ul.disc{list-style-type:disc} 96ol li ul,ol li ol{margin-left:1.25em;margin-bottom:0} 97dl dt{margin-bottom:.3125em;font-weight:bold} 98dl dd{margin-bottom:1.25em} 99abbr,acronym{text-transform:uppercase;font-size:90%;color:rgba(0,0,0,.8);border-bottom:1px dotted #ddd;cursor:help} 100abbr{text-transform:none} 101blockquote{margin:0 0 1.25em;padding:.5625em 1.25em 0 1.1875em;border-left:1px solid #ddd} 102blockquote cite{display:block;font-size:.9375em;color:rgba(0,0,0,.6)} 103blockquote cite::before{content:"\2014 \0020"} 104blockquote cite a,blockquote cite a:visited{color:rgba(0,0,0,.6)} 105blockquote,blockquote p{line-height:1.6;color:rgba(0,0,0,.85)} 106@media screen and (min-width:768px){h1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6{line-height:1.2} 107h1{font-size:2.75em} 108h2{font-size:2.3125em} 109h3,#toctitle,.sidebarblock>.content>.title{font-size:1.6875em} 110h4{font-size:1.4375em}} 111table{background:#fff;margin-bottom:1.25em;border:solid 1px #dedede} 112table thead,table tfoot{background:#f7f8f7} 113table 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} 114table tr th,table tr td{padding:.5625em .625em;font-size:inherit;color:rgba(0,0,0,.8)} 115table tr.even,table tr.alt,table tr:nth-of-type(even){background:#f8f8f7} 116table thead tr th,table tfoot tr th,table tbody tr td,table tr td,table tfoot tr td{display:table-cell;line-height:1.6} 117h1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6{line-height:1.2;word-spacing:-.05em} 118h1 strong,h2 strong,h3 strong,#toctitle strong,.sidebarblock>.content>.title strong,h4 strong,h5 strong,h6 strong{font-weight:400} 119.clearfix::before,.clearfix::after,.float-group::before,.float-group::after{content:" ";display:table} 120.clearfix::after,.float-group::after{clear:both} 121*:not(pre)>code{font-size:.9375em;font-style:normal!important;letter-spacing:0;padding:.1em .5ex;word-spacing:-.15em;background-color:#f7f7f8;-webkit-border-radius:4px;border-radius:4px;line-height:1.45;text-rendering:optimizeSpeed;word-wrap:break-word} 122*:not(pre)>code.nobreak{word-wrap:normal} 123*:not(pre)>code.nowrap{white-space:nowrap} 124pre,pre>code{line-height:1.45;color:rgba(0,0,0,.9);font-family:"Droid Sans Mono","DejaVu Sans Mono",monospace;font-weight:400;text-rendering:optimizeSpeed} 125em em{font-style:normal} 126strong strong{font-weight:400} 127.keyseq{color:rgba(51,51,51,.8)} 128kbd{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-color:#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} 129.keyseq kbd:first-child{margin-left:0} 130.keyseq kbd:last-child{margin-right:0} 131.menuseq,.menuref{color:#000} 132.menuseq b:not(.caret),.menuref{font-weight:inherit} 133.menuseq{word-spacing:-.02em} 134.menuseq b.caret{font-size:1.25em;line-height:.8} 135.menuseq i.caret{font-weight:bold;text-align:center;width:.45em} 136b.button::before,b.button::after{position:relative;top:-1px;font-weight:400} 137b.button::before{content:"[";padding:0 3px 0 2px} 138b.button::after{content:"]";padding:0 2px 0 3px} 139p a>code:hover{color:rgba(0,0,0,.9)} 140#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} 141#header::before,#header::after,#content::before,#content::after,#footnotes::before,#footnotes::after,#footer::before,#footer::after{content:" ";display:table} 142#header::after,#content::after,#footnotes::after,#footer::after{clear:both} 143#content{margin-top:1.25em} 144#content::before{content:none} 145#header>h1:first-child{color:rgba(0,0,0,.85);margin-top:2.25rem;margin-bottom:0} 146#header>h1:first-child+#toc{margin-top:8px;border-top:1px solid #dddddf} 147#header>h1:only-child,body.toc2 #header>h1:nth-last-child(2){border-bottom:1px solid #dddddf;padding-bottom:8px} 148#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} 149#header .details span:first-child{margin-left:-.125em} 150#header .details span.email a{color:rgba(0,0,0,.85)} 151#header .details br{display:none} 152#header .details br+span::before{content:"\00a0\2013\00a0"} 153#header .details br+span.author::before{content:"\00a0\22c5\00a0";color:rgba(0,0,0,.85)} 154#header .details br+span#revremark::before{content:"\00a0|\00a0"} 155#header #revnumber{text-transform:capitalize} 156#header #revnumber::after{content:"\00a0"} 157#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} 158#toc{border-bottom:1px solid #e7e7e9;padding-bottom:.5em} 159#toc>ul{margin-left:.125em} 160#toc ul.sectlevel0>li>a{font-style:italic} 161#toc ul.sectlevel0 ul.sectlevel1{margin:.5em 0} 162#toc ul{font-family:"Open Sans","DejaVu Sans",sans-serif;list-style-type:none} 163#toc li{line-height:1.3334;margin-top:.3334em} 164#toc a{text-decoration:none} 165#toc a:active{text-decoration:underline} 166#toctitle{color:#7a2518;font-size:1.2em} 167@media screen and (min-width:768px){#toctitle{font-size:1.375em} 168body.toc2{padding-left:15em;padding-right:0} 169#toc.toc2{margin-top:0!important;background-color:#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} 170#toc.toc2 #toctitle{margin-top:0;margin-bottom:.8rem;font-size:1.2em} 171#toc.toc2>ul{font-size:.9em;margin-bottom:0} 172#toc.toc2 ul ul{margin-left:0;padding-left:1em} 173#toc.toc2 ul.sectlevel0 ul.sectlevel1{padding-left:0;margin-top:.5em;margin-bottom:.5em} 174body.toc2.toc-right{padding-left:0;padding-right:15em} 175body.toc2.toc-right #toc.toc2{border-right-width:0;border-left:1px solid #e7e7e9;left:auto;right:0}} 176@media screen and (min-width:1280px){body.toc2{padding-left:20em;padding-right:0} 177#toc.toc2{width:20em} 178#toc.toc2 #toctitle{font-size:1.375em} 179#toc.toc2>ul{font-size:.95em} 180#toc.toc2 ul ul{padding-left:1.25em} 181body.toc2.toc-right{padding-left:0;padding-right:20em}} 182#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} 183#content #toc>:first-child{margin-top:0} 184#content #toc>:last-child{margin-bottom:0} 185#footer{max-width:100%;background-color:rgba(0,0,0,.8);padding:1.25em} 186#footer-text{color:rgba(255,255,255,.8);line-height:1.44} 187#content{margin-bottom:.625em} 188.sect1{padding-bottom:.625em} 189@media screen and (min-width:768px){#content{margin-bottom:1.25em} 190.sect1{padding-bottom:1.25em}} 191.sect1:last-child{padding-bottom:0} 192.sect1+.sect1{border-top:1px solid #e7e7e9} 193#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} 194#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} 195#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} 196#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} 197#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} 198.audioblock,.imageblock,.literalblock,.listingblock,.stemblock,.videoblock{margin-bottom:1.25em} 199.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} 200table.tableblock.fit-content>caption.title{white-space:nowrap;width:0} 201.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)} 202table.tableblock #preamble>.sectionbody>[class="paragraph"]:first-of-type p{font-size:inherit} 203.admonitionblock>table{border-collapse:separate;border:0;background:none;width:100%} 204.admonitionblock>table td.icon{text-align:center;width:80px} 205.admonitionblock>table td.icon img{max-width:none} 206.admonitionblock>table td.icon .title{font-weight:bold;font-family:"Open Sans","DejaVu Sans",sans-serif;text-transform:uppercase} 207.admonitionblock>table td.content{padding-left:1.125em;padding-right:1.25em;border-left:1px solid #dddddf;color:rgba(0,0,0,.6)} 208.admonitionblock>table td.content>:last-child>:last-child{margin-bottom:0} 209.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} 210.exampleblock>.content>:first-child{margin-top:0} 211.exampleblock>.content>:last-child{margin-bottom:0} 212.sidebarblock{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} 213.sidebarblock>:first-child{margin-top:0} 214.sidebarblock>:last-child{margin-bottom:0} 215.sidebarblock>.content>.title{color:#7a2518;margin-top:0;text-align:center} 216.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} 217.literalblock pre,.listingblock pre:not(.highlight),.listingblock pre[class="highlight"],.listingblock pre[class^="highlight "],.listingblock pre.CodeRay,.listingblock pre.prettyprint{background:#f7f7f8} 218.sidebarblock .literalblock pre,.sidebarblock .listingblock pre:not(.highlight),.sidebarblock .listingblock pre[class="highlight"],.sidebarblock .listingblock pre[class^="highlight "],.sidebarblock .listingblock pre.CodeRay,.sidebarblock .listingblock pre.prettyprint{background:#f2f1f1} 219.literalblock pre,.literalblock pre[class],.listingblock pre,.listingblock pre[class]{-webkit-border-radius:4px;border-radius:4px;word-wrap:break-word;overflow-x:auto;padding:1em;font-size:.8125em} 220@media screen and (min-width:768px){.literalblock pre,.literalblock pre[class],.listingblock pre,.listingblock pre[class]{font-size:.90625em}} 221@media screen and (min-width:1280px){.literalblock pre,.literalblock pre[class],.listingblock pre,.listingblock pre[class]{font-size:1em}} 222.literalblock pre.nowrap,.literalblock pre.nowrap pre,.listingblock pre.nowrap,.listingblock pre.nowrap pre{white-space:pre;word-wrap:normal} 223.literalblock.output pre{color:#f7f7f8;background-color:rgba(0,0,0,.9)} 224.listingblock pre.highlightjs{padding:0} 225.listingblock pre.highlightjs>code{padding:1em;-webkit-border-radius:4px;border-radius:4px} 226.listingblock pre.prettyprint{border-width:0} 227.listingblock>.content{position:relative} 228.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:#999} 229.listingblock:hover code[data-lang]::before{display:block} 230.listingblock.terminal pre .command::before{content:attr(data-prompt);padding-right:.5em;color:#999} 231.listingblock.terminal pre .command:not([data-prompt])::before{content:"$"} 232table.pyhltable{border-collapse:separate;border:0;margin-bottom:0;background:none} 233table.pyhltable td{vertical-align:top;padding-top:0;padding-bottom:0;line-height:1.45} 234table.pyhltable td.code{padding-left:.75em;padding-right:0} 235pre.pygments .lineno,table.pyhltable td:not(.code){color:#999;padding-left:0;padding-right:.5em;border-right:1px solid #dddddf} 236pre.pygments .lineno{display:inline-block;margin-right:.25em} 237table.pyhltable .linenodiv{background:none!important;padding-right:0!important} 238.quoteblock{margin:0 1em 1.25em 1.5em;display:table} 239.quoteblock>.title{margin-left:-1.5em;margin-bottom:.75em} 240.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} 241.quoteblock blockquote{margin:0;padding:0;border:0} 242.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)} 243.quoteblock blockquote>.paragraph:last-child p{margin-bottom:0} 244.quoteblock .attribution{margin-top:.75em;margin-right:.5ex;text-align:right} 245.verseblock{margin:0 1em 1.25em} 246.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} 247.verseblock pre strong{font-weight:400} 248.verseblock .attribution{margin-top:1.25rem;margin-left:.5ex} 249.quoteblock .attribution,.verseblock .attribution{font-size:.9375em;line-height:1.45;font-style:italic} 250.quoteblock .attribution br,.verseblock .attribution br{display:none} 251.quoteblock .attribution cite,.verseblock .attribution cite{display:block;letter-spacing:-.025em;color:rgba(0,0,0,.6)} 252.quoteblock.abstract blockquote::before,.quoteblock.excerpt blockquote::before,.quoteblock .quoteblock blockquote::before{display:none} 253.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} 254.quoteblock.abstract{margin:0 1em 1.25em;display:block} 255.quoteblock.abstract>.title{margin:0 0 .375em;font-size:1.15em;text-align:center} 256.quoteblock.excerpt,.quoteblock .quoteblock{margin:0 0 1.25em;padding:0 0 .25em 1em;border-left:.25em solid #dddddf} 257.quoteblock.excerpt blockquote,.quoteblock.excerpt p,.quoteblock .quoteblock blockquote,.quoteblock .quoteblock p{color:inherit;font-size:1.0625rem} 258.quoteblock.excerpt .attribution,.quoteblock .quoteblock .attribution{color:inherit;text-align:left;margin-right:0} 259table.tableblock{max-width:100%;border-collapse:separate} 260p.tableblock:last-child{margin-bottom:0} 261td.tableblock>.content{margin-bottom:-1.25em} 262table.tableblock,th.tableblock,td.tableblock{border:0 solid #dedede} 263table.grid-all>thead>tr>.tableblock,table.grid-all>tbody>tr>.tableblock{border-width:0 1px 1px 0} 264table.grid-all>tfoot>tr>.tableblock{border-width:1px 1px 0 0} 265table.grid-cols>*>tr>.tableblock{border-width:0 1px 0 0} 266table.grid-rows>thead>tr>.tableblock,table.grid-rows>tbody>tr>.tableblock{border-width:0 0 1px} 267table.grid-rows>tfoot>tr>.tableblock{border-width:1px 0 0} 268table.grid-all>*>tr>.tableblock:last-child,table.grid-cols>*>tr>.tableblock:last-child{border-right-width:0} 269table.grid-all>tbody>tr:last-child>.tableblock,table.grid-all>thead:last-child>tr>.tableblock,table.grid-rows>tbody>tr:last-child>.tableblock,table.grid-rows>thead:last-child>tr>.tableblock{border-bottom-width:0} 270table.frame-all{border-width:1px} 271table.frame-sides{border-width:0 1px} 272table.frame-topbot,table.frame-ends{border-width:1px 0} 273table.stripes-all tr,table.stripes-odd tr:nth-of-type(odd){background:#f8f8f7} 274table.stripes-none tr,table.stripes-odd tr:nth-of-type(even){background:none} 275th.halign-left,td.halign-left{text-align:left} 276th.halign-right,td.halign-right{text-align:right} 277th.halign-center,td.halign-center{text-align:center} 278th.valign-top,td.valign-top{vertical-align:top} 279th.valign-bottom,td.valign-bottom{vertical-align:bottom} 280th.valign-middle,td.valign-middle{vertical-align:middle} 281table thead th,table tfoot th{font-weight:bold} 282tbody tr th{display:table-cell;line-height:1.6;background:#f7f8f7} 283tbody tr th,tbody tr th p,tfoot tr th,tfoot tr th p{color:rgba(0,0,0,.8);font-weight:bold} 284p.tableblock>code:only-child{background:none;padding:0} 285p.tableblock{font-size:1em} 286td>div.verse{white-space:pre} 287ol{margin-left:1.75em} 288ul li ol{margin-left:1.5em} 289dl dd{margin-left:1.125em} 290dl dd:last-child,dl dd:last-child>:last-child{margin-bottom:0} 291ol>li p,ul>li p,ul dd,ol dd,.olist .olist,.ulist .ulist,.ulist .olist,.olist .ulist{margin-bottom:.625em} 292ul.checklist,ul.none,ol.none,ul.no-bullet,ol.no-bullet,ol.unnumbered,ul.unstyled,ol.unstyled{list-style-type:none} 293ul.no-bullet,ol.no-bullet,ol.unnumbered{margin-left:.625em} 294ul.unstyled,ol.unstyled{margin-left:0} 295ul.checklist{margin-left:.625em} 296ul.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} 297ul.checklist li>p:first-child>input[type="checkbox"]:first-child{margin-right:.25em} 298ul.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} 299ul.inline>li{margin-left:1.25em} 300.unstyled dl dt{font-weight:400;font-style:normal} 301ol.arabic{list-style-type:decimal} 302ol.decimal{list-style-type:decimal-leading-zero} 303ol.loweralpha{list-style-type:lower-alpha} 304ol.upperalpha{list-style-type:upper-alpha} 305ol.lowerroman{list-style-type:lower-roman} 306ol.upperroman{list-style-type:upper-roman} 307ol.lowergreek{list-style-type:lower-greek} 308.hdlist>table,.colist>table{border:0;background:none} 309.hdlist>table>tbody>tr,.colist>table>tbody>tr{background:none} 310td.hdlist1,td.hdlist2{vertical-align:top;padding:0 .625em} 311td.hdlist1{font-weight:bold;padding-bottom:1.25em} 312.literalblock+.colist,.listingblock+.colist{margin-top:-.5em} 313.colist td:not([class]):first-child{padding:.4em .75em 0;line-height:1;vertical-align:top} 314.colist td:not([class]):first-child img{max-width:none} 315.colist td:not([class]):last-child{padding:.25em 0} 316.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} 317.imageblock.left{margin:.25em .625em 1.25em 0} 318.imageblock.right{margin:.25em 0 1.25em .625em} 319.imageblock>.title{margin-bottom:0} 320.imageblock.thumb,.imageblock.th{border-width:6px} 321.imageblock.thumb>.title,.imageblock.th>.title{padding:0 .125em} 322.image.left,.image.right{margin-top:.25em;margin-bottom:.25em;display:inline-block;line-height:0} 323.image.left{margin-right:.625em} 324.image.right{margin-left:.625em} 325a.image{text-decoration:none;display:inline-block} 326a.image object{pointer-events:none} 327sup.footnote,sup.footnoteref{font-size:.875em;position:static;vertical-align:super} 328sup.footnote a,sup.footnoteref a{text-decoration:none} 329sup.footnote a:active,sup.footnoteref a:active{text-decoration:underline} 330#footnotes{padding-top:.75em;padding-bottom:.75em;margin-bottom:.625em} 331#footnotes hr{width:20%;min-width:6.25em;margin:-.25em 0 .75em;border-width:1px 0 0} 332#footnotes .footnote{padding:0 .375em 0 .225em;line-height:1.3334;font-size:.875em;margin-left:1.2em;margin-bottom:.2em} 333#footnotes .footnote a:first-of-type{font-weight:bold;text-decoration:none;margin-left:-1.05em} 334#footnotes .footnote:last-of-type{margin-bottom:0} 335#content #footnotes{margin-top:-.625em;margin-bottom:0;padding:.75em 0} 336.gist .file-data>table{border:0;background:#fff;width:100%;margin-bottom:0} 337.gist .file-data>table td.line-data{width:99%} 338div.unbreakable{page-break-inside:avoid} 339.big{font-size:larger} 340.small{font-size:smaller} 341.underline{text-decoration:underline} 342.overline{text-decoration:overline} 343.line-through{text-decoration:line-through} 344.aqua{color:#00bfbf} 345.aqua-background{background-color:#00fafa} 346.black{color:#000} 347.black-background{background-color:#000} 348.blue{color:#0000bf} 349.blue-background{background-color:#0000fa} 350.fuchsia{color:#bf00bf} 351.fuchsia-background{background-color:#fa00fa} 352.gray{color:#606060} 353.gray-background{background-color:#7d7d7d} 354.green{color:#006000} 355.green-background{background-color:#007d00} 356.lime{color:#00bf00} 357.lime-background{background-color:#00fa00} 358.maroon{color:#600000} 359.maroon-background{background-color:#7d0000} 360.navy{color:#000060} 361.navy-background{background-color:#00007d} 362.olive{color:#606000} 363.olive-background{background-color:#7d7d00} 364.purple{color:#600060} 365.purple-background{background-color:#7d007d} 366.red{color:#bf0000} 367.red-background{background-color:#fa0000} 368.silver{color:#909090} 369.silver-background{background-color:#bcbcbc} 370.teal{color:#006060} 371.teal-background{background-color:#007d7d} 372.white{color:#bfbfbf} 373.white-background{background-color:#fafafa} 374.yellow{color:#bfbf00} 375.yellow-background{background-color:#fafa00} 376span.icon>.fa{cursor:default} 377a span.icon>.fa{cursor:inherit} 378.admonitionblock td.icon [class^="fa icon-"]{font-size:2.5em;text-shadow:1px 1px 2px rgba(0,0,0,.5);cursor:default} 379.admonitionblock td.icon .icon-note::before{content:"\f05a";color:#19407c} 380.admonitionblock td.icon .icon-tip::before{content:"\f0eb";text-shadow:1px 1px 2px rgba(155,155,0,.8);color:#111} 381.admonitionblock td.icon .icon-warning::before{content:"\f071";color:#bf6900} 382.admonitionblock td.icon .icon-caution::before{content:"\f06d";color:#bf3400} 383.admonitionblock td.icon .icon-important::before{content:"\f06a";color:#bf0000} 384.conum[data-value]{display:inline-block;color:#fff!important;background-color:rgba(0,0,0,.8);-webkit-border-radius:100px;border-radius:100px;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} 385.conum[data-value] *{color:#fff!important} 386.conum[data-value]+b{display:none} 387.conum[data-value]::after{content:attr(data-value)} 388pre .conum[data-value]{position:relative;top:-.125em} 389b.conum *{color:inherit!important} 390.conum:not([data-value]):empty{display:none} 391dt,th.tableblock,td.content,div.footnote{text-rendering:optimizeLegibility} 392h1,h2,p,td.content,span.alt{letter-spacing:-.01em} 393p strong,td.content strong,div.footnote strong{letter-spacing:-.005em} 394p,blockquote,dt,td.content,span.alt{font-size:1.0625rem} 395p{margin-bottom:1.25rem} 396.sidebarblock p,.sidebarblock dt,.sidebarblock td.content,p.tableblock{font-size:1em} 397.exampleblock>.content{background-color:#fffef7;border-color:#e0e0dc;-webkit-box-shadow:0 1px 4px #e0e0dc;box-shadow:0 1px 4px #e0e0dc} 398.print-only{display:none!important} 399@page{margin:1.25cm .75cm} 400@media print{*{-webkit-box-shadow:none!important;box-shadow:none!important;text-shadow:none!important} 401html{font-size:80%} 402a{color:inherit!important;text-decoration:underline!important} 403a.bare,a[href^="#"],a[href^="mailto:"]{text-decoration:none!important} 404a[href^="http:"]:not(.bare)::after,a[href^="https:"]:not(.bare)::after{content:"(" attr(href) ")";display:inline-block;font-size:.875em;padding-left:.25em} 405abbr[title]::after{content:" (" attr(title) ")"} 406pre,blockquote,tr,img,object,svg{page-break-inside:avoid} 407thead{display:table-header-group} 408svg{max-width:100%} 409p,blockquote,dt,td.content{font-size:1em;orphans:3;widows:3} 410h2,h3,#toctitle,.sidebarblock>.content>.title{page-break-after:avoid} 411#toc,.sidebarblock,.exampleblock>.content{background:none!important} 412#toc{border-bottom:1px solid #dddddf!important;padding-bottom:0!important} 413body.book #header{text-align:center} 414body.book #header>h1:first-child{border:0!important;margin:2.5em 0 1em} 415body.book #header .details{border:0!important;display:block;padding:0!important} 416body.book #header .details span:first-child{margin-left:0!important} 417body.book #header .details br{display:block} 418body.book #header .details br+span::before{content:none!important} 419body.book #toc{border:0!important;text-align:left!important;padding:0!important;margin:0!important} 420body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-break-before:always} 421.listingblock code[data-lang]::before{display:block} 422#footer{padding:0 .9375em} 423.hide-on-print{display:none!important} 424.print-only{display:block!important} 425.hide-for-print{display:none!important} 426.show-for-print{display:inherit!important}} 427@media print,amzn-kf8{#header>h1:first-child{margin-top:1.25rem} 428.sect1{padding:0!important} 429.sect1+.sect1{border:0} 430#footer{background:none} 431#footer-text{color:rgba(0,0,0,.6);font-size:.9em}} 432@media amzn-kf8{#header,#content,#footnotes,#footer{padding:0}} 433</style> 434<style> 435.listingblock .pygments .hll { background-color: #ffffcc } 436.listingblock .pygments, .listingblock .pygments code { background: #f0f0f0; } 437.listingblock .pygments .tok-c { color: #60a0b0; font-style: italic } /* Comment */ 438.listingblock .pygments .tok-err { border: 1px solid #FF0000 } /* Error */ 439.listingblock .pygments .tok-k { color: #007020; font-weight: bold } /* Keyword */ 440.listingblock .pygments .tok-o { color: #666666 } /* Operator */ 441.listingblock .pygments .tok-ch { color: #60a0b0; font-style: italic } /* Comment.Hashbang */ 442.listingblock .pygments .tok-cm { color: #60a0b0; font-style: italic } /* Comment.Multiline */ 443.listingblock .pygments .tok-cp { color: #007020 } /* Comment.Preproc */ 444.listingblock .pygments .tok-cpf { color: #60a0b0; font-style: italic } /* Comment.PreprocFile */ 445.listingblock .pygments .tok-c1 { color: #60a0b0; font-style: italic } /* Comment.Single */ 446.listingblock .pygments .tok-cs { color: #60a0b0; background-color: #fff0f0 } /* Comment.Special */ 447.listingblock .pygments .tok-gd { color: #A00000 } /* Generic.Deleted */ 448.listingblock .pygments .tok-ge { font-style: italic } /* Generic.Emph */ 449.listingblock .pygments .tok-gr { color: #FF0000 } /* Generic.Error */ 450.listingblock .pygments .tok-gh { color: #000080; font-weight: bold } /* Generic.Heading */ 451.listingblock .pygments .tok-gi { color: #00A000 } /* Generic.Inserted */ 452.listingblock .pygments .tok-go { color: #888888 } /* Generic.Output */ 453.listingblock .pygments .tok-gp { color: #c65d09; font-weight: bold } /* Generic.Prompt */ 454.listingblock .pygments .tok-gs { font-weight: bold } /* Generic.Strong */ 455.listingblock .pygments .tok-gu { color: #800080; font-weight: bold } /* Generic.Subheading */ 456.listingblock .pygments .tok-gt { color: #0044DD } /* Generic.Traceback */ 457.listingblock .pygments .tok-kc { color: #007020; font-weight: bold } /* Keyword.Constant */ 458.listingblock .pygments .tok-kd { color: #007020; font-weight: bold } /* Keyword.Declaration */ 459.listingblock .pygments .tok-kn { color: #007020; font-weight: bold } /* Keyword.Namespace */ 460.listingblock .pygments .tok-kp { color: #007020 } /* Keyword.Pseudo */ 461.listingblock .pygments .tok-kr { color: #007020; font-weight: bold } /* Keyword.Reserved */ 462.listingblock .pygments .tok-kt { color: #902000 } /* Keyword.Type */ 463.listingblock .pygments .tok-m { color: #40a070 } /* Literal.Number */ 464.listingblock .pygments .tok-s { color: #4070a0 } /* Literal.String */ 465.listingblock .pygments .tok-na { color: #4070a0 } /* Name.Attribute */ 466.listingblock .pygments .tok-nb { color: #007020 } /* Name.Builtin */ 467.listingblock .pygments .tok-nc { color: #0e84b5; font-weight: bold } /* Name.Class */ 468.listingblock .pygments .tok-no { color: #60add5 } /* Name.Constant */ 469.listingblock .pygments .tok-nd { color: #555555; font-weight: bold } /* Name.Decorator */ 470.listingblock .pygments .tok-ni { color: #d55537; font-weight: bold } /* Name.Entity */ 471.listingblock .pygments .tok-ne { color: #007020 } /* Name.Exception */ 472.listingblock .pygments .tok-nf { color: #06287e } /* Name.Function */ 473.listingblock .pygments .tok-nl { color: #002070; font-weight: bold } /* Name.Label */ 474.listingblock .pygments .tok-nn { color: #0e84b5; font-weight: bold } /* Name.Namespace */ 475.listingblock .pygments .tok-nt { color: #062873; font-weight: bold } /* Name.Tag */ 476.listingblock .pygments .tok-nv { color: #bb60d5 } /* Name.Variable */ 477.listingblock .pygments .tok-ow { color: #007020; font-weight: bold } /* Operator.Word */ 478.listingblock .pygments .tok-w { color: #bbbbbb } /* Text.Whitespace */ 479.listingblock .pygments .tok-mb { color: #40a070 } /* Literal.Number.Bin */ 480.listingblock .pygments .tok-mf { color: #40a070 } /* Literal.Number.Float */ 481.listingblock .pygments .tok-mh { color: #40a070 } /* Literal.Number.Hex */ 482.listingblock .pygments .tok-mi { color: #40a070 } /* Literal.Number.Integer */ 483.listingblock .pygments .tok-mo { color: #40a070 } /* Literal.Number.Oct */ 484.listingblock .pygments .tok-sa { color: #4070a0 } /* Literal.String.Affix */ 485.listingblock .pygments .tok-sb { color: #4070a0 } /* Literal.String.Backtick */ 486.listingblock .pygments .tok-sc { color: #4070a0 } /* Literal.String.Char */ 487.listingblock .pygments .tok-dl { color: #4070a0 } /* Literal.String.Delimiter */ 488.listingblock .pygments .tok-sd { color: #4070a0; font-style: italic } /* Literal.String.Doc */ 489.listingblock .pygments .tok-s2 { color: #4070a0 } /* Literal.String.Double */ 490.listingblock .pygments .tok-se { color: #4070a0; font-weight: bold } /* Literal.String.Escape */ 491.listingblock .pygments .tok-sh { color: #4070a0 } /* Literal.String.Heredoc */ 492.listingblock .pygments .tok-si { color: #70a0d0; font-style: italic } /* Literal.String.Interpol */ 493.listingblock .pygments .tok-sx { color: #c65d09 } /* Literal.String.Other */ 494.listingblock .pygments .tok-sr { color: #235388 } /* Literal.String.Regex */ 495.listingblock .pygments .tok-s1 { color: #4070a0 } /* Literal.String.Single */ 496.listingblock .pygments .tok-ss { color: #517918 } /* Literal.String.Symbol */ 497.listingblock .pygments .tok-bp { color: #007020 } /* Name.Builtin.Pseudo */ 498.listingblock .pygments .tok-fm { color: #06287e } /* Name.Function.Magic */ 499.listingblock .pygments .tok-vc { color: #bb60d5 } /* Name.Variable.Class */ 500.listingblock .pygments .tok-vg { color: #bb60d5 } /* Name.Variable.Global */ 501.listingblock .pygments .tok-vi { color: #bb60d5 } /* Name.Variable.Instance */ 502.listingblock .pygments .tok-vm { color: #bb60d5 } /* Name.Variable.Magic */ 503.listingblock .pygments .tok-il { color: #40a070 } /* Literal.Number.Integer.Long */ 504</style> 505</head> 506<body class="article toc2 toc-left"> 507<div id="header"> 508<h1>B2 User Manual</h1> 509<div class="details"> 510<span id="author" class="author">Rene Rivera, Vladimir Prus, Steven Watanabe</span><br> 511</div> 512<div id="toc" class="toc2"> 513<div id="toctitle">Table of Contents</div> 514<ul class="sectlevel1"> 515<li><a href="#bbv2.installation">1. Installation</a></li> 516<li><a href="#bbv2.tutorial">2. Tutorial</a> 517<ul class="sectlevel2"> 518<li><a href="#bbv2.tutorial.hello">2.1. Hello, world</a></li> 519<li><a href="#bbv2.tutorial.properties">2.2. Properties</a> 520<ul class="sectlevel3"> 521<li><a href="#bbv2.tutorial.properties.requirements">2.2.1. Build Requests and Target Requirements</a></li> 522<li><a href="#bbv2.tutorial.properties.project_attributes">2.2.2. Project Attributes</a></li> 523</ul> 524</li> 525<li><a href="#bbv2.tutorial.hierarchy">2.3. Project Hierarchies</a></li> 526<li><a href="#bbv2.tutorial.libs">2.4. Dependent Targets</a></li> 527<li><a href="#bbv2.tutorial.linkage">2.5. Static and shared libraries</a></li> 528<li><a href="#bbv2.tutorial.conditions">2.6. Conditions and alternatives</a></li> 529<li><a href="#bbv2.tutorial.prebuilt">2.7. Prebuilt targets</a></li> 530</ul> 531</li> 532<li><a href="#bbv2.overview">3. Overview</a> 533<ul class="sectlevel2"> 534<li><a href="#bbv2.overview.concepts">3.1. Concepts</a></li> 535<li><a href="#bbv2.overview.jam_language">3.2. Boost.Jam Language</a></li> 536<li><a href="#bbv2.overview.configuration">3.3. Configuration</a></li> 537<li><a href="#bbv2.overview.invocation">3.4. Invocation</a> 538<ul class="sectlevel3"> 539<li><a href="#bbv2.overview.invocation.examples">3.4.1. Examples</a></li> 540<li><a href="#bbv2.overview.invocation.options">3.4.2. Options</a></li> 541<li><a href="#bbv2.overview.invocation.properties">3.4.3. Properties</a></li> 542<li><a href="#bbv2.overview.invocation.targets">3.4.4. Targets</a></li> 543</ul> 544</li> 545<li><a href="#bbv2.overview.targets">3.5. Declaring Targets</a> 546<ul class="sectlevel3"> 547<li><a href="#_name">3.5.1. Name</a></li> 548<li><a href="#_sources">3.5.2. Sources</a></li> 549<li><a href="#bbv2.overview.targets.requirements">3.5.3. Requirements</a></li> 550<li><a href="#_default_build">3.5.4. Default Build</a></li> 551<li><a href="#_additional_information">3.5.5. Additional Information</a></li> 552</ul> 553</li> 554<li><a href="#bbv2.overview.projects">3.6. Projects</a></li> 555<li><a href="#bbv2.overview.build_process">3.7. The Build Process</a> 556<ul class="sectlevel3"> 557<li><a href="#bbv2.overview.build_request">3.7.1. Build Request</a></li> 558<li><a href="#_building_a_main_target">3.7.2. Building a main target</a></li> 559<li><a href="#_building_a_project">3.7.3. Building a Project</a></li> 560</ul> 561</li> 562</ul> 563</li> 564<li><a href="#bbv2.tasks">4. Common tasks</a> 565<ul class="sectlevel2"> 566<li><a href="#bbv2.tasks.programs">4.1. Programs</a></li> 567<li><a href="#bbv2.tasks.libraries">4.2. Libraries</a></li> 568<li><a href="#bbv2.tasks.alias">4.3. Alias</a></li> 569<li><a href="#bbv2.tasks.installing">4.4. Installing</a> 570<ul class="sectlevel3"> 571<li><a href="#_basic_install">4.4.1. Basic install</a></li> 572<li><a href="#_installing_with_all_dependencies">4.4.2. Installing with all dependencies</a></li> 573<li><a href="#_preserving_directory_hierarchy">4.4.3. Preserving Directory Hierarchy</a></li> 574<li><a href="#_installing_into_several_directories">4.4.4. Installing into Several Directories</a></li> 575</ul> 576</li> 577<li><a href="#bbv2.builtins.testing">4.5. Testing</a></li> 578<li><a href="#bbv2.builtins.raw">4.6. Custom commands</a></li> 579<li><a href="#bbv2.reference.precompiled_headers">4.7. Precompiled Headers</a></li> 580<li><a href="#bbv2.reference.generated_headers">4.8. Generated headers</a></li> 581<li><a href="#bbv2.tasks.crosscompile">4.9. Cross-compilation</a></li> 582<li><a href="#bbv2.tasks.packagemanagers">4.10. Package Managers</a></li> 583</ul> 584</li> 585<li><a href="#bbv2.reference">5. Reference</a> 586<ul class="sectlevel2"> 587<li><a href="#bbv2.reference.general">5.1. General information</a> 588<ul class="sectlevel3"> 589<li><a href="#bbv2.reference.init">5.1.1. Initialization</a></li> 590</ul> 591</li> 592<li><a href="#bbv2.reference.rules">5.2. Builtin rules</a></li> 593<li><a href="#bbv2.overview.builtins.features">5.3. Builtin features</a></li> 594<li><a href="#bbv2.reference.tools">5.4. Builtin tools</a> 595<ul class="sectlevel3"> 596<li><a href="#bbv2.reference.tools.compilers">5.4.1. C++ Compilers</a></li> 597<li><a href="#_third_party_libraries">5.4.2. Third-party libraries</a></li> 598<li><a href="#_documentation_tools">5.4.3. Documentation tools</a></li> 599</ul> 600</li> 601<li><a href="#bbv2.reference.modules">5.5. Builtin modules</a> 602<ul class="sectlevel3"> 603<li><a href="#bbv2.reference.modules.modules">5.5.1. modules</a></li> 604<li><a href="#bbv2.reference.modules.path">5.5.2. path</a></li> 605<li><a href="#bbv2.reference.modules.regex">5.5.3. regex</a></li> 606<li><a href="#bbv2.reference.modules.sequence">5.5.4. sequence</a></li> 607<li><a href="#bbv2.reference.modules.stage">5.5.5. stage</a></li> 608<li><a href="#bbv2.reference.modules.type">5.5.6. type</a></li> 609</ul> 610</li> 611<li><a href="#bbv2.reference.class">5.6. Builtin classes</a> 612<ul class="sectlevel3"> 613<li><a href="#bbv2.reference.class.abstract-target">5.6.1. Class abstract-target</a></li> 614<li><a href="#bbv2.reference.class.project-target">5.6.2. Class project-target</a></li> 615<li><a href="#bbv2.reference.class.main-target">5.6.3. Class main-target</a></li> 616<li><a href="#bbv2.reference.class.basic-target">5.6.4. Class basic-target</a></li> 617<li><a href="#bbv2.reference.class.typed-target">5.6.5. Class typed-target</a></li> 618<li><a href="#bbv2.reference.class.property-set">5.6.6. Class property-set</a></li> 619</ul> 620</li> 621<li><a href="#bbv2.reference.buildprocess">5.7. Build process</a> 622<ul class="sectlevel3"> 623<li><a href="#bbv2.reference.buildprocess.alternatives">5.7.1. Alternative selection</a></li> 624<li><a href="#bbv2.reference.buildprocess.common">5.7.2. Determining common properties</a></li> 625<li><a href="#bbv2.reference.buildprocess.targetpath">5.7.3. Target Paths</a></li> 626</ul> 627</li> 628<li><a href="#bbv2.reference.definitions">5.8. Definitions</a> 629<ul class="sectlevel3"> 630<li><a href="#bbv2.reference.features">5.8.1. Features and properties</a></li> 631<li><a href="#bbv2.reference.features.validity">5.8.2. Property Validity</a></li> 632<li><a href="#bbv2.reference.features.attributes">5.8.3. Feature Attributes</a></li> 633<li><a href="#bbv2.reference.features.declaration">5.8.4. Feature Declaration</a></li> 634<li><a href="#bbv2.reference.variants.proprefine">5.8.5. Property refinement</a></li> 635<li><a href="#bbv2.reference.variants.propcond">5.8.6. Conditional properties</a></li> 636<li><a href="#bbv2.reference.ids">5.8.7. Target identifiers and references</a></li> 637</ul> 638</li> 639</ul> 640</li> 641<li><a href="#bbv2.util">6. Utilities</a> 642<ul class="sectlevel2"> 643<li><a href="#bbv2.util.debugger">6.1. Debugger</a> 644<ul class="sectlevel3"> 645<li><a href="#bbv2.util.debugger.overview">6.1.1. Overview</a></li> 646<li><a href="#bbv2.util.debugger.running">6.1.2. Running the Program</a></li> 647<li><a href="#bbv2.util.debugger.break">6.1.3. Breakpoints</a></li> 648<li><a href="#bbv2.util.debugger.stack">6.1.4. Examining the Stack</a></li> 649<li><a href="#bbv2.util.debugger.misc">6.1.5. Miscellaneous Commands</a></li> 650</ul> 651</li> 652</ul> 653</li> 654<li><a href="#bbv2.extender">7. Extender Manual</a> 655<ul class="sectlevel2"> 656<li><a href="#bbv2.extender.intro">7.1. Introduction</a> 657<ul class="sectlevel3"> 658<li><a href="#bbv2.extender.overview.metatargets">7.1.1. Metatargets</a></li> 659<li><a href="#bbv2.extender.overview.targets">7.1.2. Concrete targets</a></li> 660<li><a href="#bbv2.extender.overview.generators">7.1.3. Generators</a></li> 661</ul> 662</li> 663<li><a href="#bbv2.extender.example">7.2. Example: 1-to-1 generator</a></li> 664<li><a href="#bbv2.extending.targets">7.3. Target types</a></li> 665<li><a href="#bbv2.extending.scanners">7.4. Scanners</a></li> 666<li><a href="#bbv2.extending.tools">7.5. Tools and generators</a></li> 667<li><a href="#bbv2.extending.features">7.6. Features</a></li> 668<li><a href="#bbv2.extending.rules">7.7. Main target rules</a></li> 669<li><a href="#bbv2.extending.toolset_modules">7.8. Toolset modules</a></li> 670</ul> 671</li> 672<li><a href="#bbv2.faq">8. Frequently Asked Questions</a> 673<ul class="sectlevel2"> 674<li><a href="#bbv2.faq.featurevalue">8.1. How do I get the current value of feature in Jamfile?</a></li> 675<li><a href="#bbv2.faq.duplicate">8.2. I am getting a "Duplicate name of actual target" error. What does that mean?</a></li> 676<li><a href="#bbv2.faq.envar">8.3. Accessing environment variables</a></li> 677<li><a href="#bbv2.faq.proporder">8.4. How to control properties order?</a></li> 678<li><a href="#bbv2.faq.liborder">8.5. How to control the library linking order on Unix?</a></li> 679<li><a href="#bbv2.faq.external">8.6. Can I get capture external program output using a Boost.Jam variable?</a></li> 680<li><a href="#bbv2.faq.projectroot">8.7. How to get the project root (a.k.a. Jamroot) location?</a></li> 681<li><a href="#bbv2.faq.flags">8.8. How to change compilation flags for one file?</a></li> 682<li><a href="#bbv2.faq.dll-path">8.9. Why are the <code>dll-path</code> and <code>hardcode-dll-paths</code> properties useful?</a></li> 683<li><a href="#bbv2.recipes.site-config">8.10. Targets in site-config.jam</a></li> 684<li><a href="#bbv2.faq.header-only-libraries">8.11. Header-only libraries</a></li> 685<li><a href="#bbv2.faq.names">8.12. What is the difference between B2, <code>b2</code>, <code>bjam</code> and Perforce Jam?</a></li> 686</ul> 687</li> 688<li><a href="#_extra_tools">9. Extra Tools</a> 689<ul class="sectlevel2"> 690<li><a href="#_documentation_tools_2">9.1. Documentation Tools</a> 691<ul class="sectlevel3"> 692<li><a href="#_asciidoctor">9.1.1. Asciidoctor</a></li> 693</ul> 694</li> 695<li><a href="#_miscellaneous_tools">9.2. Miscellaneous Tools</a> 696<ul class="sectlevel3"> 697<li><a href="#_pkg_config">9.2.1. pkg-config</a></li> 698<li><a href="#_sass">9.2.2. Sass</a></li> 699</ul> 700</li> 701</ul> 702</li> 703<li><a href="#_examples">10. Examples</a> 704<ul class="sectlevel2"> 705<li><a href="#_introduction">10.1. Introduction</a></li> 706<li><a href="#_hello">10.2. Hello</a></li> 707<li><a href="#_sanitizers">10.3. Sanitizers</a></li> 708</ul> 709</li> 710<li><a href="#bbv2.jam">11. Boost.Jam Documentation</a> 711<ul class="sectlevel2"> 712<li><a href="#jam.building">11.1. Building B2</a></li> 713<li><a href="#jam.language">11.2. Language</a> 714<ul class="sectlevel3"> 715<li><a href="#jam.language.lexical">11.2.1. Lexical Features</a></li> 716<li><a href="#jam.language.target">11.2.2. Targets</a></li> 717<li><a href="#jam.language.rules">11.2.3. Rules</a></li> 718<li><a href="#jam.language.rules.builtins">11.2.4. Built-in Rules</a></li> 719<li><a href="#jam.language.flow_of_control">11.2.5. Flow-of-Control</a></li> 720<li><a href="#jam.language.variables">11.2.6. Variables</a></li> 721<li><a href="#jam.language.modules">11.2.7. Modules</a></li> 722</ul> 723</li> 724<li><a href="#jam.miscellaneous">11.3. Miscellaneous</a> 725<ul class="sectlevel3"> 726<li><a href="#jam.miscellaneous.diagnostics">11.3.1. Diagnostics</a></li> 727<li><a href="#jam.miscellaneous.bugs__limitations">11.3.2. Bugs, Limitations</a></li> 728<li><a href="#jam.miscellaneous.fundamentals">11.3.3. Fundamentals</a></li> 729</ul> 730</li> 731</ul> 732</li> 733<li><a href="#b2.history">12. History</a> 734<ul class="sectlevel2"> 735<li><a href="#_version_4_3_0">12.1. Version 4.3.0</a></li> 736<li><a href="#_version_4_2_0">12.2. Version 4.2.0</a></li> 737<li><a href="#_version_4_1_0">12.3. Version 4.1.0</a></li> 738<li><a href="#_version_4_0_1">12.4. Version 4.0.1</a></li> 739<li><a href="#_version_4_0_0">12.5. Version 4.0.0</a></li> 740</ul> 741</li> 742</ul> 743</div> 744</div> 745<div id="content"> 746<div id="preamble"> 747<div class="sectionbody"> 748<style> 749.admonitionblock .icon .title { 750 font-size: 2.5em; 751 text-shadow: 1px 1px 2px rgba(0, 0, 0, .5); 752} 753.caution .icon .title { 754 color: rgba(192, 51, 0, 1); 755} 756.important .icon .title { 757 color: rgba(192, 0, 0, 1); 758} 759.note .icon .title { 760 color: rgba(26, 64, 128, 1); 761} 762.tip .icon .title { 763 color: rgba(255, 192, 0, 1); 764} 765.warning .icon .title { 766 color: rgba(192, 102, 0, 1); 767} 768p,blockquote,dt,td.content,span.alt { 769 font-size: 1.1rem 770} 771h1, h2, h3, h4, h5, h6 { 772 font-weight: bold; 773} 774h1 { 775 font-size: 2.25em; 776} 777h2 { 778 font-size: 1.5em; 779} 780h3,#toctitle,.sidebarblock>.content>.title { 781 font-size: 1.3em; 782} 783h4, h5 { 784 font-size: 1.2em; 785} 786h6 { 787 font-size: 1.1em; 788} 789</style> 790<div class="paragraph"> 791<p>Want to learn about B2 features? Start with the 792<a href="#bbv2.tutorial">tutorial</a> and continue with the <a href="#bbv2.overview">overview</a>. 793When you’re ready to try B2 in practice, go to the 794<a href="#bbv2.installation">installation</a>.</p> 795</div> 796<div class="paragraph"> 797<p>Building a project with B2? See the <a href="#bbv2.installation">installation</a> 798and then read the <a href="#bbv2.overview.invocation">overview</a>.</p> 799</div> 800<div class="paragraph"> 801<p>Setting up B2 on your project? Take a look at the 802<a href="#bbv2.overview">overview</a> and <a href="#bbv2.extender">extender manual</a>.</p> 803</div> 804<div class="paragraph"> 805<p>If there’s anything you find unclear in this documentation, report the 806problem directly in the <a href="https://github.com/boostorg/build/issues">issue 807tracker</a>. For more general questions, please post them to our mailing 808list (<a href="http://boost.org/more/mailing_lists.htm#jamboost" class="bare">http://boost.org/more/mailing_lists.htm#jamboost</a>).</p> 809</div> 810<div class="sidebarblock"> 811<div class="content"> 812<div class="paragraph"> 813<p>Copyright 2006, 2014 <a href="http://vladimirprus.com">Vladimir Prus</a>. Distributed 814under the Boost Software License, Version 1.0. (See accompanying file 815<code>LICENSE_1_0.txt</code> or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" class="bare">http://www.boost.org/LICENSE_1_0.txt</a>)</p> 816</div> 817</div> 818</div> 819<!-- toc disabled --> 820</div> 821</div> 822<div class="sect1"> 823<h2 id="bbv2.installation"><a class="anchor" href="#bbv2.installation"></a>1. Installation</h2> 824<div class="sectionbody"> 825<div class="paragraph"> 826<p>To install B2 from an official release or a nightly build, as 827available on the <a href="http://boost.org/boost-build2">official web site</a>, 828follow these steps:</p> 829</div> 830<div class="olist arabic"> 831<ol class="arabic"> 832<li> 833<p>Unpack the release. On the command line, go to the root of the 834unpacked tree.</p> 835</li> 836<li> 837<p>Run either <code>.\bootstrap.bat</code> (on Windows), or <code>./bootstrap.sh</code> (on 838other operating systems).</p> 839</li> 840<li> 841<p>Run</p> 842<div class="listingblock"> 843<div class="content"> 844<pre class="pygments highlight"><code data-lang="shell"><span></span>$ ./b2 install --prefix<span class="tok-o">=</span>PREFIX</code></pre> 845</div> 846</div> 847<div class="paragraph"> 848<p>where PREFIX is a directory where you want B2 to be installed.</p> 849</div> 850</li> 851<li> 852<p>Optionally, add <code>PREFIX/bin</code> to your PATH environment variable.</p> 853</li> 854</ol> 855</div> 856<div class="paragraph"> 857<p>If you are not using a B2 package, but rather the version 858bundled with the Boost C++ Libraries, the above commands should be run 859in the <code>tools/build</code> directory.</p> 860</div> 861<div class="paragraph"> 862<p>Now that B2 is installed, you can try some of the examples. 863Copy <code>PREFIX/share/boost-build/examples/hello</code> to a different directory, 864then change to that directory and run:</p> 865</div> 866<div class="listingblock"> 867<div class="content"> 868<pre class="pygments highlight"><code data-lang="shell"><span></span>$ PREFIX/bin/b2</code></pre> 869</div> 870</div> 871<div class="paragraph"> 872<p>A simple executable should be built.</p> 873</div> 874</div> 875</div> 876<div class="sect1"> 877<h2 id="bbv2.tutorial"><a class="anchor" href="#bbv2.tutorial"></a>2. Tutorial</h2> 878<div class="sectionbody"> 879<div class="paragraph"> 880<p>This section will guide you though the most basic features of 881B2. We will start with the “Hello, world” example, learn how to 882use libraries, and finish with testing and installing features.</p> 883</div> 884<div class="sect2"> 885<h3 id="bbv2.tutorial.hello"><a class="anchor" href="#bbv2.tutorial.hello"></a>2.1. Hello, world</h3> 886<div class="paragraph"> 887<p>The simplest project that B2 can construct is stored in 888<code>example/hello/</code> directory. The project is described by a file called 889<code>Jamfile</code> that contains:</p> 890</div> 891<div class="listingblock"> 892<div class="content"> 893<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-nb">exe</span><span class="tok-w"> </span>hello<span class="tok-w"> </span>:<span class="tok-w"> </span>hello.cpp<span class="tok-w"> </span>;<span class="tok-w"></span></code></pre> 894</div> 895</div> 896<div class="paragraph"> 897<p>Even with this simple setup, you can do some interesting things. First 898of all, just invoking <code>b2</code> will build the <code>hello</code> executable by compiling 899and linking <code>hello.cpp</code>. By default, the debug variant is built. Now, to 900build the release variant of <code>hello</code>, invoke</p> 901</div> 902<div class="listingblock"> 903<div class="content"> 904<pre class="pygments highlight"><code data-lang="shell"><span></span>b2 release</code></pre> 905</div> 906</div> 907<div class="paragraph"> 908<p>Note that the debug and release variants are created in different 909directories, so you can switch between variants or even build multiple 910variants at once, without any unnecessary recompilation. Let us extend 911the example by adding another line to our project’s <code>Jamfile</code>:</p> 912</div> 913<div class="listingblock"> 914<div class="content"> 915<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-nb">exe</span><span class="tok-w"> </span>hello2<span class="tok-w"> </span>:<span class="tok-w"> </span>hello.cpp<span class="tok-w"> </span>;<span class="tok-w"></span></code></pre> 916</div> 917</div> 918<div class="paragraph"> 919<p>Now let us build both the debug and release variants of our project 920again:</p> 921</div> 922<div class="listingblock"> 923<div class="content"> 924<pre class="pygments highlight"><code data-lang="shell"><span></span>b2 debug release</code></pre> 925</div> 926</div> 927<div class="paragraph"> 928<p>Note that two variants of <code>hello2</code> are linked. Since we have already 929built both variants of <code>hello</code>, hello.cpp will not be recompiled; 930instead the existing object files will just be linked into the 931corresponding variants of <code>hello2</code>. Now let us remove all the built 932products:</p> 933</div> 934<div class="listingblock"> 935<div class="content"> 936<pre class="pygments highlight"><code data-lang="shell"><span></span>b2 --clean debug release</code></pre> 937</div> 938</div> 939<div class="paragraph"> 940<p>It is also possible to build or clean specific targets. The following 941two commands, respectively, build or clean only the debug version of 942<code>hello2</code>.</p> 943</div> 944<div class="listingblock"> 945<div class="content"> 946<pre class="pygments highlight"><code data-lang="shell"><span></span>b2 hello2 947b2 --clean hello2</code></pre> 948</div> 949</div> 950</div> 951<div class="sect2"> 952<h3 id="bbv2.tutorial.properties"><a class="anchor" href="#bbv2.tutorial.properties"></a>2.2. Properties</h3> 953<div class="paragraph"> 954<p>To represent aspects of target configuration such as debug and release 955variants, or single- and multi-threaded builds portably, B2 956uses <em>features</em> with associated <em>values</em>. For example, the <code>debug-symbols</code> 957feature can have a value of <code>on</code> or <code>off</code>. A <em>property</em> is just a 958(feature, value) pair. When a user initiates a build, B2 959automatically translates the requested properties into appropriate 960command-line flags for invoking toolset components like compilers and 961linkers.</p> 962</div> 963<div class="paragraph"> 964<p>There are many built-in features that can be combined to produce 965arbitrary build configurations. The following command builds the 966project’s <code>release</code> variant with inlining disabled and debug symbols 967enabled:</p> 968</div> 969<div class="listingblock"> 970<div class="content"> 971<pre class="pygments highlight"><code data-lang="shell"><span></span>b2 release <span class="tok-nv">inlining</span><span class="tok-o">=</span>off debug-symbols<span class="tok-o">=</span>on</code></pre> 972</div> 973</div> 974<div class="paragraph"> 975<p>Properties on the command-line are specified with the syntax:</p> 976</div> 977<div class="listingblock"> 978<div class="content"> 979<pre>feature-name=feature-value</pre> 980</div> 981</div> 982<div class="paragraph"> 983<p>The <code>release</code> and <code>debug</code> that we have seen in <code>b2</code> invocations are just 984a shorthand way to specify values of the <code>variant</code> feature. For example, 985the command above could also have been written this way:</p> 986</div> 987<div class="listingblock"> 988<div class="content"> 989<pre class="pygments highlight"><code data-lang="shell"><span></span>b2 <span class="tok-nv">variant</span><span class="tok-o">=</span>release <span class="tok-nv">inlining</span><span class="tok-o">=</span>off debug-symbols<span class="tok-o">=</span>on</code></pre> 990</div> 991</div> 992<div class="paragraph"> 993<p><code>variant</code> is so commonly-used that it has been given special status as 994an <em>implicit</em> feature—B2 will deduce its identity just from the 995name of one of its values.</p> 996</div> 997<div class="paragraph"> 998<p>A complete description of features can be found in 999<a href="#bbv2.reference.features">the section called “Features and properties”</a>.</p> 1000</div> 1001<div class="sect3"> 1002<h4 id="bbv2.tutorial.properties.requirements"><a class="anchor" href="#bbv2.tutorial.properties.requirements"></a>2.2.1. Build Requests and Target Requirements</h4> 1003<div class="paragraph"> 1004<p>The set of properties specified on the command line constitutes a <em>build 1005request</em>—a description of the desired properties for building the 1006requested targets (or, if no targets were explicitly requested, the 1007project in the current directory). The <em>actual</em> properties used for 1008building targets are typically a combination of the build request and 1009properties derived from the project’s <code>Jamfile</code> (and its other Jamfiles, 1010as described in 1011<a href="#bbv2.tutorial.hierarchy">the section called “Project Hierarchies”</a>). 1012For example, the locations of `#include`d header files are normally not 1013specified on the command-line, but described in Jamfiles as <em>target 1014requirements</em> and automatically combined with the build request for those 1015targets. Multi-threaded compilation is another example of a typical 1016target requirement. The Jamfile fragment below illustrates how these 1017requirements might be specified.</p> 1018</div> 1019<div class="listingblock"> 1020<div class="content"> 1021<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-nb">exe</span><span class="tok-w"> </span>hello<span class="tok-w"></span> 1022<span class="tok-w"> </span>:<span class="tok-w"> </span>hello.cpp<span class="tok-w"></span> 1023<span class="tok-w"> </span>:<span class="tok-w"> </span><span class="tok-na"><include></span>boost<span class="tok-w"> </span><span class="tok-na"><threading></span>multi<span class="tok-w"></span> 1024<span class="tok-w"> </span>;<span class="tok-w"></span></code></pre> 1025</div> 1026</div> 1027<div class="paragraph"> 1028<p>When <code>hello</code> is built, the two requirements specified above will always 1029be present. If the build request given on the <code>b2</code> command-line 1030explicitly contradicts a target’s requirements, the target requirements 1031usually override (or, in the case of “free” features like 1032<code><include></code>, <sup class="footnote">[<a id="_footnoteref_1" class="footnote" href="#_footnotedef_1" title="View footnote.">1</a>]</sup> 1033augment) the build request.</p> 1034</div> 1035<div class="admonitionblock tip"> 1036<table> 1037<tr> 1038<td class="icon"> 1039<div class="title">☀</div> 1040</td> 1041<td class="content"> 1042The value of the <code><include></code> feature is relative to the location of 1043<code>Jamfile</code> where it is used. 1044</td> 1045</tr> 1046</table> 1047</div> 1048</div> 1049<div class="sect3"> 1050<h4 id="bbv2.tutorial.properties.project_attributes"><a class="anchor" href="#bbv2.tutorial.properties.project_attributes"></a>2.2.2. Project Attributes</h4> 1051<div class="paragraph"> 1052<p>If we want the same requirements for our other target, <code>hello2</code>, we 1053could simply duplicate them. However, as projects grow, that approach 1054leads to a great deal of repeated boilerplate in Jamfiles. Fortunately, 1055there’s a better way. Each project can specify a set of <em>attributes</em>, 1056including requirements:</p> 1057</div> 1058<div class="listingblock"> 1059<div class="content"> 1060<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-nb">project</span><span class="tok-w"></span> 1061<span class="tok-w"> </span>:<span class="tok-w"> </span>requirements<span class="tok-w"> </span><span class="tok-na"><include></span>/home/ghost/Work/boost<span class="tok-w"> </span><span class="tok-na"><threading></span>multi<span class="tok-w"></span> 1062<span class="tok-w"> </span>;<span class="tok-w"></span> 1063 1064<span class="tok-nb">exe</span><span class="tok-w"> </span>hello<span class="tok-w"> </span>:<span class="tok-w"> </span>hello.cpp<span class="tok-w"> </span>;<span class="tok-w"></span> 1065<span class="tok-nb">exe</span><span class="tok-w"> </span>hello2<span class="tok-w"> </span>:<span class="tok-w"> </span>hello.cpp<span class="tok-w"> </span>;<span class="tok-w"></span></code></pre> 1066</div> 1067</div> 1068<div class="paragraph"> 1069<p>The effect would be as if we specified the same requirement for both 1070<code>hello</code> and <code>hello2</code>.</p> 1071</div> 1072</div> 1073</div> 1074<div class="sect2"> 1075<h3 id="bbv2.tutorial.hierarchy"><a class="anchor" href="#bbv2.tutorial.hierarchy"></a>2.3. Project Hierarchies</h3> 1076<div class="paragraph"> 1077<p>So far we have only considered examples with one project, with one 1078user-written <code>Jamfile</code> file. A typical large codebase would 1079be composed of many projects organized into a tree. The top of the tree 1080is called the <em>project root</em>. Every subproject is defined by a file called 1081<code>Jamfile</code> in a descendant directory of the project root. The parent 1082project of a subproject is defined by the nearest Jamfile 1083file in an ancestor directory. For example, in the following directory 1084layout:</p> 1085</div> 1086<div class="literalblock"> 1087<div class="content"> 1088<pre>top/ 1089 | 1090 +-- Jamfile 1091 | 1092 +-- app/ 1093 | | 1094 | +-- Jamfile 1095 | `-- app.cpp 1096 | 1097 `-- util/ 1098 | 1099 +-- foo/ 1100 . | 1101 . +-- Jamfile 1102 . `-- bar.cpp</pre> 1103</div> 1104</div> 1105<div class="paragraph"> 1106<p>the project root is <code>top/</code>. The projects in <code>top/app/</code> and 1107<code>top/util/foo/</code> are immediate children of the root project.</p> 1108</div> 1109<div class="admonitionblock note"> 1110<table> 1111<tr> 1112<td class="icon"> 1113<div class="title">ℹ</div> 1114</td> 1115<td class="content"> 1116When we refer to a “Jamfile,” set in normal type, we mean a file called 1117either <code>Jamfile</code> or <code>Jamroot</code>. When we need to be more specific, the 1118filename will be set as “<code>Jamfile</code>” or “<code>Jamroot</code>.” 1119</td> 1120</tr> 1121</table> 1122</div> 1123<div class="paragraph"> 1124<p>Projects inherit all attributes (such as requirements) from their 1125parents. Inherited requirements are combined with any requirements 1126specified by the subproject. For example, if <code>top/Jamfile</code> has</p> 1127</div> 1128<div class="listingblock"> 1129<div class="content"> 1130<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-na"><include></span>/home/ghost/local<span class="tok-w"></span></code></pre> 1131</div> 1132</div> 1133<div class="paragraph"> 1134<p>in its requirements, then all of its sub-projects will have it in their 1135requirements, too. Of course, any project can add include paths to those 1136specified by its parents. <sup class="footnote">[<a id="_footnoteref_2" class="footnote" href="#_footnotedef_2" title="View footnote.">2</a>]</sup> More 1137details can be found in <a href="#bbv2.overview.projects">the section called “Projects”</a>.</p> 1138</div> 1139<div class="paragraph"> 1140<p>Invoking <code>b2</code> without explicitly specifying any targets on the command 1141line builds the project rooted in the current directory. Building a 1142project does not automatically cause its sub-projects to be built unless 1143the parent project’s Jamfile explicitly requests it. In our example, 1144<code>top/Jamfile</code> might contain:</p> 1145</div> 1146<div class="listingblock"> 1147<div class="content"> 1148<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-nb">build-project</span><span class="tok-w"> </span>app<span class="tok-w"> </span>;<span class="tok-w"></span></code></pre> 1149</div> 1150</div> 1151<div class="paragraph"> 1152<p>which would cause the project in <code>top/app/</code> to be built whenever the 1153project in <code>top/</code> is built. However, targets in <code>top/util/foo/</code> will be 1154built only if they are needed by targets in <code>top/</code> or <code>top/app/</code>.</p> 1155</div> 1156</div> 1157<div class="sect2"> 1158<h3 id="bbv2.tutorial.libs"><a class="anchor" href="#bbv2.tutorial.libs"></a>2.4. Dependent Targets</h3> 1159<div class="paragraph"> 1160<p>When building a target <code>X</code> that depends on first building another target 1161<code>Y</code> (such as a library that must be linked with X), <code>Y</code> is called a 1162<em>dependency</em> of <code>X</code> and <code>X</code> is termed a <em>dependent</em> of <code>Y</code>.</p> 1163</div> 1164<div class="paragraph"> 1165<p>To get a feeling of target dependencies, let’s continue the above 1166example and see how <code>top/app/Jamfile</code> can use libraries from 1167<code>top/util/foo</code>. If <code>top/util/foo/Jamfile</code> contains</p> 1168</div> 1169<div class="listingblock"> 1170<div class="content"> 1171<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-nb">lib</span><span class="tok-w"> </span>bar<span class="tok-w"> </span>:<span class="tok-w"> </span>bar.cpp<span class="tok-w"> </span>;<span class="tok-w"></span></code></pre> 1172</div> 1173</div> 1174<div class="paragraph"> 1175<p>then to use this library in <code>top/app/Jamfile</code>, we can write:</p> 1176</div> 1177<div class="listingblock"> 1178<div class="content"> 1179<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-nb">exe</span><span class="tok-w"> </span>app<span class="tok-w"> </span>:<span class="tok-w"> </span>app.cpp<span class="tok-w"> </span>../util/foo//bar<span class="tok-w"> </span>;<span class="tok-w"></span></code></pre> 1180</div> 1181</div> 1182<div class="paragraph"> 1183<p>While <code>app.cpp</code> refers to a regular source file, <code>../util/foo//bar</code> is a 1184reference to another target: a library <code>bar</code> declared in the Jamfile at 1185<code>../util/foo</code>.</p> 1186</div> 1187<div class="admonitionblock tip"> 1188<table> 1189<tr> 1190<td class="icon"> 1191<div class="title">☀</div> 1192</td> 1193<td class="content"> 1194Some other build system have special syntax for listing dependent 1195libraries, for example <code>LIBS</code> variable. In B2, you just add the 1196library to the list of sources. 1197</td> 1198</tr> 1199</table> 1200</div> 1201<div class="paragraph"> 1202<p>Suppose we build <code>app</code> with:</p> 1203</div> 1204<div class="listingblock"> 1205<div class="content"> 1206<pre class="pygments highlight"><code data-lang="shell"><span></span>b2 app <span class="tok-nv">optimization</span><span class="tok-o">=</span>full <span class="tok-nv">define</span><span class="tok-o">=</span>USE_ASM</code></pre> 1207</div> 1208</div> 1209<div class="paragraph"> 1210<p>Which properties will be used to build <code>foo</code>? The answer is that some 1211features are <em>propagated</em> — B2 attempts to use dependencies with 1212the same value of propagated features. The <code><optimization></code> feature is 1213propagated, so both <code>app</code> and <code>foo</code> will be compiled with full 1214optimization. But <code><define></code> is not propagated: its value will be added 1215as-is to the compiler flags for <code>a.cpp</code>, but won’t affect <code>foo</code>.</p> 1216</div> 1217<div class="paragraph"> 1218<p>Let’s improve this project further. The library probably has some 1219headers that must be used when compiling <code>app.cpp</code>. We could manually 1220add the necessary <code>#include</code> paths to <code>app’s requirements as values of 1221the `<include> ` feature, but then this work will be repeated for all 1222programs that use `foo</code>. A better solution is to modify 1223<code>util/foo/Jamfile</code> in this way:</p> 1224</div> 1225<div class="listingblock"> 1226<div class="content"> 1227<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-nb">project</span><span class="tok-w"></span> 1228<span class="tok-w"> </span>:<span class="tok-w"> </span>usage-requirements<span class="tok-w"> </span><span class="tok-na"><include></span>.<span class="tok-w"></span> 1229<span class="tok-w"> </span>;<span class="tok-w"></span> 1230 1231<span class="tok-nb">lib</span><span class="tok-w"> </span>foo<span class="tok-w"> </span>:<span class="tok-w"> </span>foo.cpp<span class="tok-w"> </span>;<span class="tok-w"></span></code></pre> 1232</div> 1233</div> 1234<div class="paragraph"> 1235<p>Usage requirements are applied not to the target being declared but to 1236its dependents. In this case, <code><include>.</code> will be applied to all 1237targets that directly depend on <code>foo</code>.</p> 1238</div> 1239<div class="paragraph"> 1240<p>Another improvement is using symbolic identifiers to refer to the 1241library, as opposed to <code>Jamfile</code> location. In a large project, a library 1242can be used by many targets, and if they all use <code>Jamfile</code> location, a change 1243in directory organization entails much work. 1244The solution is to use project ids—symbolic names not tied to directory 1245layout. First, we need to assign a project id by adding this code to 1246<code>Jamfile</code>:</p> 1247</div> 1248<div class="listingblock"> 1249<div class="content"> 1250<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-nb">use-project</span><span class="tok-w"> </span>/library-example/foo<span class="tok-w"> </span>:<span class="tok-w"> </span>util/foo<span class="tok-w"> </span>;<span class="tok-w"></span></code></pre> 1251</div> 1252</div> 1253<div class="paragraph"> 1254<p>Second, we modify <code>app/Jamfile</code> to use the project id:</p> 1255</div> 1256<div class="listingblock"> 1257<div class="content"> 1258<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-nb">exe</span><span class="tok-w"> </span>app<span class="tok-w"> </span>:<span class="tok-w"> </span>app.cpp<span class="tok-w"> </span>/library-example/foo//bar<span class="tok-w"> </span>;<span class="tok-w"></span></code></pre> 1259</div> 1260</div> 1261<div class="paragraph"> 1262<p>The <code>/library-example/foo//bar</code> syntax is used to refer to the target 1263<code>bar</code> in the project with id <code>/library-example/foo</code>. We’ve achieved our 1264goal—if the library is moved to a different directory, only <code>top/Jamfile</code> 1265must be modified. Note that project ids are global—two Jamfiles 1266are not allowed to assign the same project id to different directories.</p> 1267</div> 1268<div class="admonitionblock tip"> 1269<table> 1270<tr> 1271<td class="icon"> 1272<div class="title">☀</div> 1273</td> 1274<td class="content"> 1275<div class="paragraph"> 1276<p>If you want all applications in some project to link to a certain 1277library, you can avoid having to specify directly the sources of every 1278target by using the <code><library></code> property. For example, if 1279<code>/boost/filesystem//fs</code> should be linked to all applications in your 1280project, you can add <code><library>/boost/filesystem//fs</code> to the project’s 1281requirements, like this:</p> 1282</div> 1283<div class="listingblock"> 1284<div class="content"> 1285<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-nb">project</span><span class="tok-w"></span> 1286<span class="tok-w"> </span>:<span class="tok-w"> </span>requirements<span class="tok-w"> </span><span class="tok-na"><library></span>/boost/filesystem//fs<span class="tok-w"></span> 1287<span class="tok-w"> </span>;<span class="tok-w"></span></code></pre> 1288</div> 1289</div> 1290</td> 1291</tr> 1292</table> 1293</div> 1294</div> 1295<div class="sect2"> 1296<h3 id="bbv2.tutorial.linkage"><a class="anchor" href="#bbv2.tutorial.linkage"></a>2.5. Static and shared libraries</h3> 1297<div class="paragraph"> 1298<p>Libraries can be either <em>static</em>, which means they are included in 1299executable files that use them, or <em>shared</em> (a.k.a. <em>dynamic</em>), which 1300are only referred to from executables, and must be available at run 1301time. B2 can create and use both kinds.</p> 1302</div> 1303<div class="paragraph"> 1304<p>The kind of library produced from a <code>lib</code> target is determined by the 1305value of the <code>link</code> feature. Default value is <code>shared</code>, and to build a 1306static library, the value should be <code>static</code>. You can request a static 1307build either on the command line:</p> 1308</div> 1309<div class="listingblock"> 1310<div class="content"> 1311<pre class="pygments highlight"><code data-lang="shell"><span></span>b2 <span class="tok-nv">link</span><span class="tok-o">=</span>static</code></pre> 1312</div> 1313</div> 1314<div class="paragraph"> 1315<p>or in the library’s requirements:</p> 1316</div> 1317<div class="listingblock"> 1318<div class="content"> 1319<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-nb">lib</span><span class="tok-w"> </span>l<span class="tok-w"> </span>:<span class="tok-w"> </span>l.cpp<span class="tok-w"> </span>:<span class="tok-w"> </span><span class="tok-na"><link></span>static<span class="tok-w"> </span>;<span class="tok-w"></span></code></pre> 1320</div> 1321</div> 1322<div class="paragraph"> 1323<p>We can also use the <code><link></code> property to express linking requirements on 1324a per-target basis. For example, if a particular executable can be 1325correctly built only with the static version of a library, we can 1326qualify the executable’s <a href="#bbv2.reference.targets.references">target 1327reference</a> to the library as follows:</p> 1328</div> 1329<div class="listingblock"> 1330<div class="content"> 1331<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-nb">exe</span><span class="tok-w"> </span>important<span class="tok-w"> </span>:<span class="tok-w"> </span>main.cpp<span class="tok-w"> </span>helpers/<span class="tok-na"><link></span>static<span class="tok-w"> </span>;<span class="tok-w"></span></code></pre> 1332</div> 1333</div> 1334<div class="paragraph"> 1335<p>No matter what arguments are specified on the <code>b2</code> command line, 1336<code>important</code> will only be linked with the static version of <code>helpers</code>.</p> 1337</div> 1338<div class="paragraph"> 1339<p>Specifying properties in target references is especially useful if you 1340use a library defined in some other project (one you can’t change) but 1341you still want static (or dynamic) linking to that library in all cases. 1342If that library is used by many targets, you <em>could</em> use target 1343references everywhere:</p> 1344</div> 1345<div class="listingblock"> 1346<div class="content"> 1347<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-nb">exe</span><span class="tok-w"> </span>e1<span class="tok-w"> </span>:<span class="tok-w"> </span>e1.cpp<span class="tok-w"> </span>/other_project//bar/<span class="tok-na"><link></span>static<span class="tok-w"> </span>;<span class="tok-w"></span> 1348<span class="tok-nb">exe</span><span class="tok-w"> </span>e10<span class="tok-w"> </span>:<span class="tok-w"> </span>e10.cpp<span class="tok-w"> </span>/other_project//bar/<span class="tok-na"><link></span>static<span class="tok-w"> </span>;<span class="tok-w"></span></code></pre> 1349</div> 1350</div> 1351<div class="paragraph"> 1352<p>but that’s far from being convenient. A better approach is to introduce 1353a level of indirection. Create a local <code>alias</code> target that refers to the 1354static (or dynamic) version of <code>foo</code>:</p> 1355</div> 1356<div class="listingblock"> 1357<div class="content"> 1358<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-nb">alias</span><span class="tok-w"> </span>foo<span class="tok-w"> </span>:<span class="tok-w"> </span>/other_project//bar/<span class="tok-na"><link></span>static<span class="tok-w"> </span>;<span class="tok-w"></span> 1359<span class="tok-nb">exe</span><span class="tok-w"> </span>e1<span class="tok-w"> </span>:<span class="tok-w"> </span>e1.cpp<span class="tok-w"> </span>foo<span class="tok-w"> </span>;<span class="tok-w"></span> 1360<span class="tok-nb">exe</span><span class="tok-w"> </span>e10<span class="tok-w"> </span>:<span class="tok-w"> </span>e10.cpp<span class="tok-w"> </span>foo<span class="tok-w"> </span>;<span class="tok-w"></span></code></pre> 1361</div> 1362</div> 1363<div class="paragraph"> 1364<p>The <a href="#bbv2.tasks.alias">alias</a> rule is specifically used to rename a 1365reference to a target and possibly change the properties.</p> 1366</div> 1367<div class="admonitionblock tip"> 1368<table> 1369<tr> 1370<td class="icon"> 1371<div class="title">☀</div> 1372</td> 1373<td class="content"> 1374<div class="paragraph"> 1375<p>When one library uses another, you put the second library in the source 1376list of the first. For example:</p> 1377</div> 1378<div class="listingblock"> 1379<div class="content"> 1380<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-nb">lib</span><span class="tok-w"> </span>utils<span class="tok-w"> </span>:<span class="tok-w"> </span>utils.cpp<span class="tok-w"> </span>/boost/filesystem//fs<span class="tok-w"> </span>;<span class="tok-w"></span> 1381<span class="tok-nb">lib</span><span class="tok-w"> </span>core<span class="tok-w"> </span>:<span class="tok-w"> </span>core.cpp<span class="tok-w"> </span>utils<span class="tok-w"> </span>;<span class="tok-w"></span> 1382<span class="tok-nb">exe</span><span class="tok-w"> </span>app<span class="tok-w"> </span>:<span class="tok-w"> </span>app.cpp<span class="tok-w"> </span>core<span class="tok-w"> </span>;<span class="tok-w"></span></code></pre> 1383</div> 1384</div> 1385<div class="paragraph"> 1386<p>This works no matter what kind of linking is used. When <code>core</code> is built as a 1387shared library, links <code>utils</code> directly into it. Static libraries can’t link 1388to other libraries, so when <code>core</code> is built as a static library, its 1389dependency on <code>utils</code> is passed along to <code>core’s dependents, causing `app</code> 1390to be linked with both <code>core</code> and <code>utils</code>.</p> 1391</div> 1392</td> 1393</tr> 1394</table> 1395</div> 1396<div class="admonitionblock note"> 1397<table> 1398<tr> 1399<td class="icon"> 1400<div class="title">ℹ</div> 1401</td> 1402<td class="content"> 1403(Note for non-UNIX system). Typically, shared libraries must be 1404installed to a directory in the dynamic linker’s search path. Otherwise, 1405applications that use shared libraries can’t be started. On Windows, the 1406dynamic linker’s search path is given by the <code>PATH</code> environment variable. 1407This restriction is lifted when you use B2 testing 1408facilities—the <code>PATH</code> variable will be automatically adjusted before 1409running the executable. 1410</td> 1411</tr> 1412</table> 1413</div> 1414</div> 1415<div class="sect2"> 1416<h3 id="bbv2.tutorial.conditions"><a class="anchor" href="#bbv2.tutorial.conditions"></a>2.6. Conditions and alternatives</h3> 1417<div class="paragraph"> 1418<p>Sometimes, particular relationships need to be maintained among a 1419target’s build properties. For example, you might want to set specific 1420<code>#define</code> when a library is built as shared, or when a target’s 1421<code>release</code> variant is built. This can be achieved using <em>conditional 1422requirements</em>.</p> 1423</div> 1424<div class="listingblock"> 1425<div class="content"> 1426<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-nb">lib</span><span class="tok-w"> </span>network<span class="tok-w"> </span>:<span class="tok-w"> </span>network.cpp<span class="tok-w"></span> 1427<span class="tok-w"> </span>:<span class="tok-w"> </span><span class="tok-na"><link></span>shared:<span class="tok-na"><define></span>NETWORK_LIB_SHARED<span class="tok-w"></span> 1428<span class="tok-w"> </span><span class="tok-na"><variant></span>release:<span class="tok-na"><define></span>EXTRA_FAST<span class="tok-w"></span> 1429<span class="tok-w"> </span>;<span class="tok-w"></span></code></pre> 1430</div> 1431</div> 1432<div class="paragraph"> 1433<p>In the example above, whenever <code>network</code> is built with <code><link>shared</code>, 1434<code><define>NETWORK_LIB_SHARED</code> will be in its properties, too. Also, whenever 1435its release variant is built, <code><define>EXTRA_FAST</code> will appear in its 1436properties.</p> 1437</div> 1438<div class="paragraph"> 1439<p>Sometimes the ways a target is built are so different that describing 1440them using conditional requirements would be hard. For example, imagine 1441that a library actually uses different source files depending on the 1442toolset used to build it. We can express this situation using target 1443<em>alternatives</em>:</p> 1444</div> 1445<div class="listingblock"> 1446<div class="content"> 1447<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-nb">lib</span><span class="tok-w"> </span>demangler<span class="tok-w"> </span>:<span class="tok-w"> </span>dummy_demangler.cpp<span class="tok-w"> </span>;<span class="tok-w"> </span># <b class="conum">(1)</b> 1448<span class="tok-nb">lib</span><span class="tok-w"> </span>demangler<span class="tok-w"> </span>:<span class="tok-w"> </span>demangler_gcc.cpp<span class="tok-w"> </span>:<span class="tok-w"> </span><span class="tok-na"><toolset></span>gcc<span class="tok-w"> </span>;<span class="tok-w"> </span># <b class="conum">(2)</b> 1449<span class="tok-nb">lib</span><span class="tok-w"> </span>demangler<span class="tok-w"> </span>:<span class="tok-w"> </span>demangler_msvc.cpp<span class="tok-w"> </span>:<span class="tok-w"> </span><span class="tok-na"><toolset></span>msvc<span class="tok-w"> </span>;<span class="tok-w"> </span># <b class="conum">(3)</b></code></pre> 1450</div> 1451</div> 1452<div class="paragraph"> 1453<p>When building <code>demangler</code>, B2 will compare requirements for 1454each alternative with build properties to find the best match. For 1455example, when building with <code><toolset>gcc</code> alternative <strong>(2)</strong>, will be 1456selected, and when building with <code><toolset>msvc</code> alternative <strong>(3)</strong> will be 1457selected. In all other cases, the most generic alternative <strong>(1)</strong> will be 1458built.</p> 1459</div> 1460</div> 1461<div class="sect2"> 1462<h3 id="bbv2.tutorial.prebuilt"><a class="anchor" href="#bbv2.tutorial.prebuilt"></a>2.7. Prebuilt targets</h3> 1463<div class="paragraph"> 1464<p>To link to libraries whose build instructions aren’t given in a Jamfile, 1465you need to create <code>lib</code> targets with an appropriate <code>file</code> property. 1466Target alternatives can be used to associate multiple library files with 1467a single conceptual target. For example:</p> 1468</div> 1469<div class="listingblock"> 1470<div class="content"> 1471<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-c1"># util/lib2/Jamfile</span> 1472<span class="tok-nb">lib</span><span class="tok-w"> </span>lib2<span class="tok-w"></span> 1473<span class="tok-w"> </span>:<span class="tok-w"></span> 1474<span class="tok-w"> </span>:<span class="tok-w"> </span><span class="tok-na"><file></span>lib2_release.a<span class="tok-w"> </span><span class="tok-na"><variant></span>release<span class="tok-w"></span> 1475<span class="tok-w"> </span>;<span class="tok-w"></span> 1476 1477<span class="tok-nb">lib</span><span class="tok-w"> </span>lib2<span class="tok-w"></span> 1478<span class="tok-w"> </span>:<span class="tok-w"></span> 1479<span class="tok-w"> </span>:<span class="tok-w"> </span><span class="tok-na"><file></span>lib2_debug.a<span class="tok-w"> </span><span class="tok-na"><variant></span>debug<span class="tok-w"></span> 1480<span class="tok-w"> </span>;<span class="tok-w"></span></code></pre> 1481</div> 1482</div> 1483<div class="paragraph"> 1484<p>This example defines two alternatives for <code>lib2</code>, and for each one names 1485a prebuilt file. Naturally, there are no sources. Instead, the <code><file></code> 1486feature is used to specify the file name.</p> 1487</div> 1488<div class="paragraph"> 1489<p>Once a prebuilt target has been declared, it can be used just like any 1490other target:</p> 1491</div> 1492<div class="listingblock"> 1493<div class="content"> 1494<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-nb">exe</span><span class="tok-w"> </span>app<span class="tok-w"> </span>:<span class="tok-w"> </span>app.cpp<span class="tok-w"> </span>../util/lib2//lib2<span class="tok-w"> </span>;<span class="tok-w"></span></code></pre> 1495</div> 1496</div> 1497<div class="paragraph"> 1498<p>As with any target, the alternative selected depends on the properties 1499propagated from <code>lib2’s dependents. If we build the release and debug 1500versions of `app</code> it will be linked with <code>lib2_release.a</code> and 1501<code>lib2_debug.a</code>, respectively.</p> 1502</div> 1503<div class="paragraph"> 1504<p>System libraries — those that are automatically found by the toolset by 1505searching through some set of predetermined paths — should be declared 1506almost like regular ones:</p> 1507</div> 1508<div class="listingblock"> 1509<div class="content"> 1510<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-nb">lib</span><span class="tok-w"> </span>pythonlib<span class="tok-w"> </span>:<span class="tok-w"> </span>:<span class="tok-w"> </span><span class="tok-na"><name></span>python22<span class="tok-w"> </span>;<span class="tok-w"></span></code></pre> 1511</div> 1512</div> 1513<div class="paragraph"> 1514<p>We again don’t specify any sources, but give a <code>name</code> that should be 1515passed to the compiler. If the gcc toolset were used to link an 1516executable target to <code>pythonlib</code>, <code>-lpython22</code> would appear in the 1517command line (other compilers may use different options).</p> 1518</div> 1519<div class="paragraph"> 1520<p>We can also specify where the toolset should look for the library:</p> 1521</div> 1522<div class="listingblock"> 1523<div class="content"> 1524<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-nb">lib</span><span class="tok-w"> </span>pythonlib<span class="tok-w"> </span>:<span class="tok-w"> </span>:<span class="tok-w"> </span><span class="tok-na"><name></span>python22<span class="tok-w"> </span><span class="tok-na"><search></span>/opt/lib<span class="tok-w"> </span>;<span class="tok-w"></span></code></pre> 1525</div> 1526</div> 1527<div class="paragraph"> 1528<p>And, of course, target alternatives can be used in the usual way:</p> 1529</div> 1530<div class="listingblock"> 1531<div class="content"> 1532<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-nb">lib</span><span class="tok-w"> </span>pythonlib<span class="tok-w"> </span>:<span class="tok-w"> </span>:<span class="tok-w"> </span><span class="tok-na"><name></span>python22<span class="tok-w"> </span><span class="tok-na"><variant></span>release<span class="tok-w"> </span>;<span class="tok-w"></span> 1533<span class="tok-nb">lib</span><span class="tok-w"> </span>pythonlib<span class="tok-w"> </span>:<span class="tok-w"> </span>:<span class="tok-w"> </span><span class="tok-na"><name></span>python22_d<span class="tok-w"> </span><span class="tok-na"><variant></span>debug<span class="tok-w"> </span>;<span class="tok-w"></span></code></pre> 1534</div> 1535</div> 1536<div class="paragraph"> 1537<p>A more advanced use of prebuilt targets is described in 1538<a href="#bbv2.recipes.site-config">the section called “Targets in 1539site-config.jam”</a>.</p> 1540</div> 1541</div> 1542</div> 1543</div> 1544<div class="sect1"> 1545<h2 id="bbv2.overview"><a class="anchor" href="#bbv2.overview"></a>3. Overview</h2> 1546<div class="sectionbody"> 1547<div class="paragraph"> 1548<p>This section will provide the information necessary to create your own 1549projects using B2. The information provided here is relatively 1550high-level, and the <a href="#bbv2.reference">Reference</a> as well as the on-line 1551help system must be used to obtain low-level documentation (see 1552<a href="#bbv2.overview.invocation.options.help"><code>--help</code></a>).</p> 1553</div> 1554<div class="paragraph"> 1555<p>B2 has two parts — a build engine with its own interpreted 1556language, and B2 itself, implemented in that language. The 1557chain of events when you type <code>b2</code> on the command line is as follows:</p> 1558</div> 1559<div class="olist arabic"> 1560<ol class="arabic"> 1561<li> 1562<p>The B2 executable tries to find B2 modules and 1563loads the top-level module. The exact process is described in 1564<a href="#bbv2.reference.init">the section called “Initialization”</a></p> 1565</li> 1566<li> 1567<p>The top-level module loads user-defined configuration files, 1568<code>user-config.jam</code> and <code>site-config.jam</code>, which define available 1569toolsets.</p> 1570</li> 1571<li> 1572<p>The Jamfile in the current directory is read. That in turn might 1573cause reading of further Jamfiles. As a result, a tree of projects is 1574created, with targets inside projects.</p> 1575</li> 1576<li> 1577<p>Finally, using the build request specified on the command line, 1578B2 decides which targets should be built and how. That 1579information is passed back to Boost.Jam, which takes care of actually 1580running the scheduled build action commands.</p> 1581</li> 1582</ol> 1583</div> 1584<div class="paragraph"> 1585<p>So, to be able to successfully use B2, you need to know only 1586four things:</p> 1587</div> 1588<div class="ulist"> 1589<ul> 1590<li> 1591<p><a href="#bbv2.overview.configuration">How to configure B2</a></p> 1592</li> 1593<li> 1594<p><a href="#bbv2.overview.targets">How to declare targets in Jamfiles</a></p> 1595</li> 1596<li> 1597<p><a href="#bbv2.overview.build_process">How the build process works</a></p> 1598</li> 1599<li> 1600<p>Some Basics about the Boost.Jam language. See 1601<a href="#bbv2.overview.jam_language">the section called “Boost.Jam Language”</a>.</p> 1602</li> 1603</ul> 1604</div> 1605<div class="sect2"> 1606<h3 id="bbv2.overview.concepts"><a class="anchor" href="#bbv2.overview.concepts"></a>3.1. Concepts</h3> 1607<div class="paragraph"> 1608<p>B2 has a few unique concepts that are introduced in this 1609section. The best way to explain the concepts is by comparison with more 1610classical build tools.</p> 1611</div> 1612<div class="paragraph"> 1613<p>When using any flavor of make, you directly specify <em>targets</em> and 1614commands that are used to create them from other target. The below 1615example creates <code>a.o</code> from <code>a.c</code> using a hardcoded compiler invocation 1616command.</p> 1617</div> 1618<div class="listingblock"> 1619<div class="content"> 1620<pre class="pygments highlight"><code data-lang="make"><span></span><span class="tok-nf">a.o</span><span class="tok-o">:</span> <span class="tok-n">a</span>.<span class="tok-n">c</span> 1621 g++ -o a.o -g a.c</code></pre> 1622</div> 1623</div> 1624<div class="paragraph"> 1625<p>This is a rather low-level description mechanism and it’s hard to adjust 1626commands, options, and sets of created targets depending on the compiler 1627and operating system used.</p> 1628</div> 1629<div class="paragraph"> 1630<p>To improve portability, most modern build system provide a set of 1631higher-level functions that can be used in build description files. 1632Consider this example:</p> 1633</div> 1634<div class="listingblock"> 1635<div class="content"> 1636<pre class="pygments highlight"><code data-lang="cmake"><span></span><span class="tok-nb">add_program</span> <span class="tok-p">(</span><span class="tok-s2">"a"</span><span class="tok-s">,</span> <span class="tok-s2">"a.c"</span><span class="tok-p">)</span></code></pre> 1637</div> 1638</div> 1639<div class="paragraph"> 1640<p>This is a function call that creates the targets necessary to create an 1641executable file from the source file <code>a.c</code>. Depending on configured 1642properties, different command lines may be used. However, <code>add_program</code> 1643is higher-level, but rather thin level. All targets are created 1644immediately when the build description is parsed, which makes it 1645impossible to perform multi-variant builds. Often, change in any build 1646property requires a complete reconfiguration of the build tree.</p> 1647</div> 1648<div class="paragraph"> 1649<p>In order to support true multi-variant builds, B2 introduces the 1650concept of a metatarget definition main target metatarget 1651<em>metatarget</em> — an object that is created when the build description is 1652parsed and can be called later with specific build properties to 1653generate actual targets.</p> 1654</div> 1655<div class="paragraph"> 1656<p>Consider an example:</p> 1657</div> 1658<div class="listingblock"> 1659<div class="content"> 1660<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-nb">exe</span><span class="tok-w"> </span>a<span class="tok-w"> </span>:<span class="tok-w"> </span>a.cpp<span class="tok-w"> </span>;<span class="tok-w"></span></code></pre> 1661</div> 1662</div> 1663<div class="paragraph"> 1664<p>When this declaration is parsed, B2 creates a metatarget, but 1665does not yet decide what files must be created, or what commands must be 1666used. After all build files are parsed, B2 considers the 1667properties requested on the command line. Supposed you have invoked 1668B2 with:</p> 1669</div> 1670<div class="listingblock"> 1671<div class="content"> 1672<pre class="pygments highlight"><code data-lang="shell"><span></span>b2 <span class="tok-nv">toolset</span><span class="tok-o">=</span>gcc <span class="tok-nv">toolset</span><span class="tok-o">=</span>msvc</code></pre> 1673</div> 1674</div> 1675<div class="paragraph"> 1676<p>In that case, the metatarget will be called twice, once with 1677<code>toolset=gcc</code> and once with <code>toolset=msvc</code>. Both invocations will 1678produce concrete targets, that will have different extensions and use 1679different command lines.</p> 1680</div> 1681<div class="paragraph"> 1682<p>Another key concept is <em>build property</em>. A build 1683property is a variable that affects the build process. It can be 1684specified on the command line, and is passed when calling a metatarget. 1685While all build tools have a similar mechanism, B2 differs by 1686requiring that all build properties are declared in advance, and 1687providing a large set of properties with portable semantics.</p> 1688</div> 1689<div class="paragraph"> 1690<p>The final concept is <em>property propagation</em>. 1691B2 does not require that every metatarget is called with the 1692same properties. Instead, the "top-level" metatargets are called with 1693the properties specified on the command line. Each metatarget can elect 1694to augment or override some properties (in particular, using the 1695requirements mechanism, see 1696<a href="#bbv2.overview.targets.requirements">the section called “Requirements”</a>). 1697Then, the dependency metatargets are called with the modified properties and 1698produce concrete targets that are then used in the build process. Of 1699course, dependency metatargets maybe in turn modify build properties and 1700have dependencies of their own.</p> 1701</div> 1702<div class="paragraph"> 1703<p>For a more in-depth treatment of the requirements and concepts, you may 1704refer to <a href="http://syrcose.ispras.ru/2009/files/04_paper.pdf">SYRCoSE 2009 1705B2 article</a>.</p> 1706</div> 1707</div> 1708<div class="sect2"> 1709<h3 id="bbv2.overview.jam_language"><a class="anchor" href="#bbv2.overview.jam_language"></a>3.2. Boost.Jam Language</h3> 1710<div class="paragraph"> 1711<p>This section will describe the basics of the Boost.Jam language—just 1712enough for writing Jamfiles. For more information, please see the 1713<a href="#bbv2.jam">Boost.Jam</a> documentation.</p> 1714</div> 1715<div class="paragraph"> 1716<p><a href="#bbv2.jam">Boost.Jam</a> has an interpreted, procedural language. On 1717the lowest level, a <a href="#bbv2.jam">Boost.Jam</a> program consists of 1718variables and <em>rules</em> (the Jam term for functions). They are grouped 1719into modules—there is one global module and a number of named modules. 1720Besides that, a <a href="#bbv2.jam">Boost.Jam</a> program contains classes and 1721class instances.</p> 1722</div> 1723<div class="paragraph"> 1724<p>Syntactically, a <a href="#bbv2.jam">Boost.Jam</a> program consists of two kinds 1725of elements—keywords (which have a special meaning to 1726<a href="#bbv2.jam">Boost.Jam</a>) and literals. Consider this code:</p> 1727</div> 1728<div class="listingblock"> 1729<div class="content"> 1730<pre class="pygments highlight"><code data-lang="jam"><span></span>a<span class="tok-w"> </span>=<span class="tok-w"> </span>b<span class="tok-w"> </span>;<span class="tok-w"></span></code></pre> 1731</div> 1732</div> 1733<div class="paragraph"> 1734<p>which assigns the value <code>b</code> to the variable <code>a</code>. Here, <code>=</code> and <code>;</code> are 1735keywords, while <code>a</code> and <code>b</code> are literals.</p> 1736</div> 1737<div class="admonitionblock warning"> 1738<table> 1739<tr> 1740<td class="icon"> 1741<div class="title">⚠</div> 1742</td> 1743<td class="content"> 1744All syntax elements, even keywords, must be separated by spaces. For 1745example, omitting the space character before <code>;</code> will lead to a syntax 1746error. 1747</td> 1748</tr> 1749</table> 1750</div> 1751<div class="paragraph"> 1752<p>If you want to use a literal value that is the same as some keyword, the 1753value can be quoted:</p> 1754</div> 1755<div class="listingblock"> 1756<div class="content"> 1757<pre class="pygments highlight"><code data-lang="jam"><span></span>a<span class="tok-w"> </span>=<span class="tok-w"> </span>"="<span class="tok-w"> </span>;<span class="tok-w"></span></code></pre> 1758</div> 1759</div> 1760<div class="paragraph"> 1761<p>All variables in <a href="#bbv2.jam">Boost.Jam</a> have the same type—list of 1762strings. To define a variable one assigns a value to it, like in the 1763previous example. An undefined variable is the same as a variable with 1764an empty value. Variables can be accessed using the <code>$(variable)</code> 1765syntax. For example:</p> 1766</div> 1767<div class="listingblock"> 1768<div class="content"> 1769<pre class="pygments highlight"><code data-lang="jam"><span></span>a<span class="tok-w"> </span>=<span class="tok-w"> </span><span class="tok-si">$(b)</span><span class="tok-w"> </span><span class="tok-si">$(c)</span><span class="tok-w"> </span>;<span class="tok-w"></span></code></pre> 1770</div> 1771</div> 1772<div class="paragraph"> 1773<p>Rules are defined by specifying the rule name, the parameter names, and 1774the allowed value list size for each parameter.</p> 1775</div> 1776<div class="listingblock"> 1777<div class="content"> 1778<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-k">rule</span><span class="tok-w"> </span><span class="tok-nf">example</span><span class="tok-w"></span> 1779<span class="tok-w"> </span><span class="tok-p">(</span><span class="tok-w"></span> 1780<span class="tok-w"> </span><span class="tok-nv">parameter1</span><span class="tok-w"> </span><span class="tok-p">:</span><span class="tok-w"></span> 1781<span class="tok-w"> </span><span class="tok-nv">parameter2</span><span class="tok-w"> </span><span class="tok-p">?</span><span class="tok-w"> </span><span class="tok-p">:</span><span class="tok-w"></span> 1782<span class="tok-w"> </span><span class="tok-nv">parameter3</span><span class="tok-w"> </span><span class="tok-p">+</span><span class="tok-w"> </span><span class="tok-p">:</span><span class="tok-w"></span> 1783<span class="tok-w"> </span><span class="tok-nv">parameter4</span><span class="tok-w"> </span><span class="tok-p">*</span><span class="tok-w"></span> 1784<span class="tok-w"> </span><span class="tok-p">)</span><span class="tok-w"></span> 1785<span class="tok-w"> </span>{<span class="tok-w"></span> 1786<span class="tok-w"> </span><span class="tok-c1"># rule body</span> 1787<span class="tok-w"> </span>}<span class="tok-w"></span></code></pre> 1788</div> 1789</div> 1790<div class="paragraph"> 1791<p>When this rule is called, the list passed as the first argument must 1792have exactly one value. The list passed as the second argument can 1793either have one value of be empty. The two remaining arguments can be 1794arbitrarily long, but the third argument may not be empty.</p> 1795</div> 1796<div class="paragraph"> 1797<p>The overview of <a href="#bbv2.jam">Boost.Jam</a> language statements is given 1798below:</p> 1799</div> 1800<div class="listingblock"> 1801<div class="content"> 1802<pre class="pygments highlight"><code data-lang="jam"><span></span>helper<span class="tok-w"> </span>1<span class="tok-w"> </span>:<span class="tok-w"> </span>2<span class="tok-w"> </span>:<span class="tok-w"> </span>3<span class="tok-w"> </span>;<span class="tok-w"></span> 1803x<span class="tok-w"> </span>=<span class="tok-w"> </span>[<span class="tok-w"> </span>helper<span class="tok-w"> </span>1<span class="tok-w"> </span>:<span class="tok-w"> </span>2<span class="tok-w"> </span>:<span class="tok-w"> </span>3<span class="tok-w"> </span>]<span class="tok-w"> </span>;<span class="tok-w"></span></code></pre> 1804</div> 1805</div> 1806<div class="paragraph"> 1807<p>This code calls the named rule with the specified arguments. When the 1808result of the call must be used inside some expression, you need to add 1809brackets around the call, like shown on the second line.</p> 1810</div> 1811<div class="listingblock"> 1812<div class="content"> 1813<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-k">if</span><span class="tok-w"> </span>cond<span class="tok-w"> </span>{<span class="tok-w"> </span>statements<span class="tok-w"> </span>}<span class="tok-w"> </span>[<span class="tok-w"> </span><span class="tok-k">else</span><span class="tok-w"> </span>{<span class="tok-w"> </span>statements<span class="tok-w"> </span>}<span class="tok-w"> </span>]<span class="tok-w"></span></code></pre> 1814</div> 1815</div> 1816<div class="paragraph"> 1817<p>This is a regular if-statement. The condition is composed of:</p> 1818</div> 1819<div class="ulist"> 1820<ul> 1821<li> 1822<p>Literals (true if at least one string is not empty)</p> 1823</li> 1824<li> 1825<p>Comparisons: <code>a operator b</code> where <em>operator</em> is one of <code>=</code>, <code>!=</code>, <code><</code>, 1826<code>></code>, <code>⇐</code> or <code>>=</code>. The comparison is done pairwise between each string 1827in the left and the right arguments.</p> 1828</li> 1829<li> 1830<p>Logical operations: <code>! a</code>, <code>a && b</code>, <code>a || b</code></p> 1831</li> 1832<li> 1833<p>Grouping: <code>( cond )</code></p> 1834</li> 1835</ul> 1836</div> 1837<div class="listingblock"> 1838<div class="content"> 1839<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-k">for</span><span class="tok-w"> </span>var<span class="tok-w"> </span><span class="tok-k">in</span><span class="tok-w"> </span>list<span class="tok-w"> </span>{<span class="tok-w"> </span>statements<span class="tok-w"> </span>}<span class="tok-w"></span></code></pre> 1840</div> 1841</div> 1842<div class="paragraph"> 1843<p>Executes statements for each element in list, setting the variable <code>var</code> 1844to the element value.</p> 1845</div> 1846<div class="listingblock"> 1847<div class="content"> 1848<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-k">while</span><span class="tok-w"> </span>cond<span class="tok-w"> </span>{<span class="tok-w"> </span>statements<span class="tok-w"> </span>}<span class="tok-w"></span></code></pre> 1849</div> 1850</div> 1851<div class="paragraph"> 1852<p>Repeatedly execute statements while cond remains true upon entry.</p> 1853</div> 1854<div class="listingblock"> 1855<div class="content"> 1856<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-k">return</span><span class="tok-w"> </span>values<span class="tok-w"> </span>;<span class="tok-w"></span></code></pre> 1857</div> 1858</div> 1859<div class="paragraph"> 1860<p>This statement should be used only inside a rule and returns <code>values</code> to 1861the caller of the rule.</p> 1862</div> 1863<div class="listingblock"> 1864<div class="content"> 1865<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-nb">import</span><span class="tok-w"> </span><span class="tok-k">module</span><span class="tok-w"> </span>;<span class="tok-w"></span> 1866<span class="tok-nb">import</span><span class="tok-w"> </span><span class="tok-k">module</span><span class="tok-w"> </span>:<span class="tok-w"> </span><span class="tok-k">rule</span><span class="tok-w"> </span><span class="tok-nf">;</span><span class="tok-w"></span></code></pre> 1867</div> 1868</div> 1869<div class="paragraph"> 1870<p>The first form imports the specified module. All rules from that module 1871are made available using the qualified name: <code>module.rule</code>. The second form 1872imports the specified rules only, and they can be called using unqualified 1873names.</p> 1874</div> 1875<div id="bbv2.overview.jam_language.actions" class="paragraph"> 1876<p>Sometimes, you need to specify the actual command lines to be used when 1877creating targets. In the jam language, you use named actions to do this. 1878For example:</p> 1879</div> 1880<div class="listingblock"> 1881<div class="content"> 1882<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-k">actions</span><span class="tok-w"> </span><span class="tok-nf">create-file-from-another</span><span class="tok-w"></span> 1883{<span class="tok-sh"></span> 1884<span class="tok-sh"> create-file-from-another </span><span class="tok-si">$(<)</span><span class="tok-sh"> </span><span class="tok-si">$(>)</span><span class="tok-sh"></span> 1885<span class="tok-p">}</span><span class="tok-w"></span></code></pre> 1886</div> 1887</div> 1888<div class="paragraph"> 1889<p>This specifies a named action called <code>create-file-from-another</code>. The text 1890inside braces is the command to invoke. The <code>$(<)</code> variable will be expanded 1891to a list of generated files, and the <code>$(>)</code> variable will be expanded to a 1892list of source files.</p> 1893</div> 1894<div class="paragraph"> 1895<p>To adjust the command line flexibly, you can define a rule with the same 1896name as the action and taking three parameters — targets, sources and 1897properties. For example:</p> 1898</div> 1899<div class="listingblock"> 1900<div class="content"> 1901<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-k">rule</span><span class="tok-w"> </span><span class="tok-nf">create-file-from-another</span><span class="tok-w"> </span><span class="tok-p">(</span><span class="tok-w"> </span><span class="tok-nv">targets</span><span class="tok-w"> </span><span class="tok-p">*</span><span class="tok-w"> </span><span class="tok-p">:</span><span class="tok-w"> </span><span class="tok-nv">sources</span><span class="tok-w"> </span><span class="tok-p">*</span><span class="tok-w"> </span><span class="tok-p">:</span><span class="tok-w"> </span><span class="tok-nv">properties</span><span class="tok-w"> </span><span class="tok-p">*</span><span class="tok-w"> </span><span class="tok-p">)</span><span class="tok-w"></span> 1902{<span class="tok-w"></span> 1903<span class="tok-w"> </span><span class="tok-k">if</span><span class="tok-w"> </span><span class="tok-na"><variant></span>debug<span class="tok-w"> </span><span class="tok-k">in</span><span class="tok-w"> </span><span class="tok-si">$(properties)</span><span class="tok-w"></span> 1904<span class="tok-w"> </span>{<span class="tok-w"></span> 1905<span class="tok-w"> </span>OPTIONS<span class="tok-w"> </span><span class="tok-k">on</span><span class="tok-w"> </span><span class="tok-si">$(targets)</span><span class="tok-w"> </span>=<span class="tok-w"> </span>--debug<span class="tok-w"> </span>;<span class="tok-w"></span> 1906<span class="tok-w"> </span>}<span class="tok-w"></span> 1907}<span class="tok-w"></span> 1908<span class="tok-k">actions</span><span class="tok-w"> </span><span class="tok-nf">create-file-from-another</span><span class="tok-w"></span> 1909{<span class="tok-sh"></span> 1910<span class="tok-sh"> create-file-from-another </span><span class="tok-si">$(OPTIONS)</span><span class="tok-sh"> </span><span class="tok-si">$(<)</span><span class="tok-sh"> </span><span class="tok-si">$(>)</span><span class="tok-sh"></span> 1911<span class="tok-p">}</span><span class="tok-w"></span></code></pre> 1912</div> 1913</div> 1914<div class="paragraph"> 1915<p>In this example, the rule checks if a certain build property is 1916specified. If so, it sets the variable <code>OPTIONS</code> that is then used 1917inside the action. Note that the variables set "on a target" will be 1918visible only inside actions building that target, not globally. Were 1919they set globally, using variable named <code>OPTIONS</code> in two unrelated 1920actions would be impossible.</p> 1921</div> 1922<div class="paragraph"> 1923<p>More details can be found in the Jam reference, 1924<a href="#jam.language.rules">the section called “Rules”</a>.</p> 1925</div> 1926</div> 1927<div class="sect2"> 1928<h3 id="bbv2.overview.configuration"><a class="anchor" href="#bbv2.overview.configuration"></a>3.3. Configuration</h3> 1929<div class="paragraph"> 1930<p>On startup, B2 searches and reads three configuration files: 1931<code>site-config.jam</code>, <code>user-config.jam</code>, and <code>project-config.jam</code>. The 1932first one is usually installed and maintained by a system administrator, 1933and the second is for the user to modify. You can edit the one in the 1934top-level directory of your B2 installation or create a copy in 1935your home directory and edit the copy. The third is used for project 1936specific configuration. The following table explains where the files are 1937searched.</p> 1938</div> 1939<table class="tableblock frame-all grid-all stretch"> 1940<caption class="title">Table 1. Search paths for configuration files</caption> 1941<colgroup> 1942<col style="width: 25%;"> 1943<col style="width: 25%;"> 1944<col style="width: 25%;"> 1945<col style="width: 25%;"> 1946</colgroup> 1947<thead> 1948<tr> 1949<th class="tableblock halign-left valign-top"></th> 1950<th class="tableblock halign-center valign-top">site-config.jam</th> 1951<th class="tableblock halign-center valign-top">user-config.jam</th> 1952<th class="tableblock halign-center valign-top">project-config.jam</th> 1953</tr> 1954</thead> 1955<tbody> 1956<tr> 1957<th class="tableblock halign-left valign-middle"><p class="tableblock">Linux</p></th> 1958<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph"> 1959<p><code>/etc</code></p> 1960</div> 1961<div class="paragraph"> 1962<p><code>$HOME</code></p> 1963</div> 1964<div class="paragraph"> 1965<p><code>$BOOST_BUILD_PATH</code></p> 1966</div></div></td> 1967<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph"> 1968<p><code>$HOME</code></p> 1969</div> 1970<div class="paragraph"> 1971<p><code>$BOOST_BUILD_PATH</code></p> 1972</div></div></td> 1973<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph"> 1974<p><code>.</code></p> 1975</div> 1976<div class="paragraph"> 1977<p><code>..</code></p> 1978</div> 1979<div class="paragraph"> 1980<p><code>../..</code></p> 1981</div> 1982<div class="paragraph"> 1983<p>…​</p> 1984</div></div></td> 1985</tr> 1986<tr> 1987<th class="tableblock halign-left valign-middle"><p class="tableblock">Windows</p></th> 1988<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph"> 1989<p><code>%SystemRoot%</code></p> 1990</div> 1991<div class="paragraph"> 1992<p><code>%HOMEDRIVE%%HOMEPATH%</code></p> 1993</div> 1994<div class="paragraph"> 1995<p><code>%HOME%</code></p> 1996</div> 1997<div class="paragraph"> 1998<p><code>%BOOST_BUILD_PATH%</code></p> 1999</div></div></td> 2000<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph"> 2001<p><code>%HOMEDRIVE%%HOMEPATH%</code></p> 2002</div> 2003<div class="paragraph"> 2004<p><code>%HOME%</code></p> 2005</div> 2006<div class="paragraph"> 2007<p><code>%BOOST_BUILD_PATH%</code></p> 2008</div></div></td> 2009<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph"> 2010<p><code>.</code></p> 2011</div> 2012<div class="paragraph"> 2013<p><code>..</code></p> 2014</div> 2015<div class="paragraph"> 2016<p><code>../..</code></p> 2017</div> 2018<div class="paragraph"> 2019<p>…​</p> 2020</div></div></td> 2021</tr> 2022</tbody> 2023</table> 2024<div class="paragraph"> 2025<p>Any of these files may also be overridden 2026<a href="#bbv2.reference.init.options.config">on the command line</a>.</p> 2027</div> 2028<div class="admonitionblock tip"> 2029<table> 2030<tr> 2031<td class="icon"> 2032<div class="title">☀</div> 2033</td> 2034<td class="content"> 2035You can use the <code>--debug-configuration</code> option to find which 2036configuration files are actually loaded. 2037</td> 2038</tr> 2039</table> 2040</div> 2041<div class="paragraph"> 2042<p>Usually, <code>user-config.jam</code> just defines the available compilers and 2043other tools (see <a href="#bbv2.recipes.site-config">the section called “Targets 2044in site-config.jam”</a> for more advanced usage). A tool is configured using 2045the following syntax:</p> 2046</div> 2047<div class="listingblock"> 2048<div class="content"> 2049<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-nb">using</span><span class="tok-w"> </span>tool-name<span class="tok-w"> </span>:<span class="tok-w"> </span>...<span class="tok-w"> </span>;<span class="tok-w"></span></code></pre> 2050</div> 2051</div> 2052<div class="paragraph"> 2053<p>The <code>using</code> rule is given the name of tool, and will make that tool 2054available to B2. For example,</p> 2055</div> 2056<div class="listingblock"> 2057<div class="content"> 2058<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-nb">using</span><span class="tok-w"> </span>gcc<span class="tok-w"> </span>;<span class="tok-w"></span></code></pre> 2059</div> 2060</div> 2061<div class="paragraph"> 2062<p>will make the <a href="http://gcc.gnu.org">GCC</a> compiler available.</p> 2063</div> 2064<div class="admonitionblock tip"> 2065<table> 2066<tr> 2067<td class="icon"> 2068<div class="title">☀</div> 2069</td> 2070<td class="content"> 2071You can put <code>using <tool> ;</code> with no other argument in a Jamfile 2072that needs the <code>tool</code>, provided that the <code>tool</code> supports this usage. 2073In all other cases, the <code>using</code> rule should be in a configuration file. 2074The general principle is that descriptions in Jamfile should be 2075maintained as portable while configuration files are system specific. 2076</td> 2077</tr> 2078</table> 2079</div> 2080<div class="paragraph"> 2081<p>All the supported tools are documented in 2082<a href="#bbv2.reference.tools">the section called “Builtin tools”</a>, including the 2083specific options they take. Some general notes that apply to most C++ 2084compilers are below.</p> 2085</div> 2086<div class="paragraph"> 2087<p>For all the C++ compiler toolsets that B2 supports 2088out-of-the-box, the list of parameters to <code>using</code> is the same: 2089<code>toolset-name</code>, <code>version</code>, <code>invocation-command</code>, and <code>options</code>.</p> 2090</div> 2091<div class="paragraph"> 2092<p>If you have a single compiler, and the compiler executable</p> 2093</div> 2094<div class="ulist"> 2095<ul> 2096<li> 2097<p>has its “usual name” and is in the <code>PATH</code>, or</p> 2098</li> 2099<li> 2100<p>was installed in a standard “installation directory”, or</p> 2101</li> 2102<li> 2103<p>can be found using a global system like the Windows registry.</p> 2104</li> 2105</ul> 2106</div> 2107<div class="paragraph"> 2108<p>it can be configured by simply:</p> 2109</div> 2110<div class="listingblock"> 2111<div class="content"> 2112<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-nb">using</span><span class="tok-w"> </span>tool-name<span class="tok-w"> </span>;<span class="tok-w"></span></code></pre> 2113</div> 2114</div> 2115<div class="paragraph"> 2116<p>If the compiler is installed in a custom directory, you should provide 2117the command that invokes the compiler, for example:</p> 2118</div> 2119<div class="listingblock"> 2120<div class="content"> 2121<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-nb">using</span><span class="tok-w"> </span>gcc<span class="tok-w"> </span>:<span class="tok-w"> </span>:<span class="tok-w"> </span>g++-3.2<span class="tok-w"> </span>;<span class="tok-w"></span> 2122<span class="tok-nb">using</span><span class="tok-w"> </span>msvc<span class="tok-w"> </span>:<span class="tok-w"> </span>:<span class="tok-w"> </span>"Z:/Programs/Microsoft<span class="tok-w"> </span>Visual<span class="tok-w"> </span>Studio/vc98/bin/cl"<span class="tok-w"> </span>;<span class="tok-w"></span></code></pre> 2123</div> 2124</div> 2125<div class="paragraph"> 2126<p>Some B2 toolsets will use that path to take additional actions 2127required before invoking the compiler, such as calling vendor-supplied 2128scripts to set up its required environment variables. When the compiler 2129executables for C and C++ are different, the path to the C++ compiler 2130executable must be specified. The command can be any command allowed by 2131the operating system. For example:</p> 2132</div> 2133<div class="listingblock"> 2134<div class="content"> 2135<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-nb">using</span><span class="tok-w"> </span>msvc<span class="tok-w"> </span>:<span class="tok-w"> </span>:<span class="tok-w"> </span><span class="tok-nb">echo</span><span class="tok-w"> </span>Compiling<span class="tok-w"> </span>&&<span class="tok-w"> </span>foo/bar/baz/cl<span class="tok-w"> </span>;<span class="tok-w"></span></code></pre> 2136</div> 2137</div> 2138<div class="paragraph"> 2139<p>will work.</p> 2140</div> 2141<div class="paragraph"> 2142<p>To configure several versions of a toolset, simply invoke the <code>using</code> 2143rule multiple times:</p> 2144</div> 2145<div class="listingblock"> 2146<div class="content"> 2147<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-nb">using</span><span class="tok-w"> </span>gcc<span class="tok-w"> </span>:<span class="tok-w"> </span>3.3<span class="tok-w"> </span>;<span class="tok-w"></span> 2148<span class="tok-nb">using</span><span class="tok-w"> </span>gcc<span class="tok-w"> </span>:<span class="tok-w"> </span>3.4<span class="tok-w"> </span>:<span class="tok-w"> </span>g++-3.4<span class="tok-w"> </span>;<span class="tok-w"></span> 2149<span class="tok-nb">using</span><span class="tok-w"> </span>gcc<span class="tok-w"> </span>:<span class="tok-w"> </span>3.2<span class="tok-w"> </span>:<span class="tok-w"> </span>g++-3.2<span class="tok-w"> </span>;<span class="tok-w"></span> 2150<span class="tok-nb">using</span><span class="tok-w"> </span>gcc<span class="tok-w"> </span>:<span class="tok-w"> </span>5<span class="tok-w"> </span>;<span class="tok-w"></span> 2151<span class="tok-nb">using</span><span class="tok-w"> </span>clang<span class="tok-w"> </span>:<span class="tok-w"> </span>3.9<span class="tok-w"> </span>;<span class="tok-w"></span> 2152<span class="tok-nb">using</span><span class="tok-w"> </span>msvc<span class="tok-w"> </span>:<span class="tok-w"> </span>14.0<span class="tok-w"> </span>;<span class="tok-w"></span></code></pre> 2153</div> 2154</div> 2155<div class="paragraph"> 2156<p>Note that in the first call to <code>using</code>, the compiler found in the <code>PATH</code> 2157will be used, and there is no need to explicitly specify the command.</p> 2158</div> 2159<div class="paragraph"> 2160<p>Many of toolsets have an <code>options</code> parameter to fine-tune the 2161configuration. All of B2’s standard compiler toolsets accept 2162four options <code>cflags</code>, <code>cxxflags</code>, <code>compileflags</code> and <code>linkflags</code> as 2163<code>options</code> specifying flags that will be always passed to the 2164corresponding tools. There must not be a space between the tag for the 2165option name and the value. Values of the <code>cflags</code> feature are passed 2166directly to the C compiler, values of the <code>cxxflags</code> feature are passed 2167directly to the C++ compiler, and values of the <code>compileflags</code> feature 2168are passed to both. For example, to configure a <code>gcc</code> toolset so that it 2169always generates 64-bit code you could write:</p> 2170</div> 2171<div class="listingblock"> 2172<div class="content"> 2173<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-nb">using</span><span class="tok-w"> </span>gcc<span class="tok-w"> </span>:<span class="tok-w"> </span>3.4<span class="tok-w"> </span>:<span class="tok-w"> </span>:<span class="tok-w"> </span><span class="tok-na"><compileflags></span>-m64<span class="tok-w"> </span><span class="tok-na"><linkflags></span>-m64<span class="tok-w"> </span>;<span class="tok-w"></span></code></pre> 2174</div> 2175</div> 2176<div class="paragraph"> 2177<p>If multiple of the same type of options are needed, they can be 2178concatenated with quotes or have multiple instances of the option tag.</p> 2179</div> 2180<div class="listingblock"> 2181<div class="content"> 2182<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-nb">using</span><span class="tok-w"> </span>gcc<span class="tok-w"> </span>:<span class="tok-w"> </span>5<span class="tok-w"> </span>:<span class="tok-w"> </span>:<span class="tok-w"> </span><span class="tok-na"><cxxflags></span>"-std=c++14<span class="tok-w"> </span>-O2"<span class="tok-w"> </span>;<span class="tok-w"></span> 2183<span class="tok-nb">using</span><span class="tok-w"> </span>clang<span class="tok-w"> </span>:<span class="tok-w"> </span>3.9<span class="tok-w"> </span>:<span class="tok-w"> </span>:<span class="tok-w"> </span><span class="tok-na"><cxxflags></span>-std=c++14<span class="tok-w"> </span><span class="tok-na"><cxxflags></span>-O2<span class="tok-w"> </span>;<span class="tok-w"></span></code></pre> 2184</div> 2185</div> 2186<div class="paragraph"> 2187<p>Multiple variations of the same tool can be used for most tools. These 2188are delineated by the version passed in. Because the dash '-' cannot be 2189used here, the convention has become to use the tilde '~' to delineate 2190variations.</p> 2191</div> 2192<div class="listingblock"> 2193<div class="content"> 2194<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-nb">using</span><span class="tok-w"> </span>gcc<span class="tok-w"> </span>:<span class="tok-w"> </span>5<span class="tok-w"> </span>:<span class="tok-w"> </span>g++-5<span class="tok-w"> </span>:<span class="tok-w"> </span>;<span class="tok-w"> </span><span class="tok-c1"># default is C++ 98</span> 2195<span class="tok-nb">using</span><span class="tok-w"> </span>gcc<span class="tok-w"> </span>:<span class="tok-w"> </span>5~c++03<span class="tok-w"> </span>:<span class="tok-w"> </span>g++-5<span class="tok-w"> </span>:<span class="tok-w"> </span><span class="tok-na"><cxxflags></span>-std=c++03<span class="tok-w"> </span>;<span class="tok-w"> </span><span class="tok-c1"># C++ 03</span> 2196<span class="tok-nb">using</span><span class="tok-w"> </span>gcc<span class="tok-w"> </span>:<span class="tok-w"> </span>5~gnu03<span class="tok-w"> </span>:<span class="tok-w"> </span>g++-5<span class="tok-w"> </span>:<span class="tok-w"> </span><span class="tok-na"><cxxflags></span>-std=gnu++03<span class="tok-w"> </span>;<span class="tok-w"> </span><span class="tok-c1"># C++ 03 with GNU</span> 2197<span class="tok-nb">using</span><span class="tok-w"> </span>gcc<span class="tok-w"> </span>:<span class="tok-w"> </span>5~c++11<span class="tok-w"> </span>:<span class="tok-w"> </span>g++-5<span class="tok-w"> </span>:<span class="tok-w"> </span><span class="tok-na"><cxxflags></span>-std=c++11<span class="tok-w"> </span>;<span class="tok-w"> </span><span class="tok-c1"># C++ 11</span> 2198<span class="tok-nb">using</span><span class="tok-w"> </span>gcc<span class="tok-w"> </span>:<span class="tok-w"> </span>5~c++14<span class="tok-w"> </span>:<span class="tok-w"> </span>g++-5<span class="tok-w"> </span>:<span class="tok-w"> </span><span class="tok-na"><cxxflags></span>-std=c++14<span class="tok-w"> </span>;<span class="tok-w"> </span><span class="tok-c1"># C++ 14</span></code></pre> 2199</div> 2200</div> 2201<div class="paragraph"> 2202<p>These are then used as normal toolsets:</p> 2203</div> 2204<div class="listingblock"> 2205<div class="content"> 2206<pre class="pygments highlight"><code data-lang="shell"><span></span>b2 <span class="tok-nv">toolset</span><span class="tok-o">=</span>gcc-5 stage 2207b2 <span class="tok-nv">toolset</span><span class="tok-o">=</span>gcc-5~c++14 stage</code></pre> 2208</div> 2209</div> 2210<div class="admonitionblock warning"> 2211<table> 2212<tr> 2213<td class="icon"> 2214<div class="title">⚠</div> 2215</td> 2216<td class="content"> 2217Although the syntax used to specify toolset options is very similar 2218to syntax used to specify requirements in Jamfiles, the toolset options are 2219not the same as features. Don’t try to specify a feature value in 2220toolset initialization. 2221</td> 2222</tr> 2223</table> 2224</div> 2225</div> 2226<div class="sect2"> 2227<h3 id="bbv2.overview.invocation"><a class="anchor" href="#bbv2.overview.invocation"></a>3.4. Invocation</h3> 2228<div class="paragraph"> 2229<p>To invoke B2, type <code>b2</code> on the command line. Three kinds of 2230command-line tokens are accepted, in any order:</p> 2231</div> 2232<div class="dlist"> 2233<dl> 2234<dt class="hdlist1">options</dt> 2235<dd> 2236<p>Options start with either one or two dashes. The standard options are 2237listed below, and each project may add additional options</p> 2238</dd> 2239<dt class="hdlist1">properties</dt> 2240<dd> 2241<p>Properties specify details of what you want to build (e.g. debug or 2242release variant). Syntactically, all command line tokens with an equal 2243sign in them are considered to specify properties. In the simplest 2244form, a property looks like <code>feature=value</code></p> 2245</dd> 2246<dt class="hdlist1">target</dt> 2247<dd> 2248<p>All tokens that are neither options nor properties specify what 2249targets to build. The available targets entirely depend on the project 2250you are building.</p> 2251</dd> 2252</dl> 2253</div> 2254<div class="sect3"> 2255<h4 id="bbv2.overview.invocation.examples"><a class="anchor" href="#bbv2.overview.invocation.examples"></a>3.4.1. Examples</h4> 2256<div class="paragraph"> 2257<p>To build all targets defined in the Jamfile in the current directory 2258with the default properties, run:</p> 2259</div> 2260<div class="listingblock"> 2261<div class="content"> 2262<pre class="pygments highlight"><code data-lang="shell"><span></span>b2</code></pre> 2263</div> 2264</div> 2265<div class="paragraph"> 2266<p>To build specific targets, specify them on the command line:</p> 2267</div> 2268<div class="listingblock"> 2269<div class="content"> 2270<pre class="pygments highlight"><code data-lang="shell"><span></span>b2 lib1 subproject//lib2</code></pre> 2271</div> 2272</div> 2273<div class="paragraph"> 2274<p>To request a certain value for some property, add <code>property=value</code> to the 2275command line:</p> 2276</div> 2277<div class="listingblock"> 2278<div class="content"> 2279<pre class="pygments highlight"><code data-lang="shell"><span></span>b2 <span class="tok-nv">toolset</span><span class="tok-o">=</span>gcc <span class="tok-nv">variant</span><span class="tok-o">=</span>debug <span class="tok-nv">optimization</span><span class="tok-o">=</span>space</code></pre> 2280</div> 2281</div> 2282</div> 2283<div class="sect3"> 2284<h4 id="bbv2.overview.invocation.options"><a class="anchor" href="#bbv2.overview.invocation.options"></a>3.4.2. Options</h4> 2285<div class="paragraph"> 2286<p>B2 recognizes the following command line options.</p> 2287</div> 2288<div class="dlist"> 2289<dl> 2290<dt class="hdlist1"><a id="bbv2.overview.invocation.options.help"></a><code>--help</code></dt> 2291<dd> 2292<p>Invokes the online help system. This prints general information on how 2293to use the help system with additional --help* options.</p> 2294</dd> 2295<dt class="hdlist1"><code>--clean</code></dt> 2296<dd> 2297<p>Cleans all targets in the current directory and in any sub-projects. 2298Note that unlike the <code>clean</code> target in make, you can use <code>--clean</code> 2299together with target names to clean specific targets.</p> 2300</dd> 2301<dt class="hdlist1"><code>--clean-all</code></dt> 2302<dd> 2303<p>Cleans all targets, no matter where they are defined. In particular, 2304it will clean targets in parent Jamfiles, and targets defined under 2305other project roots.</p> 2306</dd> 2307<dt class="hdlist1"><code>--build-dir</code></dt> 2308<dd> 2309<p>Changes the build directories for all project roots being built. When 2310this option is specified, all Jamroot files must declare a project 2311name. The build directory for the project root will be computed by 2312concatenating the value of the <code>--build-dir</code> option, the project name 2313specified in Jamroot, and the build dir specified in Jamroot (or 2314<code>bin</code>, if none is specified). 2315The option is primarily useful when building from read-only media, 2316when you can’t modify Jamroot.</p> 2317</dd> 2318<dt class="hdlist1"><code>--abbreviate-paths</code></dt> 2319<dd> 2320<p>Compresses target paths by abbreviating each component. This option is 2321useful to keep paths from becoming longer than the filesystem 2322supports. See also <a href="#bbv2.reference.buildprocess.targetpath">the 2323section called “Target Paths”</a>.</p> 2324</dd> 2325<dt class="hdlist1"><code>--hash</code></dt> 2326<dd> 2327<p>Compresses target paths using an MD5 hash. This option is useful to 2328keep paths from becoming longer than the filesystem supports. This 2329option produces shorter paths than <code>--abbreviate-paths</code> does, but at the 2330cost of making them less understandable. See also 2331<a href="#bbv2.reference.buildprocess.targetpath">the section called “Target 2332Paths”</a>.</p> 2333</dd> 2334<dt class="hdlist1"><code>--version</code></dt> 2335<dd> 2336<p>Prints information on the B2 and Boost.Jam versions.</p> 2337</dd> 2338<dt class="hdlist1"><code>-a</code></dt> 2339<dd> 2340<p>Causes all files to be rebuilt.</p> 2341</dd> 2342<dt class="hdlist1"><code>-n</code></dt> 2343<dd> 2344<p>Do not execute the commands, only print them.</p> 2345</dd> 2346<dt class="hdlist1"><code>-q</code></dt> 2347<dd> 2348<p>Stop at the first error, as opposed to continuing to build targets 2349that don’t depend on the failed ones.</p> 2350</dd> 2351<dt class="hdlist1"><code>-j N</code></dt> 2352<dd> 2353<p>Run up to N commands in parallel. Default number of jobs is the number 2354of detected available CPU threads. Note: There are circumstances when that 2355default can be larger than the allocated cpu resources, for instance in some 2356virtualized container installs.</p> 2357</dd> 2358<dt class="hdlist1"><code>--config=filename</code><a id="bbv2.reference.init.options.config"></a></dt> 2359<dd> 2360<p>Override all <a href="#bbv2.overview.configuration">configuration files</a></p> 2361</dd> 2362<dt class="hdlist1"><code>--site-config=filename</code></dt> 2363<dd> 2364<p>Override the default <a href="#bbv2.overview.configuration">site-config.jam</a></p> 2365</dd> 2366<dt class="hdlist1"><code>--user-config=filename</code></dt> 2367<dd> 2368<p>Override the default <a href="#bbv2.overview.configuration">user-config.jam</a></p> 2369</dd> 2370<dt class="hdlist1"><code>--project-config=filename</code></dt> 2371<dd> 2372<p>Override the default <a href="#bbv2.overview.configuration">project-config.jam</a></p> 2373</dd> 2374<dt class="hdlist1"><code>--debug-configuration</code></dt> 2375<dd> 2376<p>Produces debug information about the loading of B2 and 2377toolset files.</p> 2378</dd> 2379<dt class="hdlist1"><code>--debug-building</code></dt> 2380<dd> 2381<p>Prints what targets are being built and with what properties.</p> 2382</dd> 2383<dt class="hdlist1"><code>--debug-generators</code></dt> 2384<dd> 2385<p>Produces debug output from the generator search process. Useful for 2386debugging custom generators.</p> 2387</dd> 2388<dt class="hdlist1"><code>-d0</code></dt> 2389<dd> 2390<p>Suppress all informational messages.</p> 2391</dd> 2392<dt class="hdlist1"><code>-d N</code></dt> 2393<dd> 2394<p>Enable cumulative debugging levels from 1 to n. Values are: 2395+</p> 2396<div class="olist arabic"> 2397<ol class="arabic"> 2398<li> 2399<p>Show the actions taken for building targets, as they are executed 2400(the default).</p> 2401</li> 2402<li> 2403<p>Show "quiet" actions and display all action text, as they are 2404executed.</p> 2405</li> 2406<li> 2407<p>Show dependency analysis, and target/source timestamps/paths.</p> 2408</li> 2409<li> 2410<p>Show arguments and timing of shell invocations.</p> 2411</li> 2412<li> 2413<p>Show rule invocations and variable expansions.</p> 2414</li> 2415<li> 2416<p>Show directory/header file/archive scans, and attempts at binding 2417to targets.</p> 2418</li> 2419<li> 2420<p>Show variable settings.</p> 2421</li> 2422<li> 2423<p>Show variable fetches, variable expansions, and evaluation of 2424'"if"' expressions.</p> 2425</li> 2426<li> 2427<p>Show variable manipulation, scanner tokens, and memory usage.</p> 2428</li> 2429<li> 2430<p>Show profile information for rules, both timing and memory.</p> 2431</li> 2432<li> 2433<p>Show parsing progress of Jamfiles.</p> 2434</li> 2435<li> 2436<p>Show graph of target dependencies.</p> 2437</li> 2438<li> 2439<p>Show change target status (fate).</p> 2440</li> 2441</ol> 2442</div> 2443</dd> 2444<dt class="hdlist1"><code>-d +N</code></dt> 2445<dd> 2446<p>Enable debugging level <code>N</code>.</p> 2447</dd> 2448<dt class="hdlist1"><code>-o file</code></dt> 2449<dd> 2450<p>Write the updating actions to the specified file instead of running 2451them.</p> 2452</dd> 2453<dt class="hdlist1"><code>-s var=value</code></dt> 2454<dd> 2455<p>Set the variable <code>var</code> to <code>value</code> in the global scope of the jam language 2456interpreter, overriding variables imported from the environment.</p> 2457</dd> 2458</dl> 2459</div> 2460</div> 2461<div class="sect3"> 2462<h4 id="bbv2.overview.invocation.properties"><a class="anchor" href="#bbv2.overview.invocation.properties"></a>3.4.3. Properties</h4> 2463<div class="paragraph"> 2464<p>In the simplest case, the build is performed with a single set of 2465properties, that you specify on the command line with elements in the 2466form <code>feature=value</code>. The complete list of features can be found in 2467<a href="#bbv2.overview.builtins.features">the section called “Builtin features”</a>. 2468The most common features are summarized below.</p> 2469</div> 2470<table class="tableblock frame-all grid-all stretch"> 2471<colgroup> 2472<col style="width: 33.3333%;"> 2473<col style="width: 33.3333%;"> 2474<col style="width: 33.3334%;"> 2475</colgroup> 2476<thead> 2477<tr> 2478<th class="tableblock halign-left valign-top">Feature</th> 2479<th class="tableblock halign-left valign-top">Allowed values</th> 2480<th class="tableblock halign-left valign-top">Notes</th> 2481</tr> 2482</thead> 2483<tbody> 2484<tr> 2485<td class="tableblock halign-left valign-top"><p class="tableblock">variant</p></td> 2486<td class="tableblock halign-left valign-top"><p class="tableblock">debug,release</p></td> 2487<td class="tableblock halign-left valign-top"><div class="content"></div></td> 2488</tr> 2489<tr> 2490<td class="tableblock halign-left valign-top"><p class="tableblock">link</p></td> 2491<td class="tableblock halign-left valign-top"><p class="tableblock">shared,static</p></td> 2492<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph"> 2493<p>Determines if B2 creates shared or static libraries</p> 2494</div></div></td> 2495</tr> 2496<tr> 2497<td class="tableblock halign-left valign-top"><p class="tableblock">threading</p></td> 2498<td class="tableblock halign-left valign-top"><p class="tableblock">single,multi</p></td> 2499<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph"> 2500<p>Cause the produced binaries to be thread-safe. This requires proper support 2501in the source code itself.</p> 2502</div></div></td> 2503</tr> 2504<tr> 2505<td class="tableblock halign-left valign-top"><p class="tableblock">address-model</p></td> 2506<td class="tableblock halign-left valign-top"><p class="tableblock">32,64</p></td> 2507<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph"> 2508<p>Explicitly request either 32-bit or 64-bit code 2509generation. This typically requires that your compiler is appropriately 2510configured. Please refer to 2511<a href="#bbv2.reference.tools.compilers">the section called “C++ Compilers”</a> 2512and your compiler documentation in case of problems.</p> 2513</div></div></td> 2514</tr> 2515<tr> 2516<td class="tableblock halign-left valign-top"><p class="tableblock">toolset</p></td> 2517<td class="tableblock halign-left valign-top"><p class="tableblock">(Depends on configuration)</p></td> 2518<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph"> 2519<p>The C++ compiler to use. See 2520<a href="#bbv2.reference.tools.compilers">the section called “C++ Compilers”</a> 2521for a detailed list.</p> 2522</div></div></td> 2523</tr> 2524<tr> 2525<td class="tableblock halign-left valign-top"><p class="tableblock">include</p></td> 2526<td class="tableblock halign-left valign-top"><p class="tableblock">(Arbitrary string)</p></td> 2527<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph"> 2528<p>Additional include paths for C and C++ compilers.</p> 2529</div></div></td> 2530</tr> 2531<tr> 2532<td class="tableblock halign-left valign-top"><p class="tableblock">define</p></td> 2533<td class="tableblock halign-left valign-top"><p class="tableblock">(Arbitrary string)</p></td> 2534<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph"> 2535<p>Additional macro definitions for C and C++ compilers. The string should be 2536either <code>SYMBOL</code> or <code>SYMBOL=VALUE</code></p> 2537</div></div></td> 2538</tr> 2539<tr> 2540<td class="tableblock halign-left valign-top"><p class="tableblock">cxxflags</p></td> 2541<td class="tableblock halign-left valign-top"><p class="tableblock">(Arbitrary string)</p></td> 2542<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph"> 2543<p>Custom options to pass to the C++ compiler.</p> 2544</div></div></td> 2545</tr> 2546<tr> 2547<td class="tableblock halign-left valign-top"><p class="tableblock">cflags</p></td> 2548<td class="tableblock halign-left valign-top"><p class="tableblock">(Arbitrary string)</p></td> 2549<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph"> 2550<p>Custom options to pass to the C compiler.</p> 2551</div></div></td> 2552</tr> 2553<tr> 2554<td class="tableblock halign-left valign-top"><p class="tableblock">linkflags</p></td> 2555<td class="tableblock halign-left valign-top"><p class="tableblock">(Arbitrary string)</p></td> 2556<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph"> 2557<p>Custom options to pass to the C++ linker.</p> 2558</div></div></td> 2559</tr> 2560<tr> 2561<td class="tableblock halign-left valign-top"><p class="tableblock">runtime-link</p></td> 2562<td class="tableblock halign-left valign-top"><p class="tableblock">shared,static</p></td> 2563<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph"> 2564<p>Determines if shared or static version of C and C++ runtimes should be used.</p> 2565</div></div></td> 2566</tr> 2567</tbody> 2568</table> 2569<div class="paragraph"> 2570<p>If you have more than one version of a given C++ toolset (e.g. 2571configured in <code>user-config.jam</code>, or autodetected, as happens with msvc), 2572you can request the specific version by passing <code>toolset-version</code> as the 2573value of the <code>toolset</code> feature, for example <code>toolset=msvc-8.0</code>.</p> 2574</div> 2575<div class="paragraph"> 2576<p>If a feature has a fixed set of values it can be specified more than 2577once on the command line. In which case, everything will be built 2578several times — once for each specified value of a feature. For 2579example, if you use</p> 2580</div> 2581<div class="listingblock"> 2582<div class="content"> 2583<pre class="pygments highlight"><code data-lang="shell"><span></span>b2 <span class="tok-nv">link</span><span class="tok-o">=</span>static <span class="tok-nv">link</span><span class="tok-o">=</span>shared <span class="tok-nv">threading</span><span class="tok-o">=</span>single <span class="tok-nv">threading</span><span class="tok-o">=</span>multi</code></pre> 2584</div> 2585</div> 2586<div class="paragraph"> 2587<p>Then a total of 4 builds will be performed. For convenience, instead of 2588specifying all requested values of a feature in separate command line 2589elements, you can separate the values with commas, for example:</p> 2590</div> 2591<div class="listingblock"> 2592<div class="content"> 2593<pre class="pygments highlight"><code data-lang="shell"><span></span>b2 <span class="tok-nv">link</span><span class="tok-o">=</span>static,shared <span class="tok-nv">threading</span><span class="tok-o">=</span>single,multi</code></pre> 2594</div> 2595</div> 2596<div class="paragraph"> 2597<p>The comma has this special meaning only if the feature has a fixed set 2598of values, so</p> 2599</div> 2600<div class="listingblock"> 2601<div class="content"> 2602<pre class="pygments highlight"><code data-lang="shell"><span></span>b2 <span class="tok-nv">include</span><span class="tok-o">=</span>static,shared</code></pre> 2603</div> 2604</div> 2605<div class="paragraph"> 2606<p>is not treated specially.</p> 2607</div> 2608<div class="paragraph"> 2609<p>Multiple features may be grouped by using a forwards slash.</p> 2610</div> 2611<div class="listingblock"> 2612<div class="content"> 2613<pre class="pygments highlight"><code data-lang="shell"><span></span>b2 gcc/link<span class="tok-o">=</span>shared msvc/link<span class="tok-o">=</span>static,shared</code></pre> 2614</div> 2615</div> 2616<div class="paragraph"> 2617<p>This will build 3 different variants, altogether.</p> 2618</div> 2619</div> 2620<div class="sect3"> 2621<h4 id="bbv2.overview.invocation.targets"><a class="anchor" href="#bbv2.overview.invocation.targets"></a>3.4.4. Targets</h4> 2622<div class="paragraph"> 2623<p>All command line elements that are neither options nor properties are 2624the names of the targets to build. See <a href="#bbv2.reference.ids">the section 2625called “Target identifiers and references”</a>. If no target is specified, the 2626project in the current directory is built.</p> 2627</div> 2628</div> 2629</div> 2630<div class="sect2"> 2631<h3 id="bbv2.overview.targets"><a class="anchor" href="#bbv2.overview.targets"></a>3.5. Declaring Targets</h3> 2632<div id="bbv2.overview.targets.main" class="paragraph"> 2633<p>A Main target is a user-defined named entity that can be built, for 2634example an executable file. Declaring a main target is usually done 2635using one of the main target rules described in 2636<a href="#bbv2.reference.rules">the section called “Builtin rules”</a>. The user can 2637also declare custom main target rules as shown in 2638<a href="#bbv2.extending.rules">the section called “Main target rules”</a>.</p> 2639</div> 2640<div class="paragraph"> 2641<p><a id="bbv2.main-target-rule-syntax"></a> 2642Most main target rules in B2 have the same common signature:</p> 2643</div> 2644<div class="listingblock"> 2645<div class="content"> 2646<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-k">rule</span><span class="tok-w"> </span><span class="tok-nf">rule-name</span><span class="tok-w"> </span><span class="tok-p">(</span><span class="tok-w"></span> 2647<span class="tok-w"> </span><span class="tok-nv">main-target-name</span><span class="tok-w"> </span><span class="tok-p">:</span><span class="tok-w"></span> 2648<span class="tok-w"> </span><span class="tok-nv">sources</span><span class="tok-w"> </span><span class="tok-p">+</span><span class="tok-w"> </span><span class="tok-p">:</span><span class="tok-w"></span> 2649<span class="tok-w"> </span><span class="tok-nv">requirements</span><span class="tok-w"> </span><span class="tok-p">*</span><span class="tok-w"> </span><span class="tok-p">:</span><span class="tok-w"></span> 2650<span class="tok-w"> </span><span class="tok-nv">default-build</span><span class="tok-w"> </span><span class="tok-p">*</span><span class="tok-w"> </span><span class="tok-p">:</span><span class="tok-w"></span> 2651<span class="tok-w"> </span><span class="tok-nv">usage-requirements</span><span class="tok-w"> </span><span class="tok-p">*</span><span class="tok-w"> </span><span class="tok-p">)</span><span class="tok-w"></span></code></pre> 2652</div> 2653</div> 2654<div class="ulist"> 2655<ul> 2656<li> 2657<p><code>main-target-name</code> is the name used to request the target on command 2658line and to use it from other main targets. A main target name may 2659contain alphanumeric characters, dashes (‘<code>-</code>’), and underscores 2660(‘<code>_</code>’).</p> 2661</li> 2662<li> 2663<p><code>sources</code> is the list of source files and other main targets that must 2664be combined.</p> 2665</li> 2666<li> 2667<p><code>requirements</code> is the list of properties that must always be present 2668when this main target is built.</p> 2669</li> 2670<li> 2671<p><code>default-build</code> is the list of properties that will be used unless 2672some other value of the same feature is already specified, e.g. on the 2673command line or by propagation from a dependent target.</p> 2674</li> 2675<li> 2676<p><code>usage-requirements</code> is the list of properties that will be propagated 2677to all main targets that use this one, i.e. to all its dependents.</p> 2678</li> 2679</ul> 2680</div> 2681<div class="paragraph"> 2682<p>Some main target rules have a different list of parameters as explicitly 2683stated in their documentation.</p> 2684</div> 2685<div class="paragraph"> 2686<p>The actual requirements for a target are obtained by refining the 2687requirements of the project where the target is declared with the 2688explicitly specified requirements. The same is true for 2689usage-requirements. More details can be found in 2690<a href="#bbv2.reference.variants.proprefine">the section called “Property refinement”</a>.</p> 2691</div> 2692<div class="sect3"> 2693<h4 id="_name"><a class="anchor" href="#_name"></a>3.5.1. Name</h4> 2694<div class="paragraph"> 2695<p>The name of main target has two purposes. First, it’s used to refer to 2696this target from other targets and from command line. Second, it’s used 2697to compute the names of the generated files. Typically, filenames are 2698obtained from main target name by appending system-dependent suffixes 2699and prefixes.</p> 2700</div> 2701<div class="paragraph"> 2702<p>The name of a main target can contain alphanumeric characters, dashes, 2703underscores and dots. The entire name is significant when resolving 2704references from other targets. For determining filenames, only the part 2705before the first dot is taken. For example:</p> 2706</div> 2707<div class="listingblock"> 2708<div class="content"> 2709<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-nb">obj</span><span class="tok-w"> </span>test.release<span class="tok-w"> </span>:<span class="tok-w"> </span>test.cpp<span class="tok-w"> </span>:<span class="tok-w"> </span><span class="tok-na"><variant></span>release<span class="tok-w"> </span>;<span class="tok-w"></span> 2710<span class="tok-nb">obj</span><span class="tok-w"> </span>test.debug<span class="tok-w"> </span>:<span class="tok-w"> </span>test.cpp<span class="tok-w"> </span>:<span class="tok-w"> </span><span class="tok-na"><variant></span>debug<span class="tok-w"> </span>;<span class="tok-w"></span></code></pre> 2711</div> 2712</div> 2713<div class="paragraph"> 2714<p>will generate two files named <code>test.obj</code> (in two different directories), 2715not two files named <code>test.release.obj</code> and <code>test.debug.obj</code>.</p> 2716</div> 2717</div> 2718<div class="sect3"> 2719<h4 id="_sources"><a class="anchor" href="#_sources"></a>3.5.2. Sources</h4> 2720<div class="paragraph"> 2721<p>The list of sources specifies what should be processed to get the 2722resulting targets. Most of the time, it’s just a list of files. 2723Sometimes, you’ll want to automatically construct the list of source 2724files rather than having to spell it out manually, in which case you can 2725use the <a href="#bbv2.reference.rules.glob">glob</a> rule. Here are two 2726examples:</p> 2727</div> 2728<div class="listingblock"> 2729<div class="content"> 2730<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-nb">exe</span><span class="tok-w"> </span>a<span class="tok-w"> </span>:<span class="tok-w"> </span>a.cpp<span class="tok-w"> </span>;<span class="tok-w"> </span><b class="conum">(1)</b> 2731<span class="tok-nb">exe</span><span class="tok-w"> </span>b<span class="tok-w"> </span>:<span class="tok-w"> </span>[<span class="tok-w"> </span><span class="tok-nb">glob</span><span class="tok-w"> </span>*.cpp<span class="tok-w"> </span>]<span class="tok-w"> </span>;<span class="tok-w"> </span><b class="conum">(2)</b></code></pre> 2732</div> 2733</div> 2734<div class="colist arabic"> 2735<ol> 2736<li> 2737<p><code>a.cpp</code> is the only source file</p> 2738</li> 2739<li> 2740<p>all <code>.cpp</code> files in this directory are sources</p> 2741</li> 2742</ol> 2743</div> 2744<div class="paragraph"> 2745<p>Unless you specify a file with an absolute path, the name is considered 2746relative to the source directory — which is typically the directory 2747where the Jamfile is located, but can be changed as described in 2748<a href="#bbv2.overview.projects.attributes.projectrule">the section called “Projects”</a>.</p> 2749</div> 2750<div class="paragraph"> 2751<p>The list of sources can also refer to other main targets. Targets in the 2752same project can be referred to by name, while targets in other projects 2753must be qualified with a directory or a symbolic project name. The 2754directory/project name is separated from the target name by a double 2755forward slash. There is no special syntax to distinguish the directory 2756name from the project name—the part before the double slash is first 2757looked up as project name, and then as directory name. For example:</p> 2758</div> 2759<div class="listingblock"> 2760<div class="content"> 2761<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-nb">lib</span><span class="tok-w"> </span>helper<span class="tok-w"> </span>:<span class="tok-w"> </span>helper.cpp<span class="tok-w"> </span>;<span class="tok-w"></span> 2762<span class="tok-nb">exe</span><span class="tok-w"> </span>a<span class="tok-w"> </span>:<span class="tok-w"> </span>a.cpp<span class="tok-w"> </span>helper<span class="tok-w"> </span>;<span class="tok-w"></span> 2763<span class="tok-nb">exe</span><span class="tok-w"> </span>b<span class="tok-w"> </span>:<span class="tok-w"> </span>b.cpp<span class="tok-w"> </span>..//utils<span class="tok-w"> </span>;<span class="tok-w"> </span><b class="conum">(1)</b> 2764<span class="tok-nb">exe</span><span class="tok-w"> </span>c<span class="tok-w"> </span>:<span class="tok-w"> </span>c.cpp<span class="tok-w"> </span>/boost/program_options//program_options<span class="tok-w"> </span>;<span class="tok-w"></span></code></pre> 2765</div> 2766</div> 2767<div class="colist arabic"> 2768<ol> 2769<li> 2770<p>Since all project ids start with slash, “..” is a directory name.</p> 2771</li> 2772</ol> 2773</div> 2774<div class="paragraph"> 2775<p>The first exe uses the library defined in the same project. The second 2776one uses some target (most likely a library) defined by a Jamfile one 2777level higher. Finally, the third target uses a <a href="http://boost.org">C++ 2778Boost</a> library, referring to it using its absolute symbolic name. More 2779information about target references can be found in 2780<a href="#bbv2.tutorial.libs">the section called “Dependent Targets”</a> and 2781<a href="#bbv2.reference.ids">the section called “Target identifiers and references”</a>.</p> 2782</div> 2783</div> 2784<div class="sect3"> 2785<h4 id="bbv2.overview.targets.requirements"><a class="anchor" href="#bbv2.overview.targets.requirements"></a>3.5.3. Requirements</h4> 2786<div class="paragraph"> 2787<p>Requirements are the properties that should always be present when 2788building a target. Typically, they are includes and defines:</p> 2789</div> 2790<div class="listingblock"> 2791<div class="content"> 2792<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-nb">exe</span><span class="tok-w"> </span>hello<span class="tok-w"> </span>:<span class="tok-w"> </span>hello.cpp<span class="tok-w"> </span>:<span class="tok-w"> </span><span class="tok-na"><include></span>/opt/boost<span class="tok-w"> </span><span class="tok-na"><define></span>MY_DEBUG<span class="tok-w"> </span>;<span class="tok-w"></span></code></pre> 2793</div> 2794</div> 2795<div class="paragraph"> 2796<p>There are a number of other features, listed in 2797<a href="#bbv2.overview.builtins.features">the section called “Builtin features”</a>. 2798For example if a library can only be built statically, or a file can’t be 2799compiled with optimization due to a compiler bug, one can use.</p> 2800</div> 2801<div class="listingblock"> 2802<div class="content"> 2803<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-nb">lib</span><span class="tok-w"> </span>util<span class="tok-w"> </span>:<span class="tok-w"> </span>util.cpp<span class="tok-w"> </span>:<span class="tok-w"> </span><span class="tok-na"><link></span>static<span class="tok-w"> </span>;<span class="tok-w"></span> 2804<span class="tok-nb">obj</span><span class="tok-w"> </span>main<span class="tok-w"> </span>:<span class="tok-w"> </span>main.cpp<span class="tok-w"> </span>:<span class="tok-w"> </span><span class="tok-na"><optimization></span>off<span class="tok-w"> </span>;<span class="tok-w"></span></code></pre> 2805</div> 2806</div> 2807<div class="paragraph"> 2808<p><a id="bbv2.overview.targets.requirements.conditional"></a>Sometimes, particular 2809relationships need to be 2810maintained among a target’s build properties. This can be achieved with 2811<em>conditional requirements</em>. For example, you might want to set specific 2812<code>#defines</code> when a library is built as shared, or when a target’s 2813<code>release</code> variant is built in release mode.</p> 2814</div> 2815<div class="listingblock"> 2816<div class="content"> 2817<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-nb">lib</span><span class="tok-w"> </span>network<span class="tok-w"> </span>:<span class="tok-w"> </span>network.cpp<span class="tok-w"></span> 2818<span class="tok-w"> </span>:<span class="tok-w"> </span><span class="tok-na"><link></span>shared:<span class="tok-na"><define></span>NETWORK_LIB_SHARED<span class="tok-w"></span> 2819<span class="tok-w"> </span><span class="tok-na"><variant></span>release:<span class="tok-na"><define></span>EXTRA_FAST<span class="tok-w"></span> 2820<span class="tok-w"> </span>;<span class="tok-w"></span></code></pre> 2821</div> 2822</div> 2823<div class="paragraph"> 2824<p>In the example above, whenever <code>network</code> is built with <code><link>shared</code>, 2825<code><define>NETWORK_LIB_SHARED</code> will be in its properties, too.</p> 2826</div> 2827<div class="paragraph"> 2828<p>You can use several properties in the condition, for example:</p> 2829</div> 2830<div class="listingblock"> 2831<div class="content"> 2832<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-nb">lib</span><span class="tok-w"> </span>network<span class="tok-w"> </span>:<span class="tok-w"> </span>network.cpp<span class="tok-w"></span> 2833<span class="tok-w"> </span>:<span class="tok-w"> </span><span class="tok-na"><toolset></span>gcc,<span class="tok-na"><optimization></span>speed:<span class="tok-na"><define></span>USE_INLINE_ASSEMBLER<span class="tok-w"></span> 2834<span class="tok-w"> </span>;<span class="tok-w"></span></code></pre> 2835</div> 2836</div> 2837<div class="paragraph"> 2838<p>A more powerful variant of conditional requirements 2839is <em>indirect conditional</em> requirements. You can provide a rule that will 2840be called with the current build properties and can compute additional 2841properties to be added. For example:</p> 2842</div> 2843<div class="listingblock"> 2844<div class="content"> 2845<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-nb">lib</span><span class="tok-w"> </span>network<span class="tok-w"> </span>:<span class="tok-w"> </span>network.cpp<span class="tok-w"></span> 2846<span class="tok-w"> </span>:<span class="tok-w"> </span><span class="tok-na"><conditional></span>@my-rule<span class="tok-w"></span> 2847<span class="tok-w"> </span>;<span class="tok-w"></span> 2848<span class="tok-k">rule</span><span class="tok-w"> </span><span class="tok-nf">my-rule</span><span class="tok-w"> </span><span class="tok-p">(</span><span class="tok-w"> </span><span class="tok-nv">properties</span><span class="tok-w"> </span><span class="tok-p">*</span><span class="tok-w"> </span><span class="tok-p">)</span><span class="tok-w"></span> 2849{<span class="tok-w"></span> 2850<span class="tok-w"> </span><span class="tok-k">local</span><span class="tok-w"> </span>result<span class="tok-w"> </span>;<span class="tok-w"></span> 2851<span class="tok-w"> </span><span class="tok-k">if</span><span class="tok-w"> </span><span class="tok-na"><toolset></span>gcc<span class="tok-w"> </span><span class="tok-na"><optimization></span>speed<span class="tok-w"> </span><span class="tok-k">in</span><span class="tok-w"> </span><span class="tok-si">$(properties)</span><span class="tok-w"></span> 2852<span class="tok-w"> </span>{<span class="tok-w"></span> 2853<span class="tok-w"> </span>result<span class="tok-w"> </span>+=<span class="tok-w"> </span><span class="tok-na"><define></span>USE_INLINE_ASSEMBLER<span class="tok-w"> </span>;<span class="tok-w"></span> 2854<span class="tok-w"> </span>}<span class="tok-w"></span> 2855<span class="tok-w"> </span><span class="tok-k">return</span><span class="tok-w"> </span><span class="tok-si">$(result)</span><span class="tok-w"> </span>;<span class="tok-w"></span> 2856}<span class="tok-w"></span></code></pre> 2857</div> 2858</div> 2859<div class="paragraph"> 2860<p>This example is equivalent to the previous one, but for complex cases, 2861indirect conditional requirements can be easier to write and understand.</p> 2862</div> 2863<div class="paragraph"> 2864<p>Requirements explicitly specified for a target are usually combined with 2865the requirements specified for the containing project. You can cause a 2866target to completely ignore a specific project requirement using the 2867syntax by adding a minus sign before the property, for example:</p> 2868</div> 2869<div class="listingblock"> 2870<div class="content"> 2871<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-nb">exe</span><span class="tok-w"> </span>main<span class="tok-w"> </span>:<span class="tok-w"> </span>main.cpp<span class="tok-w"> </span>:<span class="tok-w"> </span>-<span class="tok-na"><define></span>UNNECESSARY_DEFINE<span class="tok-w"> </span>;<span class="tok-w"></span></code></pre> 2872</div> 2873</div> 2874<div class="paragraph"> 2875<p>This syntax is the only way to ignore free properties, such as defines, 2876from a parent. It can be also useful for ordinary properties. Consider 2877this example:</p> 2878</div> 2879<div class="listingblock"> 2880<div class="content"> 2881<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-nb">project</span><span class="tok-w"> </span>test<span class="tok-w"> </span>:<span class="tok-w"> </span>requirements<span class="tok-w"> </span><span class="tok-na"><threading></span>multi<span class="tok-w"> </span>;<span class="tok-w"></span> 2882<span class="tok-nb">exe</span><span class="tok-w"> </span>test1<span class="tok-w"> </span>:<span class="tok-w"> </span>test1.cpp<span class="tok-w"> </span>;<span class="tok-w"></span> 2883<span class="tok-nb">exe</span><span class="tok-w"> </span>test2<span class="tok-w"> </span>:<span class="tok-w"> </span>test2.cpp<span class="tok-w"> </span>:<span class="tok-w"> </span><span class="tok-na"><threading></span>single<span class="tok-w"> </span>;<span class="tok-w"></span> 2884<span class="tok-nb">exe</span><span class="tok-w"> </span>test3<span class="tok-w"> </span>:<span class="tok-w"> </span>test3.cpp<span class="tok-w"> </span>:<span class="tok-w"> </span>-<span class="tok-na"><threading></span>multi<span class="tok-w"> </span>;<span class="tok-w"></span></code></pre> 2885</div> 2886</div> 2887<div class="paragraph"> 2888<p>Here, <code>test1</code> inherits the project requirements and will always be built 2889in multi-threaded mode. The <code>test2</code> target <em>overrides</em> the project’s 2890requirements and will always be built in single-threaded mode. In 2891contrast, the <code>test3</code> target <em>removes</em> a property from the project 2892requirements and will be built either in single-threaded or 2893multi-threaded mode depending on which variant is requested by the user.</p> 2894</div> 2895<div class="paragraph"> 2896<p>Note that the removal of requirements is completely textual: you need to 2897specify exactly the same property to remove it.</p> 2898</div> 2899</div> 2900<div class="sect3"> 2901<h4 id="_default_build"><a class="anchor" href="#_default_build"></a>3.5.4. Default Build</h4> 2902<div class="paragraph"> 2903<p>The <code>default-build</code> parameter is a set of properties to be used if the 2904build request does not otherwise specify a value for features in the 2905set. For example:</p> 2906</div> 2907<div class="listingblock"> 2908<div class="content"> 2909<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-nb">exe</span><span class="tok-w"> </span>hello<span class="tok-w"> </span>:<span class="tok-w"> </span>hello.cpp<span class="tok-w"> </span>:<span class="tok-w"> </span>:<span class="tok-w"> </span><span class="tok-na"><threading></span>multi<span class="tok-w"> </span>;<span class="tok-w"></span></code></pre> 2910</div> 2911</div> 2912<div class="paragraph"> 2913<p>would build a multi-threaded target unless the user explicitly requests 2914a single-threaded version. The difference between the requirements and 2915the default-build is that the requirements cannot be overridden in any 2916way.</p> 2917</div> 2918</div> 2919<div class="sect3"> 2920<h4 id="_additional_information"><a class="anchor" href="#_additional_information"></a>3.5.5. Additional Information</h4> 2921<div class="paragraph"> 2922<p>The ways a target is built can be so different that describing them 2923using conditional requirements would be hard. For example, imagine that 2924a library actually uses different source files depending on the toolset 2925used to build it. We can express this situation using <em>target alternatives</em>:</p> 2926</div> 2927<div class="listingblock"> 2928<div class="content"> 2929<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-nb">lib</span><span class="tok-w"> </span>demangler<span class="tok-w"> </span>:<span class="tok-w"> </span>dummy_demangler.cpp<span class="tok-w"> </span>;<span class="tok-w"> </span><span class="tok-c1"># alternative 1</span> 2930<span class="tok-nb">lib</span><span class="tok-w"> </span>demangler<span class="tok-w"> </span>:<span class="tok-w"> </span>demangler_gcc.cpp<span class="tok-w"> </span>:<span class="tok-w"> </span><span class="tok-na"><toolset></span>gcc<span class="tok-w"> </span>;<span class="tok-w"> </span><span class="tok-c1"># alternative 2</span> 2931<span class="tok-nb">lib</span><span class="tok-w"> </span>demangler<span class="tok-w"> </span>:<span class="tok-w"> </span>demangler_msvc.cpp<span class="tok-w"> </span>:<span class="tok-w"> </span><span class="tok-na"><toolset></span>msvc<span class="tok-w"> </span>;<span class="tok-w"> </span><span class="tok-c1"># alternative 3</span></code></pre> 2932</div> 2933</div> 2934<div class="paragraph"> 2935<p>In the example above, when built with <code>gcc</code> or <code>msvc</code>, <code>demangler</code> will 2936use a source file specific to the toolset. Otherwise, it will use a 2937generic source file, <code>dummy_demangler.cpp</code>.</p> 2938</div> 2939<div class="paragraph"> 2940<p>It is possible to declare a target inline, i.e. the "sources" parameter 2941may include calls to other main rules. For example:</p> 2942</div> 2943<div class="listingblock"> 2944<div class="content"> 2945<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-nb">exe</span><span class="tok-w"> </span>hello<span class="tok-w"> </span>:<span class="tok-w"> </span>hello.cpp<span class="tok-w"></span> 2946<span class="tok-w"> </span>[<span class="tok-w"> </span><span class="tok-nb">obj</span><span class="tok-w"> </span>helpers<span class="tok-w"> </span>:<span class="tok-w"> </span>helpers.cpp<span class="tok-w"> </span>:<span class="tok-w"> </span><span class="tok-na"><optimization></span>off<span class="tok-w"> </span>]<span class="tok-w"> </span>;<span class="tok-w"></span></code></pre> 2947</div> 2948</div> 2949<div class="paragraph"> 2950<p>Will cause "helpers.cpp" to be always compiled without optimization. 2951When referring to an inline main target, its declared name must be 2952prefixed by its parent target’s name and two dots. In the example above, 2953to build only helpers, one should run <code>b2 hello..helpers</code>.</p> 2954</div> 2955<div class="paragraph"> 2956<p>When no target is requested on the command line, all targets in the 2957current project will be built. If a target should be built only by 2958explicit request, this can be expressed by the 2959<a href="#bbv2.reference.rules.explicit">explicit</a> rule:</p> 2960</div> 2961<div class="listingblock"> 2962<div class="content"> 2963<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-nb">explicit</span><span class="tok-w"> </span>install_programs<span class="tok-w"> </span>;<span class="tok-w"></span></code></pre> 2964</div> 2965</div> 2966</div> 2967</div> 2968<div class="sect2"> 2969<h3 id="bbv2.overview.projects"><a class="anchor" href="#bbv2.overview.projects"></a>3.6. Projects</h3> 2970<div class="paragraph"> 2971<p>As mentioned before, targets are grouped into projects, and each Jamfile 2972is a separate project. Projects are useful because they allow us to 2973group related targets together, define properties common to all those 2974targets, and assign a symbolic name to the project that can be used in 2975referring to its targets.</p> 2976</div> 2977<div class="paragraph"> 2978<p>Projects are named using the <code>project</code> rule, which has the following 2979syntax:</p> 2980</div> 2981<div class="listingblock"> 2982<div class="content"> 2983<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-nb">project</span><span class="tok-w"> </span>id<span class="tok-w"> </span>:<span class="tok-w"> </span>attributes<span class="tok-w"> </span>;<span class="tok-w"></span></code></pre> 2984</div> 2985</div> 2986<div class="paragraph"> 2987<p>Here, <em>attributes</em> is a sequence of rule arguments, each of which begins 2988with an attribute-name and is followed by any number of build 2989properties. The list of attribute names along with its handling is also 2990shown in the table below. For example, it is possible to write:</p> 2991</div> 2992<div class="listingblock"> 2993<div class="content"> 2994<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-nb">project</span><span class="tok-w"> </span>tennis<span class="tok-w"></span> 2995<span class="tok-w"> </span>:<span class="tok-w"> </span>requirements<span class="tok-w"> </span><span class="tok-na"><threading></span>multi<span class="tok-w"></span> 2996<span class="tok-w"> </span>:<span class="tok-w"> </span>default-build<span class="tok-w"> </span>release<span class="tok-w"></span> 2997<span class="tok-w"> </span>;<span class="tok-w"></span></code></pre> 2998</div> 2999</div> 3000<div class="paragraph"> 3001<p>The possible attributes are listed below.</p> 3002</div> 3003<div class="paragraph"> 3004<p><em>Project id</em> is a short way to denote a project, as opposed to the 3005Jamfile’s pathname. It is a hierarchical path, unrelated to filesystem, 3006such as "boost/thread". <a href="#bbv2.reference.ids">Target references</a> make 3007use of project ids to specify a target.</p> 3008</div> 3009<div class="paragraph"> 3010<p><em>Source location</em> specifies the directory where sources for the project 3011are located.</p> 3012</div> 3013<div class="paragraph"> 3014<p><em>Project requirements</em> are requirements that apply to all the targets in 3015the projects as well as all sub-projects.</p> 3016</div> 3017<div class="paragraph"> 3018<p><em>Default build</em> is the build request that should be used when no build 3019request is specified explicitly.</p> 3020</div> 3021<div id="bbv2.overview.projects.attributes.projectrule" class="paragraph"> 3022<p>The default values for those attributes are given in the table below.</p> 3023</div> 3024<table class="tableblock frame-all grid-all stretch"> 3025<colgroup> 3026<col style="width: 25%;"> 3027<col style="width: 25%;"> 3028<col style="width: 25%;"> 3029<col style="width: 25%;"> 3030</colgroup> 3031<thead> 3032<tr> 3033<th class="tableblock halign-left valign-top">Attribute</th> 3034<th class="tableblock halign-left valign-top">Name</th> 3035<th class="tableblock halign-left valign-top">Default value</th> 3036<th class="tableblock halign-left valign-top">Handling by the <code>project</code> rule</th> 3037</tr> 3038</thead> 3039<tbody> 3040<tr> 3041<td class="tableblock halign-left valign-top"><p class="tableblock">Project id</p></td> 3042<td class="tableblock halign-left valign-top"><p class="tableblock">none</p></td> 3043<td class="tableblock halign-left valign-top"><p class="tableblock">none</p></td> 3044<td class="tableblock halign-left valign-top"><p class="tableblock">Assigned from the first parameter of the 3045'project' rule. It is assumed to denote absolute project id.</p></td> 3046</tr> 3047<tr> 3048<td class="tableblock halign-left valign-top"><p class="tableblock">Source location</p></td> 3049<td class="tableblock halign-left valign-top"><p class="tableblock"><code>source-location</code></p></td> 3050<td class="tableblock halign-left valign-top"><p class="tableblock">The location of jamfile for the 3051project</p></td> 3052<td class="tableblock halign-left valign-top"><p class="tableblock">Sets to the passed value</p></td> 3053</tr> 3054<tr> 3055<td class="tableblock halign-left valign-top"><p class="tableblock">Requirements</p></td> 3056<td class="tableblock halign-left valign-top"><p class="tableblock"><code>requirements</code></p></td> 3057<td class="tableblock halign-left valign-top"><p class="tableblock">The parent’s requirements</p></td> 3058<td class="tableblock halign-left valign-top"><p class="tableblock">The parent’s 3059requirements are refined with the passed requirement and the result is 3060used as the project requirements.</p></td> 3061</tr> 3062<tr> 3063<td class="tableblock halign-left valign-top"><p class="tableblock">Default build</p></td> 3064<td class="tableblock halign-left valign-top"><p class="tableblock"><code>default-build</code></p></td> 3065<td class="tableblock halign-left valign-top"><p class="tableblock">none</p></td> 3066<td class="tableblock halign-left valign-top"><p class="tableblock">Sets to the passed value</p></td> 3067</tr> 3068<tr> 3069<td class="tableblock halign-left valign-top"><p class="tableblock">Build directory</p></td> 3070<td class="tableblock halign-left valign-top"><p class="tableblock"><code>build-dir</code></p></td> 3071<td class="tableblock halign-left valign-top"><p class="tableblock">Empty if the parent has no build 3072directory set. Otherwise, the parent’s build directory with the relative 3073path from parent to the current project appended to it.</p></td> 3074<td class="tableblock halign-left valign-top"><p class="tableblock">Sets to the 3075passed value, interpreted as relative to the project’s location.</p></td> 3076</tr> 3077</tbody> 3078</table> 3079<div class="paragraph"> 3080<p>Besides defining projects and main targets, Jamfiles often invoke 3081various utility rules. For the full list of rules that can be directly 3082used in Jamfile see 3083<a href="#bbv2.reference.rules">the section called “Builtin rules”</a>.</p> 3084</div> 3085<div class="paragraph"> 3086<p>Each subproject inherits attributes, constants and rules from its parent 3087project, which is defined by the nearest Jamfile in an ancestor 3088directory above the subproject. The top-level project is declared in a 3089file called <code>Jamroot</code>, or <code>Jamfile</code>. When loading a project, 3090B2 looks for either <code>Jamroot</code> or <code>Jamfile</code>. They are handled 3091identically, except that if the file is called <code>Jamroot</code>, the search for 3092a parent project is not performed. A <code>Jamfile</code> without a parent project 3093is also considered the top-level project.</p> 3094</div> 3095<div class="paragraph"> 3096<p>Even when building in a subproject directory, parent project files are 3097always loaded before those of their sub-projects, so that every 3098definition made in a parent project is always available to its children. 3099The loading order of any other projects is unspecified. Even if one 3100project refers to another via the <code>use-project</code> or a target reference, 3101no specific order should be assumed.</p> 3102</div> 3103<div class="admonitionblock note"> 3104<table> 3105<tr> 3106<td class="icon"> 3107<div class="title">ℹ</div> 3108</td> 3109<td class="content"> 3110Giving the root project the special name “<code>Jamroot</code>” ensures that 3111B2 won’t misinterpret a directory above it as the project root 3112just because the directory contains a Jamfile. 3113</td> 3114</tr> 3115</table> 3116</div> 3117</div> 3118<div class="sect2"> 3119<h3 id="bbv2.overview.build_process"><a class="anchor" href="#bbv2.overview.build_process"></a>3.7. The Build Process</h3> 3120<div class="paragraph"> 3121<p>When you’ve described your targets, you want B2 to run the 3122right tools and create the needed targets. This section will describe 3123two things: how you specify what to build, and how the main targets are 3124actually constructed.</p> 3125</div> 3126<div class="paragraph"> 3127<p>The most important thing to note is that in B2, unlike other 3128build tools, the targets you declare do not correspond to specific 3129files. What you declare in a Jamfile is more like a “metatarget.” 3130Depending on the properties you specify on the command line, each 3131metatarget will produce a set of real targets corresponding to the 3132requested properties. It is quite possible that the same metatarget is 3133built several times with different properties, producing different 3134files.</p> 3135</div> 3136<div class="admonitionblock tip"> 3137<table> 3138<tr> 3139<td class="icon"> 3140<div class="title">☀</div> 3141</td> 3142<td class="content"> 3143This means that for B2, you cannot directly obtain a build 3144variant from a Jamfile. There could be several variants requested by the 3145user, and each target can be built with different properties. 3146</td> 3147</tr> 3148</table> 3149</div> 3150<div class="sect3"> 3151<h4 id="bbv2.overview.build_request"><a class="anchor" href="#bbv2.overview.build_request"></a>3.7.1. Build Request</h4> 3152<div class="paragraph"> 3153<p>The command line specifies which targets to build and with which 3154properties. For example:</p> 3155</div> 3156<div class="listingblock"> 3157<div class="content"> 3158<pre class="pygments highlight"><code data-lang="shell"><span></span>b2 app1 lib1//lib1 <span class="tok-nv">toolset</span><span class="tok-o">=</span>gcc <span class="tok-nv">variant</span><span class="tok-o">=</span>debug <span class="tok-nv">optimization</span><span class="tok-o">=</span>full</code></pre> 3159</div> 3160</div> 3161<div class="paragraph"> 3162<p>would build two targets, "app1" and "lib1//lib1" with the specified 3163properties. You can refer to any targets, using 3164<a href="#bbv2.reference.ids">target id</a> and specify arbitrary properties. 3165Some of the properties are very common, and for them the name of the 3166property can be omitted. For example, the above can be written as:</p> 3167</div> 3168<div class="listingblock"> 3169<div class="content"> 3170<pre class="pygments highlight"><code data-lang="shell"><span></span>b2 app1 lib1//lib1 gcc debug <span class="tok-nv">optimization</span><span class="tok-o">=</span>full</code></pre> 3171</div> 3172</div> 3173<div class="paragraph"> 3174<p>The complete syntax, which has some additional shortcuts, is described 3175in <a href="#bbv2.overview.invocation">the section called “Invocation”</a>.</p> 3176</div> 3177</div> 3178<div class="sect3"> 3179<h4 id="_building_a_main_target"><a class="anchor" href="#_building_a_main_target"></a>3.7.2. Building a main target</h4> 3180<div class="paragraph"> 3181<p>When you request, directly or indirectly, a build of a main target with 3182specific requirements, the following steps are done. Some brief 3183explanation is provided, and more details are given in 3184<a href="#bbv2.reference.buildprocess">the section called “Build process”</a>.</p> 3185</div> 3186<div class="olist arabic"> 3187<ol class="arabic"> 3188<li> 3189<p>Applying default build. If the default-build property of a target 3190specifies a value of a feature that is not present in the build request, 3191that value is added.</p> 3192</li> 3193<li> 3194<p>Selecting the main target alternative to use. For each alternative 3195we look how many properties are present both in alternative’s 3196requirements, and in build request. The alternative with largest number 3197of matching properties is selected.</p> 3198</li> 3199<li> 3200<p>Determining "common" properties. The build request is 3201<a href="#bbv2.reference.variants.proprefine">refined</a> with target’s 3202requirements. The conditional properties in requirements are handled as 3203well. Finally, default values of features are added.</p> 3204</li> 3205<li> 3206<p>Building targets referred by the sources list and dependency 3207properties. The list of sources and the properties can refer to other 3208target using <a href="#bbv2.reference.ids">target references</a>. For each 3209reference, we take all 3210<a href="#bbv2.reference.features.attributes.propagated">propagated</a> 3211properties, refine them by explicit properties specified in the target 3212reference, and pass the resulting properties as build request to the 3213other target.</p> 3214</li> 3215<li> 3216<p>Adding the usage requirements produced when building dependencies to 3217the "common" properties. When dependencies are built in the previous 3218step, they return both the set of created "real" targets, and usage 3219requirements. The usage requirements are added to the common properties 3220and the resulting property set will be used for building the current 3221target.</p> 3222</li> 3223<li> 3224<p>Building the target using generators. To convert the sources to the 3225desired type, B2 uses "generators" — objects that correspond 3226to tools like compilers and linkers. Each generator declares what type 3227of targets it can produce and what type of sources it requires. Using 3228this information, B2 determines which generators must be run to 3229produce a specific target from specific sources. When generators are 3230run, they return the "real" targets.</p> 3231</li> 3232<li> 3233<p>Computing the usage requirements to be returned. The conditional 3234properties in usage requirements are expanded and the result is 3235returned.</p> 3236</li> 3237</ol> 3238</div> 3239</div> 3240<div class="sect3"> 3241<h4 id="_building_a_project"><a class="anchor" href="#_building_a_project"></a>3.7.3. Building a Project</h4> 3242<div class="paragraph"> 3243<p>Often, a user builds a complete project, not just one main target. In 3244fact, invoking <code>b2</code> without arguments builds the project defined in the 3245current directory.</p> 3246</div> 3247<div class="paragraph"> 3248<p>When a project is built, the build request is passed without 3249modification to all main targets in that project. It’s is possible to 3250prevent implicit building of a target in a project with the <code>explicit</code> 3251rule:</p> 3252</div> 3253<div class="listingblock"> 3254<div class="content"> 3255<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-nb">explicit</span><span class="tok-w"> </span>hello_test<span class="tok-w"> </span>;<span class="tok-w"></span></code></pre> 3256</div> 3257</div> 3258<div class="paragraph"> 3259<p>would cause the <code>hello_test</code> target to be built only if explicitly 3260requested by the user or by some other target.</p> 3261</div> 3262<div class="paragraph"> 3263<p>The Jamfile for a project can include a number of <code>build-project</code> rule 3264calls that specify additional projects to be built.</p> 3265</div> 3266</div> 3267</div> 3268</div> 3269</div> 3270<div class="sect1"> 3271<h2 id="bbv2.tasks"><a class="anchor" href="#bbv2.tasks"></a>4. Common tasks</h2> 3272<div class="sectionbody"> 3273<div class="paragraph"> 3274<p>This section describes main targets types that B2 supports 3275out-of-the-box. Unless otherwise noted, all mentioned main target rules 3276have the common signature, described in 3277<a href="#bbv2.overview.targets">the section called “Declaring Targets”</a>.</p> 3278</div> 3279<div class="sect2"> 3280<h3 id="bbv2.tasks.programs"><a class="anchor" href="#bbv2.tasks.programs"></a>4.1. Programs</h3> 3281<div class="paragraph"> 3282<p>Programs are created using the <code>exe</code> rule, which follows the 3283<a href="#bbv2.main-target-rule-syntax">common syntax</a>. For example:</p> 3284</div> 3285<div class="listingblock"> 3286<div class="content"> 3287<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-nb">exe</span><span class="tok-w"> </span>hello<span class="tok-w"></span> 3288<span class="tok-w"> </span>:<span class="tok-w"> </span>hello.cpp<span class="tok-w"> </span>some_library.lib<span class="tok-w"> </span>/some_project//library<span class="tok-w"></span> 3289<span class="tok-w"> </span>:<span class="tok-w"> </span><span class="tok-na"><threading></span>multi<span class="tok-w"></span> 3290<span class="tok-w"> </span>;<span class="tok-w"></span></code></pre> 3291</div> 3292</div> 3293<div class="paragraph"> 3294<p>This will create an executable file from the sources—​in this case, 3295one C++ file, one library file present in the same directory, and 3296another library that is created by B2. Generally, sources can 3297include C and C++ files, object files and libraries. B2 will 3298automatically try to convert targets of other types.</p> 3299</div> 3300<div class="admonitionblock tip"> 3301<table> 3302<tr> 3303<td class="icon"> 3304<div class="title">☀</div> 3305</td> 3306<td class="content"> 3307On Windows, if an application uses shared libraries, and both the 3308application and the libraries are built using B2, it is not 3309possible to immediately run the application, because the <code>PATH</code> environment 3310variable should include the path to the libraries. It means you have to either 3311add the paths manually, or have the build place the application and the 3312libraries into the same directory. See 3313<a href="#bbv2.tasks.installing">the section called “Installing”</a>. 3314</td> 3315</tr> 3316</table> 3317</div> 3318</div> 3319<div class="sect2"> 3320<h3 id="bbv2.tasks.libraries"><a class="anchor" href="#bbv2.tasks.libraries"></a>4.2. Libraries</h3> 3321<div class="paragraph"> 3322<p>Library targets are created using the <code>lib</code> rule, which follows the 3323<a href="#bbv2.main-target-rule-syntax">common syntax</a>. For example:</p> 3324</div> 3325<div class="listingblock"> 3326<div class="content"> 3327<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-nb">lib</span><span class="tok-w"> </span>helpers<span class="tok-w"> </span>:<span class="tok-w"> </span>helpers.cpp<span class="tok-w"> </span>;<span class="tok-w"></span></code></pre> 3328</div> 3329</div> 3330<div class="paragraph"> 3331<p>This will define a library target named <code>helpers</code> built from the 3332<code>helpers.cpp</code> source file. It can be either a static library or a shared 3333library, depending on the value of the 3334<a href="#bbv2.builtin.features.link"><code><link></code></a> feature.</p> 3335</div> 3336<div class="paragraph"> 3337<p>Library targets can represent:</p> 3338</div> 3339<div class="ulist"> 3340<ul> 3341<li> 3342<p>Libraries that should be built from source, as in the example above.</p> 3343</li> 3344<li> 3345<p>Prebuilt libraries which already exist on the system. Such libraries 3346can be searched for by the tools using them (typically with the linker’s 3347<code>-l</code> option) or their paths can be known in advance by the build system.</p> 3348</li> 3349</ul> 3350</div> 3351<div class="paragraph"> 3352<p>The syntax for prebuilt libraries is given below:</p> 3353</div> 3354<div class="listingblock"> 3355<div class="content"> 3356<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-nb">lib</span><span class="tok-w"> </span>z<span class="tok-w"> </span>:<span class="tok-w"> </span>:<span class="tok-w"> </span><span class="tok-na"><name></span>z<span class="tok-w"> </span><span class="tok-na"><search></span>/home/ghost<span class="tok-w"> </span>;<span class="tok-w"></span> 3357<span class="tok-nb">lib</span><span class="tok-w"> </span>compress<span class="tok-w"> </span>:<span class="tok-w"> </span>:<span class="tok-w"> </span><span class="tok-na"><file></span>/opt/libs/compress.a<span class="tok-w"> </span>;<span class="tok-w"></span></code></pre> 3358</div> 3359</div> 3360<div class="paragraph"> 3361<p>The <code>name</code> property specifies the name of the library without the 3362standard prefixes and suffixes. For example, depending on the system, 3363<code>z</code> could refer to a file called <code>z.so</code>, <code>libz.a</code>, or <code>z.lib</code>, etc. The 3364<code>search</code> feature specifies paths in which to search for the library in 3365addition to the default compiler paths. <code>search</code> can be specified 3366several times or it can be omitted, in which case only the default 3367compiler paths will be searched. The <code>file</code> property specifies the file 3368location.</p> 3369</div> 3370<div class="paragraph"> 3371<p>The difference between using the <code>file</code> feature and using a combination 3372of the <code>name</code> and <code>search</code> features is that <code>file</code> is more precise.</p> 3373</div> 3374<div class="admonitionblock warning"> 3375<table> 3376<tr> 3377<td class="icon"> 3378<div class="title">⚠</div> 3379</td> 3380<td class="content"> 3381<div class="paragraph"> 3382<p>The value of the <code>search</code> feature is just added to the linker search 3383path. When linking to multiple libraries, the paths specified by 3384<code>search</code> are combined without regard to which <code>lib</code> target each path 3385came from. Thus, given</p> 3386</div> 3387<div class="listingblock"> 3388<div class="content"> 3389<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-nb">lib</span><span class="tok-w"> </span>a<span class="tok-w"> </span>:<span class="tok-w"> </span>:<span class="tok-w"> </span><span class="tok-na"><name></span>a<span class="tok-w"> </span><span class="tok-na"><search></span>/pool/release<span class="tok-w"> </span>;<span class="tok-w"></span> 3390<span class="tok-nb">lib</span><span class="tok-w"> </span>b<span class="tok-w"> </span>:<span class="tok-w"> </span>:<span class="tok-w"> </span><span class="tok-na"><name></span>b<span class="tok-w"> </span><span class="tok-na"><search></span>/pool/debug<span class="tok-w"> </span>;<span class="tok-w"></span></code></pre> 3391</div> 3392</div> 3393<div class="paragraph"> 3394<p>If /pool/release/a.so, /pool/release/b.so, /pool/debug/a.so, and 3395/pool/release/b.so all exist, the linker will probably take both <code>a</code> and 3396<code>b</code> from the same directory, instead of finding <code>a</code> in /pool/release and 3397<code>b</code> in /pool/debug. If you need to distinguish between multiple 3398libraries with the same name, it’s safer to use <code>file</code>.</p> 3399</div> 3400</td> 3401</tr> 3402</table> 3403</div> 3404<div class="paragraph"> 3405<p>For convenience, the following syntax is allowed:</p> 3406</div> 3407<div class="listingblock"> 3408<div class="content"> 3409<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-nb">lib</span><span class="tok-w"> </span>z<span class="tok-w"> </span>;<span class="tok-w"></span> 3410<span class="tok-nb">lib</span><span class="tok-w"> </span>gui<span class="tok-w"> </span>db<span class="tok-w"> </span>aux<span class="tok-w"> </span>;<span class="tok-w"></span></code></pre> 3411</div> 3412</div> 3413<div class="paragraph"> 3414<p>which has exactly the same effect as:</p> 3415</div> 3416<div class="listingblock"> 3417<div class="content"> 3418<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-nb">lib</span><span class="tok-w"> </span>z<span class="tok-w"> </span>:<span class="tok-w"> </span>:<span class="tok-w"> </span><span class="tok-na"><name></span>z<span class="tok-w"> </span>;<span class="tok-w"></span> 3419<span class="tok-nb">lib</span><span class="tok-w"> </span>gui<span class="tok-w"> </span>:<span class="tok-w"> </span>:<span class="tok-w"> </span><span class="tok-na"><name></span>gui<span class="tok-w"> </span>;<span class="tok-w"></span> 3420<span class="tok-nb">lib</span><span class="tok-w"> </span>db<span class="tok-w"> </span>:<span class="tok-w"> </span>:<span class="tok-w"> </span><span class="tok-na"><name></span>db<span class="tok-w"> </span>;<span class="tok-w"></span> 3421<span class="tok-nb">lib</span><span class="tok-w"> </span>aux<span class="tok-w"> </span>:<span class="tok-w"> </span>:<span class="tok-w"> </span><span class="tok-na"><name></span>aux<span class="tok-w"> </span>;<span class="tok-w"></span></code></pre> 3422</div> 3423</div> 3424<div class="paragraph"> 3425<p>When a library references another library you should put that other 3426library in its list of sources. This will do the right thing in all 3427cases. For portability, you should specify library dependencies even for 3428searched and prebuilt libraries, otherwise, static linking on Unix will 3429not work. For example:</p> 3430</div> 3431<div class="listingblock"> 3432<div class="content"> 3433<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-nb">lib</span><span class="tok-w"> </span>z<span class="tok-w"> </span>;<span class="tok-w"></span> 3434<span class="tok-nb">lib</span><span class="tok-w"> </span>png<span class="tok-w"> </span>:<span class="tok-w"> </span>z<span class="tok-w"> </span>:<span class="tok-w"> </span><span class="tok-na"><name></span>png<span class="tok-w"> </span>;<span class="tok-w"></span></code></pre> 3435</div> 3436</div> 3437<div class="admonitionblock note"> 3438<table> 3439<tr> 3440<td class="icon"> 3441<div class="title">ℹ</div> 3442</td> 3443<td class="content"> 3444<div class="paragraph"> 3445<p>When a library has a shared library as a source, or a static library has 3446another static library as a source then any target linking to the first 3447library with automatically link to its source library as well.</p> 3448</div> 3449<div class="paragraph"> 3450<p>On the other hand, when a shared library has a static library as a 3451source then the first library will be built so that it completely 3452includes the second one.</p> 3453</div> 3454<div class="paragraph"> 3455<p>If you do not want a shared library to include all the libraries 3456specified in its sources (especially statically linked ones), you would 3457need to use the following:</p> 3458</div> 3459<div class="listingblock"> 3460<div class="content"> 3461<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-nb">lib</span><span class="tok-w"> </span>b<span class="tok-w"> </span>:<span class="tok-w"> </span>a.cpp<span class="tok-w"> </span>;<span class="tok-w"></span> 3462<span class="tok-nb">lib</span><span class="tok-w"> </span>a<span class="tok-w"> </span>:<span class="tok-w"> </span>a.cpp<span class="tok-w"> </span>:<span class="tok-w"> </span><span class="tok-na"><use></span>b<span class="tok-w"> </span>:<span class="tok-w"> </span>:<span class="tok-w"> </span><span class="tok-na"><library></span>b<span class="tok-w"> </span>;<span class="tok-w"></span></code></pre> 3463</div> 3464</div> 3465<div class="paragraph"> 3466<p>This specifies that library <code>a</code> uses library <code>b</code>, and causes all 3467executables that link to <code>a</code> to link to <code>b</code> also. In this case, even for 3468shared linking, the <code>a</code> library will not refer to <code>b</code>.</p> 3469</div> 3470</td> 3471</tr> 3472</table> 3473</div> 3474<div class="paragraph"> 3475<p><a href="#bbv2.overview.targets">Usage requirements</a> are often very useful 3476for defining library targets. For example, imagine that you want you 3477build a <code>helpers</code> library and its interface is described in its 3478<code>helpers.hpp</code> header file located in the same directory as the 3479<code>helpers.cpp</code> source file. Then you could add the following to the 3480Jamfile located in that same directory:</p> 3481</div> 3482<div class="listingblock"> 3483<div class="content"> 3484<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-nb">lib</span><span class="tok-w"> </span>helpers<span class="tok-w"> </span>:<span class="tok-w"> </span>helpers.cpp<span class="tok-w"> </span>:<span class="tok-w"> </span>:<span class="tok-w"> </span>:<span class="tok-w"> </span><span class="tok-na"><include></span>.<span class="tok-w"> </span>;<span class="tok-w"></span></code></pre> 3485</div> 3486</div> 3487<div class="paragraph"> 3488<p>which would automatically add the directory where the target has been 3489defined (and where the library’s header file is located) to the 3490compiler’s include path for all targets using the <code>helpers</code> library. 3491This feature greatly simplifies Jamfiles.</p> 3492</div> 3493</div> 3494<div class="sect2"> 3495<h3 id="bbv2.tasks.alias"><a class="anchor" href="#bbv2.tasks.alias"></a>4.3. Alias</h3> 3496<div class="paragraph"> 3497<p>The <code>alias</code> rule gives an alternative name to a group of targets. For 3498example, to give the name <code>core</code> to a group of three other targets with 3499the following code:</p> 3500</div> 3501<div class="listingblock"> 3502<div class="content"> 3503<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-nb">alias</span><span class="tok-w"> </span>core<span class="tok-w"> </span>:<span class="tok-w"> </span>im<span class="tok-w"> </span>reader<span class="tok-w"> </span>writer<span class="tok-w"> </span>;<span class="tok-w"></span></code></pre> 3504</div> 3505</div> 3506<div class="paragraph"> 3507<p>Using <code>core</code> on the command line, or in the source list of any other 3508target is the same as explicitly using <code>im</code>, <code>reader</code>, and <code>writer</code>.</p> 3509</div> 3510<div class="paragraph"> 3511<p>Another use of the <code>alias</code> rule is to change build properties. For 3512example, if you want to link statically to the Boost Threads 3513library, you can write the following:</p> 3514</div> 3515<div class="listingblock"> 3516<div class="content"> 3517<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-nb">alias</span><span class="tok-w"> </span>threads<span class="tok-w"> </span>:<span class="tok-w"> </span>/boost/thread//boost_thread<span class="tok-w"> </span>:<span class="tok-w"> </span><span class="tok-na"><link></span>static<span class="tok-w"> </span>;<span class="tok-w"></span></code></pre> 3518</div> 3519</div> 3520<div class="paragraph"> 3521<p>and use only the <code>threads</code> alias in your Jamfiles.</p> 3522</div> 3523<div class="paragraph"> 3524<p>You can also specify usage requirements for the <code>alias</code> target. If you 3525write the following:</p> 3526</div> 3527<div class="listingblock"> 3528<div class="content"> 3529<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-nb">alias</span><span class="tok-w"> </span>header_only_library<span class="tok-w"> </span>:<span class="tok-w"> </span>:<span class="tok-w"> </span>:<span class="tok-w"> </span>:<span class="tok-w"> </span><span class="tok-na"><include></span>/usr/include/header_only_library<span class="tok-w"> </span>;<span class="tok-w"></span></code></pre> 3530</div> 3531</div> 3532<div class="paragraph"> 3533<p>then using <code>header_only_library</code> in sources will only add an include 3534path. Also note that when an alias has sources, their usage requirements 3535are propagated as well. For example:</p> 3536</div> 3537<div class="listingblock"> 3538<div class="content"> 3539<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-nb">lib</span><span class="tok-w"> </span>library1<span class="tok-w"> </span>:<span class="tok-w"> </span>library1.cpp<span class="tok-w"> </span>:<span class="tok-w"> </span>:<span class="tok-w"> </span>:<span class="tok-w"> </span><span class="tok-na"><include></span>/library/include1<span class="tok-w"> </span>;<span class="tok-w"></span> 3540<span class="tok-nb">lib</span><span class="tok-w"> </span>library2<span class="tok-w"> </span>:<span class="tok-w"> </span>library2.cpp<span class="tok-w"> </span>:<span class="tok-w"> </span>:<span class="tok-w"> </span>:<span class="tok-w"> </span><span class="tok-na"><include></span>/library/include2<span class="tok-w"> </span>;<span class="tok-w"></span> 3541<span class="tok-nb">alias</span><span class="tok-w"> </span>static_libraries<span class="tok-w"> </span>:<span class="tok-w"> </span>library1<span class="tok-w"> </span>library2<span class="tok-w"> </span>:<span class="tok-w"> </span><span class="tok-na"><link></span>static<span class="tok-w"> </span>;<span class="tok-w"></span> 3542<span class="tok-nb">exe</span><span class="tok-w"> </span>main<span class="tok-w"> </span>:<span class="tok-w"> </span>main.cpp<span class="tok-w"> </span>static_libraries<span class="tok-w"> </span>;<span class="tok-w"></span></code></pre> 3543</div> 3544</div> 3545<div class="paragraph"> 3546<p>will compile <code>main.cpp</code> with additional includes required for using the 3547specified static libraries.</p> 3548</div> 3549</div> 3550<div class="sect2"> 3551<h3 id="bbv2.tasks.installing"><a class="anchor" href="#bbv2.tasks.installing"></a>4.4. Installing</h3> 3552<div class="paragraph"> 3553<p>This section describes various ways to install built targets and 3554arbitrary files.</p> 3555</div> 3556<div class="sect3"> 3557<h4 id="_basic_install"><a class="anchor" href="#_basic_install"></a>4.4.1. Basic install</h4> 3558<div class="paragraph"> 3559<p>For installing a built target you should use the <code>install</code> rule, which 3560follows the <a href="#bbv2.main-target-rule-syntax">common syntax</a>. For 3561example:</p> 3562</div> 3563<div class="listingblock"> 3564<div class="content"> 3565<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-nb">install</span><span class="tok-w"> </span>dist<span class="tok-w"> </span>:<span class="tok-w"> </span>hello<span class="tok-w"> </span>helpers<span class="tok-w"> </span>;<span class="tok-w"></span></code></pre> 3566</div> 3567</div> 3568<div class="paragraph"> 3569<p>will cause the targets <code>hello</code> and <code>helpers</code> to be moved to the <code>dist</code> 3570directory, relative to the Jamfile’s directory. The directory can be 3571changed using the <code>location</code> property:</p> 3572</div> 3573<div class="listingblock"> 3574<div class="content"> 3575<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-nb">install</span><span class="tok-w"> </span>dist<span class="tok-w"> </span>:<span class="tok-w"> </span>hello<span class="tok-w"> </span>helpers<span class="tok-w"> </span>:<span class="tok-w"> </span><span class="tok-na"><location></span>/usr/bin<span class="tok-w"> </span>;<span class="tok-w"></span></code></pre> 3576</div> 3577</div> 3578<div class="paragraph"> 3579<p>While you can achieve the same effect by changing the target name to 3580<code>/usr/bin</code>, using the <code>location</code> property is better as it allows you to 3581use a mnemonic target name.</p> 3582</div> 3583<div class="paragraph"> 3584<p>The <code>location</code> property is especially handy when the location is not 3585fixed, but depends on the build variant or environment variables:</p> 3586</div> 3587<div class="listingblock"> 3588<div class="content"> 3589<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-nb">install</span><span class="tok-w"> </span>dist<span class="tok-w"> </span>:<span class="tok-w"> </span>hello<span class="tok-w"> </span>helpers<span class="tok-w"> </span>:<span class="tok-w"></span> 3590<span class="tok-w"> </span><span class="tok-na"><variant></span>release:<span class="tok-na"><location></span>dist/release<span class="tok-w"></span> 3591<span class="tok-w"> </span><span class="tok-na"><variant></span>debug:<span class="tok-na"><location></span>dist/debug<span class="tok-w"> </span>;<span class="tok-w"></span> 3592<span class="tok-nb">install</span><span class="tok-w"> </span>dist2<span class="tok-w"> </span>:<span class="tok-w"> </span>hello<span class="tok-w"> </span>helpers<span class="tok-w"> </span>:<span class="tok-w"> </span><span class="tok-na"><location></span><span class="tok-si">$(DIST)</span><span class="tok-w"> </span>;<span class="tok-w"></span></code></pre> 3593</div> 3594</div> 3595<div class="paragraph"> 3596<p>See also <a href="#bbv2.reference.variants.propcond">conditional properties</a> 3597and <a href="#bbv2.faq.envar">environment variables</a></p> 3598</div> 3599</div> 3600<div class="sect3"> 3601<h4 id="_installing_with_all_dependencies"><a class="anchor" href="#_installing_with_all_dependencies"></a>4.4.2. Installing with all dependencies</h4> 3602<div class="paragraph"> 3603<p>Specifying the names of all libraries to install can be boring. The 3604<code>install</code> allows you to specify only the top-level executable targets to 3605install, and automatically install all dependencies:</p> 3606</div> 3607<div class="listingblock"> 3608<div class="content"> 3609<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-nb">install</span><span class="tok-w"> </span>dist<span class="tok-w"> </span>:<span class="tok-w"> </span>hello<span class="tok-w"> </span>:<span class="tok-w"></span> 3610<span class="tok-w"> </span><span class="tok-na"><install-dependencies></span>on<span class="tok-w"> </span><span class="tok-na"><install-type></span>EXE<span class="tok-w"></span> 3611<span class="tok-w"> </span><span class="tok-na"><install-type></span>LIB<span class="tok-w"></span> 3612<span class="tok-w"> </span>;<span class="tok-w"></span></code></pre> 3613</div> 3614</div> 3615<div class="paragraph"> 3616<p>will find all targets that <code>hello</code> depends on, and install all of those 3617which are either executables or libraries. More specifically, for each 3618target, other targets that were specified as sources or as dependency 3619properties, will be recursively found. One exception is that targets 3620referred with the <a href="#bbv2.builtin.features.use"><code>use</code></a> feature are not 3621considered, as that feature is typically used to refer to header-only 3622libraries. If the set of target types is specified, only targets of that 3623type will be installed, otherwise, all found target will be installed.</p> 3624</div> 3625</div> 3626<div class="sect3"> 3627<h4 id="_preserving_directory_hierarchy"><a class="anchor" href="#_preserving_directory_hierarchy"></a>4.4.3. Preserving Directory Hierarchy</h4> 3628<div class="paragraph"> 3629<p>By default, the <code>install</code> rule will strip paths from its sources. So, if 3630sources include <code>a/b/c.hpp</code>, the <code>a/b</code> part will be ignored. To make the 3631<code>install</code> rule preserve the directory hierarchy you need to use the 3632<code><install-source-root></code> feature to specify the root of the hierarchy you 3633are installing. Relative paths from that root will be preserved. For 3634example, if you write:</p> 3635</div> 3636<div class="listingblock"> 3637<div class="content"> 3638<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-nb">install</span><span class="tok-w"> </span>headers<span class="tok-w"></span> 3639<span class="tok-w"> </span>:<span class="tok-w"> </span>a/b/c.h<span class="tok-w"></span> 3640<span class="tok-w"> </span>:<span class="tok-w"> </span><span class="tok-na"><location></span>/tmp<span class="tok-w"> </span><span class="tok-na"><install-source-root></span>a<span class="tok-w"></span> 3641<span class="tok-w"> </span>;<span class="tok-w"></span></code></pre> 3642</div> 3643</div> 3644<div class="paragraph"> 3645<p>the a file named <code>/tmp/b/c.h</code> will be created.</p> 3646</div> 3647<div class="paragraph"> 3648<p>The <a href="#bbv2.reference.glob-tree"><code>glob-tree</code></a> rule can be used to find 3649all files below a given directory, making it easy to install an entire 3650directory tree.</p> 3651</div> 3652</div> 3653<div class="sect3"> 3654<h4 id="_installing_into_several_directories"><a class="anchor" href="#_installing_into_several_directories"></a>4.4.4. Installing into Several Directories</h4> 3655<div class="paragraph"> 3656<p>The <a href="#bbv2.tasks.alias"><code>alias</code></a> rule can be used when targets need 3657to be installed into several directories:</p> 3658</div> 3659<div class="listingblock"> 3660<div class="content"> 3661<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-nb">alias</span><span class="tok-w"> </span><span class="tok-nb">install</span><span class="tok-w"> </span>:<span class="tok-w"> </span><span class="tok-nb">install</span>-bin<span class="tok-w"> </span><span class="tok-nb">install</span>-lib<span class="tok-w"> </span>;<span class="tok-w"></span> 3662<span class="tok-nb">install</span><span class="tok-w"> </span><span class="tok-nb">install</span>-bin<span class="tok-w"> </span>:<span class="tok-w"> </span>applications<span class="tok-w"> </span>:<span class="tok-w"> </span>/usr/bin<span class="tok-w"> </span>;<span class="tok-w"></span> 3663<span class="tok-nb">install</span><span class="tok-w"> </span><span class="tok-nb">install</span>-lib<span class="tok-w"> </span>:<span class="tok-w"> </span>helper<span class="tok-w"> </span>:<span class="tok-w"> </span>/usr/lib<span class="tok-w"> </span>;<span class="tok-w"></span></code></pre> 3664</div> 3665</div> 3666<div class="paragraph"> 3667<p>Because the <code>install</code> rule just copies targets, most free features 3668<sup class="footnote">[<a id="_footnoteref_3" class="footnote" href="#_footnotedef_3" title="View footnote.">3</a>]</sup> 3669have no effect when used in requirements of the <code>install</code> rule. The only two 3670that matter are 3671<a href="#bbv2.builtin.features.dependency"><code>dependency</code></a> and, on Unix, 3672<a href="#bbv2.builtin.features.dll-path"><code>dll-path</code></a>.</p> 3673</div> 3674<div class="admonitionblock note"> 3675<table> 3676<tr> 3677<td class="icon"> 3678<div class="title">ℹ</div> 3679</td> 3680<td class="content"> 3681(Unix specific) On Unix, executables built using B2 typically 3682contain the list of paths to all used shared libraries. For installing, 3683this is not desired, so B2 relinks the executable with an empty 3684list of paths. You can also specify additional paths for installed 3685executables using the <code>dll-path</code> feature. 3686</td> 3687</tr> 3688</table> 3689</div> 3690</div> 3691</div> 3692<div class="sect2"> 3693<h3 id="bbv2.builtins.testing"><a class="anchor" href="#bbv2.builtins.testing"></a>4.5. Testing</h3> 3694<div class="paragraph"> 3695<p>B2 has convenient support for running unit tests. The simplest 3696way is the <code>unit-test</code> rule, which follows the 3697<a href="#bbv2.main-target-rule-syntax">common syntax</a>. For example:</p> 3698</div> 3699<div class="listingblock"> 3700<div class="content"> 3701<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-nb">unit-test</span><span class="tok-w"> </span>helpers_test<span class="tok-w"> </span>:<span class="tok-w"> </span>helpers_test.cpp<span class="tok-w"> </span>helpers<span class="tok-w"> </span>;<span class="tok-w"></span></code></pre> 3702</div> 3703</div> 3704<div class="paragraph"> 3705<p>The <code>unit-test</code> rule behaves like the <a href="#bbv2.tasks.programs">exe</a> 3706rule, but after the executable is created it is also run. If the 3707executable returns an error code, the build system will also return an 3708error and will try running the executable on the next invocation until 3709it runs successfully. This behavior ensures that you can not miss a 3710unit test failure.</p> 3711</div> 3712<div class="paragraph"> 3713<p>There are few specialized testing rules, listed below:</p> 3714</div> 3715<div class="listingblock"> 3716<div class="content"> 3717<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-k">rule</span><span class="tok-w"> </span><span class="tok-nf">compile</span><span class="tok-w"> </span><span class="tok-p">(</span><span class="tok-w"> </span><span class="tok-nv">sources</span><span class="tok-w"> </span><span class="tok-p">:</span><span class="tok-w"> </span><span class="tok-nv">requirements</span><span class="tok-w"> </span><span class="tok-p">*</span><span class="tok-w"> </span><span class="tok-p">:</span><span class="tok-w"> </span><span class="tok-nv">target-name</span><span class="tok-w"> </span><span class="tok-p">?</span><span class="tok-w"> </span><span class="tok-p">)</span><span class="tok-w"></span> 3718<span class="tok-k">rule</span><span class="tok-w"> </span><span class="tok-nf">compile-fail</span><span class="tok-w"> </span><span class="tok-p">(</span><span class="tok-w"> </span><span class="tok-nv">sources</span><span class="tok-w"> </span><span class="tok-p">:</span><span class="tok-w"> </span><span class="tok-nv">requirements</span><span class="tok-w"> </span><span class="tok-p">*</span><span class="tok-w"> </span><span class="tok-p">:</span><span class="tok-w"> </span><span class="tok-nv">target-name</span><span class="tok-w"> </span><span class="tok-p">?</span><span class="tok-w"> </span><span class="tok-p">)</span><span class="tok-w"></span> 3719<span class="tok-k">rule</span><span class="tok-w"> </span><span class="tok-nf">link</span><span class="tok-w"> </span><span class="tok-p">(</span><span class="tok-w"> </span><span class="tok-nv">sources</span><span class="tok-w"> </span><span class="tok-p">+</span><span class="tok-w"> </span><span class="tok-p">:</span><span class="tok-w"> </span><span class="tok-nv">requirements</span><span class="tok-w"> </span><span class="tok-p">*</span><span class="tok-w"> </span><span class="tok-p">:</span><span class="tok-w"> </span><span class="tok-nv">target-name</span><span class="tok-w"> </span><span class="tok-p">?</span><span class="tok-w"> </span><span class="tok-p">)</span><span class="tok-w"></span> 3720<span class="tok-k">rule</span><span class="tok-w"> </span><span class="tok-nf">link-fail</span><span class="tok-w"> </span><span class="tok-p">(</span><span class="tok-w"> </span><span class="tok-nv">sources</span><span class="tok-w"> </span><span class="tok-p">+</span><span class="tok-w"> </span><span class="tok-p">:</span><span class="tok-w"> </span><span class="tok-nv">requirements</span><span class="tok-w"> </span><span class="tok-p">*</span><span class="tok-w"> </span><span class="tok-p">:</span><span class="tok-w"> </span><span class="tok-nv">target-name</span><span class="tok-w"> </span><span class="tok-p">?</span><span class="tok-w"> </span><span class="tok-p">)</span><span class="tok-w"></span></code></pre> 3721</div> 3722</div> 3723<div class="paragraph"> 3724<p>They are given a list of sources and requirements. If the target name is 3725not provided, the name of the first source file is used instead. The 3726<code>compile*</code> tests try to compile the passed source. The <code>link*</code> rules try 3727to compile and link an application from all the passed sources. The 3728<code>compile</code> and <code>link</code> rules expect that compilation/linking succeeds. The 3729<code>compile-fail</code> and <code>link-fail</code> rules expect that the 3730compilation/linking fails.</p> 3731</div> 3732<div class="paragraph"> 3733<p>There are two specialized rules for running executables, which are more 3734powerful than the <code>unit-test</code> rule. The <code>run</code> rule has the following 3735signature:</p> 3736</div> 3737<div class="listingblock"> 3738<div class="content"> 3739<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-k">rule</span><span class="tok-w"> </span><span class="tok-nf">run</span><span class="tok-w"> </span><span class="tok-p">(</span><span class="tok-w"> </span><span class="tok-nv">sources</span><span class="tok-w"> </span><span class="tok-p">+</span><span class="tok-w"> </span><span class="tok-p">:</span><span class="tok-w"> </span><span class="tok-nv">args</span><span class="tok-w"> </span><span class="tok-p">*</span><span class="tok-w"> </span><span class="tok-p">:</span><span class="tok-w"> </span><span class="tok-nv">input-files</span><span class="tok-w"> </span><span class="tok-p">*</span><span class="tok-w"> </span><span class="tok-p">:</span><span class="tok-w"> </span><span class="tok-nv">requirements</span><span class="tok-w"> </span><span class="tok-p">*</span><span class="tok-w"> </span><span class="tok-p">:</span><span class="tok-w"> </span><span class="tok-nv">target-name</span><span class="tok-w"> </span><span class="tok-p">?</span><span class="tok-w"></span> 3740<span class="tok-w"> </span><span class="tok-p">:</span><span class="tok-w"> </span><span class="tok-nv">default-build</span><span class="tok-w"> </span><span class="tok-p">*</span><span class="tok-w"> </span><span class="tok-p">)</span><span class="tok-w"></span></code></pre> 3741</div> 3742</div> 3743<div class="paragraph"> 3744<p>The rule builds application from the provided sources and runs it, 3745passing <code>args</code> and <code>input-files</code> as command-line arguments. The <code>args</code> 3746parameter is passed verbatim and the values of the <code>input-files</code> 3747parameter are treated as paths relative to containing Jamfile, and are 3748adjusted if <code>b2</code> is invoked from a different directory. The <code>run-fail</code> 3749rule is identical to the <code>run</code> rule, except that it expects that the run 3750fails.</p> 3751</div> 3752<div class="paragraph"> 3753<p>All rules described in this section, if executed successfully, create a 3754special manifest file to indicate that the test passed. For the 3755<code>unit-test</code> rule the files is named <code>target-name.passed</code> and for the other 3756rules it is called <code>target-name.test</code>. The <code>run*</code> rules also capture all 3757output from the program, and store it in a file named <code>target-name.output</code>.</p> 3758</div> 3759<div class="paragraph"> 3760<p>If the <code>preserve-test-targets</code> feature has the 3761value <code>off</code>, then <code>run</code> and the <code>run-fail</code> rules will remove the 3762executable after running it. This somewhat decreases disk space 3763requirements for continuous testing environments. The default value of 3764<code>preserve-test-targets</code> feature is <code>on</code>.</p> 3765</div> 3766<div class="paragraph"> 3767<p>It is possible to print the list of all test targets (except for 3768<code>unit-test</code>) declared in your project, by passing the <code>--dump-tests</code> 3769command-line option. The output will consist of lines of the form:</p> 3770</div> 3771<div class="listingblock"> 3772<div class="content"> 3773<pre class="pygments highlight"><code data-lang="jam"><span></span>boost-test(test-type)<span class="tok-w"> </span>path<span class="tok-w"> </span>:<span class="tok-w"> </span>sources<span class="tok-w"></span></code></pre> 3774</div> 3775</div> 3776<div class="paragraph"> 3777<p>It is possible to process the list of tests, B2 output and the 3778presence/absence of the <code>*.test</code> files created when test passes into 3779human-readable status table of tests. Such processing utilities are not 3780included in B2.</p> 3781</div> 3782<div class="paragraph"> 3783<p>The following features adjust behavior of the testing metatargets.</p> 3784</div> 3785<div class="dlist"> 3786<dl> 3787<dt class="hdlist1"><code>testing.arg</code></dt> 3788<dd> 3789<p>Defines an argument to be passed to the target when it is executed 3790before the list of input files.</p> 3791<div class="listingblock"> 3792<div class="content"> 3793<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-nb">unit-test</span><span class="tok-w"> </span>helpers_test<span class="tok-w"></span> 3794<span class="tok-w"> </span>:<span class="tok-w"> </span>helpers_test.cpp<span class="tok-w"> </span>helpers<span class="tok-w"></span> 3795<span class="tok-w"> </span>:<span class="tok-w"> </span><span class="tok-na"><testing.arg></span>"--foo<span class="tok-w"> </span>bar"<span class="tok-w"></span> 3796<span class="tok-w"> </span>;<span class="tok-w"></span></code></pre> 3797</div> 3798</div> 3799</dd> 3800<dt class="hdlist1"><code>testing.input-file</code></dt> 3801<dd> 3802<p>Specifies a file to be passed to the executable on the command line 3803after the arguments. All files must be specified in alphabetical order 3804due to constraints in the current implementation.</p> 3805</dd> 3806<dt class="hdlist1"><code>testing.launcher</code></dt> 3807<dd> 3808<p>By default, the executable is run directly. Sometimes, it is desirable 3809to run the executable using some helper command. You should use this 3810property to specify the name of the helper command. For example, if 3811you write:</p> 3812<div class="listingblock"> 3813<div class="content"> 3814<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-nb">unit-test</span><span class="tok-w"> </span>helpers_test<span class="tok-w"></span> 3815<span class="tok-w"> </span>:<span class="tok-w"> </span>helpers_test.cpp<span class="tok-w"> </span>helpers<span class="tok-w"></span> 3816<span class="tok-w"> </span>:<span class="tok-w"> </span><span class="tok-na"><testing.launcher></span>valgrind<span class="tok-w"></span> 3817<span class="tok-w"> </span>;<span class="tok-w"></span></code></pre> 3818</div> 3819</div> 3820<div class="paragraph"> 3821<p>The command used to run the executable will be:</p> 3822</div> 3823<div class="listingblock"> 3824<div class="content"> 3825<pre class="pygments highlight"><code data-lang="shell"><span></span>valgrind bin/<span class="tok-nv">$toolset</span>/debug/helpers_test</code></pre> 3826</div> 3827</div> 3828</dd> 3829<dt class="hdlist1"><code>test-info</code></dt> 3830<dd> 3831<p>A description of the test. This is displayed as part of the 3832<code>--dump-tests</code> command-line option.</p> 3833</dd> 3834</dl> 3835</div> 3836</div> 3837<div class="sect2"> 3838<h3 id="bbv2.builtins.raw"><a class="anchor" href="#bbv2.builtins.raw"></a>4.6. Custom commands</h3> 3839<div class="paragraph"> 3840<p>For most main target rules, B2 automatically figures out the 3841commands to run. When you want to use new file types or support new 3842tools, one approach is to extend B2 to support them smoothly, 3843as documented in <a href="#bbv2.extender">Extender Manual</a>. However, if the new 3844tool is only used in a single place, it might be easier just to specify the 3845commands to run explicitly.</p> 3846</div> 3847<div class="paragraph"> 3848<p>Three main target rules can be used for that. The <code>make</code> rule allows you to 3849construct a single file from any number of source file, by running a command 3850you specify. The <code>notfile</code> rule allows you to run an arbitrary command, 3851without creating any files. And finally, the <code>generate</code> rule allows you to 3852describe a transformation using B2’s virtual targets. This is 3853higher-level than the file names that the <code>make</code> rule operates with and 3854allows you to create more than one target, create differently named targets 3855depending on properties, or use more than one tool.</p> 3856</div> 3857<div class="paragraph"> 3858<p>The <code>make</code> rule is used when you want to create one file from a number 3859of sources using some specific command. The <code>notfile</code> is used to 3860unconditionally run a command.</p> 3861</div> 3862<div class="paragraph"> 3863<p>Suppose you want to create the file <code>file.out</code> from the file <code>file.in</code> 3864by running the command <code>in2out</code>. Here is how you would do this in B2:</p> 3865</div> 3866<div class="listingblock"> 3867<div class="content"> 3868<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-nb">make</span><span class="tok-w"> </span>file.out<span class="tok-w"> </span>:<span class="tok-w"> </span>file.in<span class="tok-w"> </span>:<span class="tok-w"> </span>@in2out<span class="tok-w"> </span>;<span class="tok-w"></span> 3869<span class="tok-k">actions</span><span class="tok-w"> </span><span class="tok-nf">in2out</span><span class="tok-w"></span> 3870{<span class="tok-sh"></span> 3871<span class="tok-sh"> in2out </span><span class="tok-si">$(<)</span><span class="tok-sh"> </span><span class="tok-si">$(>)</span><span class="tok-sh"></span> 3872<span class="tok-p">}</span><span class="tok-w"></span></code></pre> 3873</div> 3874</div> 3875<div class="paragraph"> 3876<p>If you run <code>b2</code> and <code>file.out</code> does not exist, B2 will run the 3877<code>in2out</code> command to create that file. For more details on specifying 3878actions, see 3879<a href="#bbv2.overview.jam_language.actions">the section called “Boost.Jam Language”</a>.</p> 3880</div> 3881<div class="paragraph"> 3882<p>It could be that you just want to run some command unconditionally, and 3883that command does not create any specific files. For that you can use 3884the <code>notfile</code> rule. For example:</p> 3885</div> 3886<div class="listingblock"> 3887<div class="content"> 3888<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-nb">notfile</span><span class="tok-w"> </span>echo_something<span class="tok-w"> </span>:<span class="tok-w"> </span>@echo<span class="tok-w"> </span>;<span class="tok-w"></span> 3889<span class="tok-k">actions</span><span class="tok-w"> </span><span class="tok-nf">echo</span><span class="tok-w"></span> 3890{<span class="tok-sh"></span> 3891<span class="tok-sh"> echo "something"</span> 3892<span class="tok-p">}</span><span class="tok-w"></span></code></pre> 3893</div> 3894</div> 3895<div class="paragraph"> 3896<p>The only difference from the <code>make</code> rule is that the name of the target 3897is not considered a name of a file, so B2 will unconditionally 3898run the action.</p> 3899</div> 3900<div class="paragraph"> 3901<p>The <code>generate</code> rule is used when you want to express transformations 3902using B2’s virtual targets, as opposed to just filenames. The 3903<code>generate</code> rule has the standard main target rule signature, but you are 3904required to specify the <code>generating-rule</code> property. The value of the 3905property should be in the form <code>@<em>rule-name</em></code>, the named rule should have the 3906following signature:</p> 3907</div> 3908<div class="listingblock"> 3909<div class="content"> 3910<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-k">rule</span><span class="tok-w"> </span><span class="tok-nf">generating-rule</span><span class="tok-w"> </span><span class="tok-p">(</span><span class="tok-w"> </span><span class="tok-nv">project</span><span class="tok-w"> </span><span class="tok-nv">name</span><span class="tok-w"> </span><span class="tok-p">:</span><span class="tok-w"> </span><span class="tok-nv">property-set</span><span class="tok-w"> </span><span class="tok-p">:</span><span class="tok-w"> </span><span class="tok-nv">sources</span><span class="tok-w"> </span><span class="tok-p">*</span><span class="tok-w"> </span><span class="tok-p">)</span><span class="tok-w"></span></code></pre> 3911</div> 3912</div> 3913<div class="paragraph"> 3914<p>and will be called with an instance of the <code>project-target</code> class, the 3915name of the main target, an instance of the <code>property-set</code> class 3916containing build properties, and the list of instances of the 3917<code>virtual-target</code> class corresponding to sources. The rule must return a 3918list of <code>virtual-target</code> instances. The interface of the 3919<code>virtual-target</code> class can be learned by looking at the 3920<code>build/virtual-target.jam</code> file. The <code>generate</code> example contained in the 3921B2 distribution illustrates how the <code>generate</code> rule can be 3922used.</p> 3923</div> 3924</div> 3925<div class="sect2"> 3926<h3 id="bbv2.reference.precompiled_headers"><a class="anchor" href="#bbv2.reference.precompiled_headers"></a>4.7. Precompiled Headers</h3> 3927<div class="paragraph"> 3928<p>Precompiled headers is a mechanism to speed up compilation by creating a 3929partially processed version of some header files, and then using that 3930version during compilations rather then repeatedly parsing the original 3931headers. B2 supports precompiled headers with gcc and msvc 3932toolsets.</p> 3933</div> 3934<div class="paragraph"> 3935<p>To use precompiled headers, follow the following steps:</p> 3936</div> 3937<div class="olist arabic"> 3938<ol class="arabic"> 3939<li> 3940<p>Create a header that includes headers used by your project that you 3941want precompiled. It is better to include only headers that are 3942sufficiently stable — like headers from the compiler and external 3943libraries. Please wrap the header in <code>#ifdef BOOST_BUILD_PCH_ENABLED</code>, so 3944that the potentially expensive inclusion of headers is not done when PCH is 3945not enabled. Include the new header at the top of your source files.</p> 3946</li> 3947<li> 3948<p>Declare a new B2 target for the precompiled header and add 3949that precompiled header to the sources of the target whose compilation 3950you want to speed up:</p> 3951<div class="listingblock"> 3952<div class="content"> 3953<pre class="pygments highlight"><code data-lang="jam"><span></span>cpp-pch<span class="tok-w"> </span>pch<span class="tok-w"> </span>:<span class="tok-w"> </span>pch.hpp<span class="tok-w"> </span>;<span class="tok-w"></span> 3954<span class="tok-nb">exe</span><span class="tok-w"> </span>main<span class="tok-w"> </span>:<span class="tok-w"> </span>main.cpp<span class="tok-w"> </span>pch<span class="tok-w"> </span>;<span class="tok-w"></span></code></pre> 3955</div> 3956</div> 3957<div class="paragraph"> 3958<p>You can use the <code>c-pch</code> rule if you want to use the precompiled header 3959in C programs.</p> 3960</div> 3961</li> 3962</ol> 3963</div> 3964<div class="paragraph"> 3965<p>The <code>pch</code> example in B2 distribution can be used as reference.</p> 3966</div> 3967<div class="paragraph"> 3968<p>Please note the following:</p> 3969</div> 3970<div class="ulist"> 3971<ul> 3972<li> 3973<p>The inclusion of the precompiled header must be the first thing in a 3974source file, before any code or preprocessor directives.</p> 3975</li> 3976<li> 3977<p>The build properties used to compile the source files and the 3978precompiled header must be the same. Consider using project requirements 3979to assure this.</p> 3980</li> 3981<li> 3982<p>Precompiled headers must be used purely as a way to improve 3983compilation time, not to save the number of <code>#include</code> statements. If a 3984source file needs to include some header, explicitly include it in the 3985source file, even if the same header is included from the precompiled 3986header. This makes sure that your project will build even if precompiled 3987headers are not supported.</p> 3988</li> 3989<li> 3990<p>Prior to version 4.2, the gcc compiler did not allow anonymous 3991namespaces in precompiled headers, which limits their utility. See the 3992<a href="http://gcc.gnu.org/bugzilla/show_bug.cgi?id=29085">bug report</a> for 3993details.</p> 3994</li> 3995</ul> 3996</div> 3997</div> 3998<div class="sect2"> 3999<h3 id="bbv2.reference.generated_headers"><a class="anchor" href="#bbv2.reference.generated_headers"></a>4.8. Generated headers</h3> 4000<div class="paragraph"> 4001<p>Usually, B2 handles implicit dependencies completely 4002automatically. For example, for C++ files, all <code>#include</code> statements are 4003found and handled. The only aspect where user help might be needed is 4004implicit dependency on generated files.</p> 4005</div> 4006<div class="paragraph"> 4007<p>By default, B2 handles such dependencies within one main 4008target. For example, assume that main target "app" has two sources, 4009"app.cpp" and "parser.y". The latter source is converted into "parser.c" 4010and "parser.h". Then, if "app.cpp" includes "parser.h", B2 will 4011detect this dependency. Moreover, since "parser.h" will be generated 4012into a build directory, the path to that directory will automatically be 4013added to the include path.</p> 4014</div> 4015<div class="paragraph"> 4016<p>Making this mechanism work across main target boundaries is possible, 4017but imposes certain overhead. For that reason, if there is implicit 4018dependency on files from other main targets, the <code><implicit-dependency></code> 4019feature must be used, for example:</p> 4020</div> 4021<div class="listingblock"> 4022<div class="content"> 4023<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-nb">lib</span><span class="tok-w"> </span>parser<span class="tok-w"> </span>:<span class="tok-w"> </span>parser.y<span class="tok-w"> </span>;<span class="tok-w"></span> 4024<span class="tok-nb">exe</span><span class="tok-w"> </span>app<span class="tok-w"> </span>:<span class="tok-w"> </span>app.cpp<span class="tok-w"> </span>:<span class="tok-w"> </span><span class="tok-na"><implicit-dependency></span>parser<span class="tok-w"> </span>;<span class="tok-w"></span></code></pre> 4025</div> 4026</div> 4027<div class="paragraph"> 4028<p>The above example tells the build system that when scanning all sources 4029of "app" for implicit-dependencies, it should consider targets from 4030"parser" as potential dependencies.</p> 4031</div> 4032</div> 4033<div class="sect2"> 4034<h3 id="bbv2.tasks.crosscompile"><a class="anchor" href="#bbv2.tasks.crosscompile"></a>4.9. Cross-compilation</h3> 4035<div class="paragraph"> 4036<p>B2 supports cross compilation with the gcc and msvc toolsets.</p> 4037</div> 4038<div class="paragraph"> 4039<p>When using gcc, you first need to specify your cross compiler in 4040<code>user-config.jam</code> (see 4041<a href="#bbv2.overview.configuration">the section called “Configuration”</a>), for 4042example:</p> 4043</div> 4044<div class="listingblock"> 4045<div class="content"> 4046<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-nb">using</span><span class="tok-w"> </span>gcc<span class="tok-w"> </span>:<span class="tok-w"> </span>arm<span class="tok-w"> </span>:<span class="tok-w"> </span>arm-none-linux-gnueabi-g++<span class="tok-w"> </span>;<span class="tok-w"></span></code></pre> 4047</div> 4048</div> 4049<div class="paragraph"> 4050<p>After that, if the host and target os are the same, for example Linux, 4051you can just request that this compiler version be used:</p> 4052</div> 4053<div class="listingblock"> 4054<div class="content"> 4055<pre class="pygments highlight"><code data-lang="shell"><span></span>b2 <span class="tok-nv">toolset</span><span class="tok-o">=</span>gcc-arm</code></pre> 4056</div> 4057</div> 4058<div class="paragraph"> 4059<p>If you want to target a different operating system from the host, you 4060need to additionally specify the value for the <code>target-os</code> feature, for 4061example:</p> 4062</div> 4063<div class="listingblock"> 4064<div class="content"> 4065<pre class="pygments highlight"><code data-lang="bat"><span></span># On windows box 4066b2 toolset=gcc-arm target-os=linux 4067# On Linux box 4068b2 toolset=gcc-mingw target-os=windows</code></pre> 4069</div> 4070</div> 4071<div class="paragraph"> 4072<p>For the complete list of allowed operating system names, please see the 4073documentation for <a href="#bbv2.builtin.features.target-os">target-os 4074feature</a>.</p> 4075</div> 4076<div class="paragraph"> 4077<p>When using the msvc compiler, it’s only possible to cross-compile to a 407864-bit system on a 32-bit host. Please see 4079<a href="#bbv2.reference.tools.compiler.msvc.64">the section called “64-bit support”</a> 4080for details.</p> 4081</div> 4082</div> 4083<div class="sect2"> 4084<h3 id="bbv2.tasks.packagemanagers"><a class="anchor" href="#bbv2.tasks.packagemanagers"></a>4.10. Package Managers</h3> 4085<div class="paragraph"> 4086<p>B2 support automatic, or manual, loading of generated build files 4087from package managers. For example using the Conan package manager which 4088generates <code>conanbuildinfo.jam</code> files B2 will load that files automatically 4089when it loads the project at the same location. The included file can 4090define targets and other project declarations in the context of the 4091project it’s being loaded into. Control over what package manager file 4092is loaded can be controlled with (in order of priority):</p> 4093</div> 4094<div class="ulist"> 4095<ul> 4096<li> 4097<p>With the <code>use-packages</code> rule.</p> 4098</li> 4099<li> 4100<p>Command line argument <code>--use-package-manager=X</code>.</p> 4101</li> 4102<li> 4103<p>Environment variable <code>PACKAGE_MANAGER_BUILD_INFO</code>.</p> 4104</li> 4105<li> 4106<p>Built-in detection of the file. Currently this includes: "conan".</p> 4107</li> 4108</ul> 4109</div> 4110<div class="paragraph"> 4111<p><strong><code>use-packages</code> rule:</strong></p> 4112</div> 4113<div class="listingblock"> 4114<div class="content"> 4115<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-k">rule</span><span class="tok-w"> </span><span class="tok-nf">use-packages</span><span class="tok-w"> </span><span class="tok-p">(</span><span class="tok-w"> </span><span class="tok-nv">name-or-glob-pattern</span><span class="tok-w"> </span><span class="tok-p">?</span><span class="tok-w"> </span><span class="tok-p">)</span><span class="tok-w"></span></code></pre> 4116</div> 4117</div> 4118<div class="paragraph"> 4119<p>The <code>use-packages</code> rule allows one to specify in the projects themselves kind 4120of package definitions to use either as the ones for a built-in package 4121manager support. For example:</p> 4122</div> 4123<div class="listingblock"> 4124<div class="content"> 4125<pre class="pygments highlight"><code data-lang="jam"><span></span>use-packages<span class="tok-w"> </span>conan<span class="tok-w"> </span>;<span class="tok-w"></span></code></pre> 4126</div> 4127</div> 4128<div class="paragraph"> 4129<p>Or to specify a <code>glob</code> pattern to find the file with the definitions. For 4130instance:</p> 4131</div> 4132<div class="listingblock"> 4133<div class="content"> 4134<pre class="pygments highlight"><code data-lang="jam"><span></span>use-packages<span class="tok-w"> </span>"packages.jam"<span class="tok-w"> </span>;<span class="tok-w"></span></code></pre> 4135</div> 4136</div> 4137<div class="paragraph"> 4138<p><strong><code>--use-package-manager</code> command line option:</strong></p> 4139</div> 4140<div class="paragraph"> 4141<p>The <code>--use-package-manager=NAME</code> command line option allows one to 4142non-intrusively specify per invocation which of the built-in package manager 4143types to use.</p> 4144</div> 4145<div class="paragraph"> 4146<p><strong><code>PACKAGE_MANAGER_BUILD_INFO</code> variable:</strong></p> 4147</div> 4148<div class="paragraph"> 4149<p>The <code>PACKAGE_MANAGER_BUILD_INFO</code> variable, which is taken from the environment 4150or defined with the <code>-sX=Y</code> option, specifies a <code>glob</code> pattern to use to find 4151the package definitions.</p> 4152</div> 4153<div class="paragraph"> 4154<p><strong>Built-in detection:</strong></p> 4155</div> 4156<div class="paragraph"> 4157<p>There are a number of built-in <code>glob</code> patterns to support popular package 4158managers. Currently the supported ones are:</p> 4159</div> 4160<div class="ulist"> 4161<ul> 4162<li> 4163<p>Conan (<code>conan</code>): currently supports the 4164<a href="https://bintray.com/bfgroup/public-conan/b2gen%3Abfgroup"><code>b2gen</code></a> 4165generator.</p> 4166</li> 4167</ul> 4168</div> 4169</div> 4170</div> 4171</div> 4172<div class="sect1"> 4173<h2 id="bbv2.reference"><a class="anchor" href="#bbv2.reference"></a>5. Reference</h2> 4174<div class="sectionbody"> 4175<div class="sect2"> 4176<h3 id="bbv2.reference.general"><a class="anchor" href="#bbv2.reference.general"></a>5.1. General information</h3> 4177<div class="sect3"> 4178<h4 id="bbv2.reference.init"><a class="anchor" href="#bbv2.reference.init"></a>5.1.1. Initialization</h4> 4179<div class="paragraph"> 4180<p>Immediately upon starting, the B2 engine (<strong><code>b2</code></strong>) loads the Jam 4181code that implements the build system. To do this, it searches for a 4182file called <code>boost-build.jam</code>, first in the invocation directory, then 4183in its parent and so forth up to the filesystem root, and finally in the 4184directories specified by the environment variable BOOST_BUILD_PATH. On 4185Unix BOOST_BUILD_PATH defaults to <code>/usr/share/boost-build</code>. When 4186found, the file is interpreted, and should specify the build system 4187location by calling the boost-build rule:</p> 4188</div> 4189<div class="listingblock"> 4190<div class="content"> 4191<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-k">rule</span><span class="tok-w"> </span><span class="tok-nf">boost-build</span><span class="tok-w"> </span><span class="tok-p">(</span><span class="tok-w"> </span><span class="tok-nv">location</span><span class="tok-w"> </span><span class="tok-p">?</span><span class="tok-w"> </span><span class="tok-p">)</span><span class="tok-w"></span></code></pre> 4192</div> 4193</div> 4194<div class="paragraph"> 4195<p>If location is a relative path, it is treated as relative to the 4196directory of <code>boost-build.jam</code>. The directory specified by that location 4197and the directories in BOOST_BUILD_PATH are then searched for a file 4198called <code>bootstrap.jam</code>, which is expected to bootstrap the build system. 4199This arrangement allows the build system to work without any 4200command-line or environment variable settings. For example, if the build 4201system files were located in a directory "build-system/" at your project 4202root, you might place a <code>boost-build.jam</code> at the project root 4203containing:</p> 4204</div> 4205<div class="listingblock"> 4206<div class="content"> 4207<pre class="pygments highlight"><code data-lang="jam"><span></span>boost-build<span class="tok-w"> </span>build-system<span class="tok-w"> </span>;<span class="tok-w"></span></code></pre> 4208</div> 4209</div> 4210<div class="paragraph"> 4211<p>In this case, running <strong><code>b2</code></strong> anywhere in the project tree will 4212automatically find the build system.</p> 4213</div> 4214<div class="paragraph"> 4215<p>The default <code>bootstrap.jam</code>, after loading some standard definitions, 4216loads both <code>site-config.jam</code> and <code>user-config.jam</code>.</p> 4217</div> 4218</div> 4219</div> 4220<div class="sect2"> 4221<h3 id="bbv2.reference.rules"><a class="anchor" href="#bbv2.reference.rules"></a>5.2. Builtin rules</h3> 4222<div class="paragraph"> 4223<p>This section contains the list of all rules that can be used in 4224Jamfile — both rules that define new targets and auxiliary rules.</p> 4225</div> 4226<div class="dlist"> 4227<dl> 4228<dt class="hdlist1"><a id="bbv2.reference.rules.exe"></a><code>exe</code></dt> 4229<dd> 4230<p>Creates an executable file. See 4231<a href="#bbv2.tasks.programs">the section called “Programs”</a>.</p> 4232</dd> 4233<dt class="hdlist1"><a id="bbv2.reference.rules.lib"></a><code>lib</code></dt> 4234<dd> 4235<p>Creates an library file. See 4236<a href="#bbv2.tasks.libraries">the section called “Libraries”</a>.</p> 4237</dd> 4238<dt class="hdlist1"><a id="bbv2.reference.rules.install"></a><code>install</code></dt> 4239<dd> 4240<p>Installs built targets and other files. See 4241<a href="#bbv2.tasks.installing">the section called “Installing”</a>.</p> 4242</dd> 4243<dt class="hdlist1"><a id="bbv2.reference.rules.alias"></a><code>alias</code></dt> 4244<dd> 4245<p>Creates an alias for other targets. See 4246<a href="#bbv2.tasks.alias">the section called “Alias”</a>.</p> 4247</dd> 4248<dt class="hdlist1"><a id="bbv2.reference.rules.unit-test"></a><code>unit-test</code></dt> 4249<dd> 4250<p>Creates an executable that will be automatically run. See 4251<a href="#bbv2.builtins.testing">the section called “Testing”</a>.</p> 4252</dd> 4253<dt class="hdlist1"><a id="bbv2.reference.rules.test"></a><code>compile</code>; <code>compile-fail</code>; <code>link</code>; <code>link-fail</code>; <code>run</code>; <code>run-fail</code></dt> 4254<dd> 4255<p>Specialized rules for testing. See 4256<a href="#bbv2.builtins.testing">the section called “Testing”</a>.</p> 4257</dd> 4258<dt class="hdlist1"><a id="bbv2.reference.rules.check-target-builds"></a><code>check-target-builds</code></dt> 4259<dd> 4260<p>The <code>check-target-builds</code> allows you to conditionally use different 4261properties depending on whether some metatarget builds, or not. This 4262is similar to functionality of configure script in <code>autotools</code> projects. 4263The function signature is:</p> 4264<div class="listingblock"> 4265<div class="content"> 4266<pre>rule check-target-builds ( target message ? : true-properties * : false-properties * )</pre> 4267</div> 4268</div> 4269<div class="paragraph"> 4270<p>This function can only be used when passing requirements or usage 4271requirements to a metatarget rule. For example, to make an application 4272link to a library if it’s available, one has use the following:</p> 4273</div> 4274<div class="listingblock"> 4275<div class="content"> 4276<pre>exe app : app.cpp : [ check-target-builds has_foo "System has foo" : <library>foo : <define>FOO_MISSING=1 ] ;</pre> 4277</div> 4278</div> 4279<div class="paragraph"> 4280<p>For another example, the alias rule can be used to consolidate 4281configuration choices and make them available to other metatargets, 4282like so:</p> 4283</div> 4284<div class="listingblock"> 4285<div class="content"> 4286<pre>alias foobar : : : : [ check-target-builds has_foo "System has foo" : <library>foo : <library>bar ] ;</pre> 4287</div> 4288</div> 4289</dd> 4290<dt class="hdlist1"><a id="bbv2.reference.rules.obj"></a><code>obj</code></dt> 4291<dd> 4292<p>Creates an object file. Useful when a single source file must be 4293compiled with special properties.</p> 4294</dd> 4295<dt class="hdlist1"><a id="bbv2.reference.rules.preprocessed"></a><code>preprocessed</code></dt> 4296<dd> 4297<p>Creates an preprocessed source file. The arguments follow the 4298<a href="#bbv2.main-target-rule-syntax">common syntax</a>.</p> 4299</dd> 4300<dt class="hdlist1"><a id="bbv2.reference.rules.glob"></a><code>glob</code></dt> 4301<dd> 4302<p>The <code>glob</code> rule takes a list shell pattern and returns the list of 4303files in the project’s source directory that match the pattern. For 4304example:</p> 4305<div class="listingblock"> 4306<div class="content"> 4307<pre>lib tools : [ glob *.cpp ] ;</pre> 4308</div> 4309</div> 4310<div class="paragraph"> 4311<p>It is possible to also pass a second argument—the list of exclude 4312patterns. The result will then include the list of files matching any 4313of include patterns, and not matching any of the exclude patterns. For 4314example:</p> 4315</div> 4316<div class="listingblock"> 4317<div class="content"> 4318<pre>lib tools : [ glob *.cpp : file_to_exclude.cpp bad*.cpp ] ;</pre> 4319</div> 4320</div> 4321</dd> 4322<dt class="hdlist1"><a id="bbv2.reference.glob-tree"></a><code>glob-tree</code></dt> 4323<dd> 4324<p>The <code>glob-tree</code> is similar to the <code>glob</code> except that it operates 4325recursively from the directory of the containing Jamfile. For example:</p> 4326<div class="listingblock"> 4327<div class="content"> 4328<pre>ECHO [ glob-tree *.cpp : .svn ] ;</pre> 4329</div> 4330</div> 4331<div class="paragraph"> 4332<p>will print the names of all C++ files in your project. The <code>.svn</code> 4333exclude pattern prevents the <code>glob-tree</code> rule from entering 4334administrative directories of the Subversion version control system.</p> 4335</div> 4336</dd> 4337<dt class="hdlist1"><a id="bbv2.reference.rules.project"></a><code>project</code></dt> 4338<dd> 4339<p>Declares project id and attributes, including project requirements. 4340See <a href="#bbv2.overview.projects">the section called “Projects”</a>.</p> 4341</dd> 4342<dt class="hdlist1"><a id="bbv2.reference.rules.use-project"></a><code>use-project</code></dt> 4343<dd> 4344<p>Assigns a symbolic project ID to a project at a given path. This rule 4345must be better documented!</p> 4346</dd> 4347<dt class="hdlist1"><a id="bbv2.reference.rules.explicit"></a><code>explicit</code></dt> 4348<dd> 4349<p>The <code>explicit</code> rule takes a single parameter—​a list of target names. 4350The named targets will be marked explicit, and will be built only if 4351they are explicitly requested on the command line, or if their 4352dependents are built. Compare this to ordinary targets, that are built 4353implicitly when their containing project is built.</p> 4354</dd> 4355<dt class="hdlist1"><a id="bbv2.reference.rules.always"></a><code>always</code></dt> 4356<dd> 4357<p>The <code>always</code> function takes a single parameter—a list of metatarget 4358names. The targets produced by the named metatargets will be 4359always considered out of date. Consider this example:</p> 4360<div class="listingblock"> 4361<div class="content"> 4362<pre>exe hello : hello.cpp ; 4363exe bye : bye.cpp ; 4364always hello ;</pre> 4365</div> 4366</div> 4367<div class="paragraph"> 4368<p>If a build of <code>hello</code> is requested, then it will always be recompiled. Note that 4369if a build of <code>hello</code> is not requested, for example you specify just 4370<code>bye</code> on the command line, <code>hello</code> will not be recompiled.</p> 4371</div> 4372</dd> 4373<dt class="hdlist1"><a id="bbv2.reference.rules.constant"></a><code>constant</code></dt> 4374<dd> 4375<p>Sets project-wide constant. Takes two parameters: variable name and a 4376value and makes the specified variable name accessible in this Jamfile 4377and any child Jamfiles. For example:</p> 4378<div class="listingblock"> 4379<div class="content"> 4380<pre>constant VERSION : 1.34.0 ;</pre> 4381</div> 4382</div> 4383</dd> 4384<dt class="hdlist1"><a id="bbv2.reference.rules.path-constant"></a><code>path-constant</code></dt> 4385<dd> 4386<p>Same as <code>constant</code> except that the value is treated as path relative 4387to Jamfile location. For example, if <code>b2</code> is invoked in the current 4388directory, and Jamfile in <code>helper</code> subdirectory has:</p> 4389<div class="listingblock"> 4390<div class="content"> 4391<pre>path-constant DATA : data/a.txt ;</pre> 4392</div> 4393</div> 4394<div class="paragraph"> 4395<p>then the variable <code>DATA</code> will be set to <code>helper/data/a.txt</code>, and if 4396<strong><code>b2</code></strong> is invoked from the <code>helper</code> directory, then the variable <code>DATA</code> 4397will be set to <code>data/a.txt</code>.</p> 4398</div> 4399</dd> 4400<dt class="hdlist1"><a id="bbv2.reference.rules.build-project"></a><code>build-project</code></dt> 4401<dd> 4402<p>Cause some other project to be built. This rule takes a single 4403parameter—a directory name relative to the containing Jamfile. When 4404the containing Jamfile is built, the project located at that directory 4405will be built as well. At the moment, the parameter to this rule 4406should be a directory name. Project ID or general target references 4407are not allowed.</p> 4408</dd> 4409<dt class="hdlist1"><a id="bbv2.reference.rules.test-suite"></a><code>test-suite</code></dt> 4410<dd> 4411<p>This rule is deprecated and equivalent to <code>alias</code>.</p> 4412</dd> 4413</dl> 4414</div> 4415</div> 4416<div class="sect2"> 4417<h3 id="bbv2.overview.builtins.features"><a class="anchor" href="#bbv2.overview.builtins.features"></a>5.3. Builtin features</h3> 4418<div class="paragraph"> 4419<p>This section documents the features that are built-in into B2. 4420For features with a fixed set of values, that set is provided, with the 4421default value listed first.</p> 4422</div> 4423<div class="dlist"> 4424<dl> 4425<dt class="hdlist1"><a id="bbv2.builtin.features.address-model"></a><code>address-model</code></dt> 4426<dd> 4427<p><strong>Allowed values:</strong> <code>32</code>, <code>64</code>.</p> 4428<div class="paragraph"> 4429<p>Specifies if 32-bit or 64-bit code should be generated by the compiler. Whether 4430this feature works depends on the used compiler, its version, how the compiler 4431is configured, and the values of the <code>architecture</code> <code>instruction-set</code> features. 4432Please see the section <a href="#bbv2.reference.tools.compilers">C++ Compilers</a> for details.</p> 4433</div> 4434</dd> 4435<dt class="hdlist1"><a id="bbv2.builtin.features.address-sanitizer"></a><code>address-sanitizer</code></dt> 4436<dd> 4437<p><strong>Allowed values:</strong> <code>on</code>, <code>norecover</code>.</p> 4438<div class="paragraph"> 4439<p>Enables address sanitizer. Value <code>norecover</code> disables recovery for the 4440sanitizer. The feature is optional, thus no sanitizer is enabled by default.</p> 4441</div> 4442</dd> 4443<dt class="hdlist1"><a id="bbv2.builtin.features.allow"></a><code>allow</code></dt> 4444<dd> 4445<p>This feature is used to allow specific generators to run. For example, Qt tools 4446can only be invoked when Qt library is used. In that case, <code><allow>qt</code> will be 4447in usage requirement of the library.</p> 4448</dd> 4449<dt class="hdlist1"><a id="bbv2.builtin.features.architecture"></a><code>architecture</code></dt> 4450<dd> 4451<p><strong>Allowed values:</strong> <code>x86</code>, <code>ia64</code>, <code>sparc</code>, <code>power</code>, <code>mips1</code>, <code>mips2</code>, 4452<code>mips3</code>, <code>mips4</code>, <code>mips32</code>, <code>mips32r2</code>, <code>mips64</code>, <code>parisc</code>, <code>arm</code>, 4453<code>s390x</code>, <code>combined</code>, <code>combined-x86-power</code>.</p> 4454<div class="paragraph"> 4455<p>Specifies the general processor family to generate code for.</p> 4456</div> 4457</dd> 4458<dt class="hdlist1"><a id="bbv2.builtin.features.archiveflags"></a><code>archiveflags</code></dt> 4459<dd> 4460<p>The value of this feature is passed without modification to the archiver tool 4461when creating static libraries.</p> 4462</dd> 4463<dt class="hdlist1"><a id="bbv2.builtin.features.asmflags"></a><code>asmflags</code></dt> 4464<dd> 4465<p>The value of this feature is passed without modification to the assembler.</p> 4466</dd> 4467<dt class="hdlist1"><a id="bbv2.builtin.features.asynch-exceptions"></a><code>asynch-exceptions</code></dt> 4468<dd> 4469<p><strong>Allowed values:</strong> <code>off</code>, <code>on</code>.</p> 4470<div class="paragraph"> 4471<p>Selects whether there is support for asynchronous EH (e.g. catching SEGVs).</p> 4472</div> 4473</dd> 4474<dt class="hdlist1"><a id="bbv2.builtin.features.build"></a><code>build</code></dt> 4475<dd> 4476<p><strong>Allowed values:</strong> <code>no</code></p> 4477<div class="paragraph"> 4478<p>Used to conditionally disable build of a target. If <code><build>no</code> is in 4479properties when building a target, build of that target is skipped. Combined 4480with conditional requirements this allows you to skip building some target in 4481configurations where the build is known to fail.</p> 4482</div> 4483</dd> 4484<dt class="hdlist1"><a id="bbv2.builtin.features.cflags"></a><code>cflags</code>; <code>cxxflags</code>; <code>linkflags</code></dt> 4485<dd> 4486<p>The value of these features is passed without modification to the corresponding 4487tools. For <code>cflags</code> that is both the C and C++ compilers, for <code>cxxflags</code> that 4488is the C++ compiler, and for <code>linkflags</code> that is the linker. The features are 4489handy when you are trying to do something special that cannot be achieved by a 4490higher-level feature in B2.</p> 4491</dd> 4492<dt class="hdlist1"><a id="bbv2.builtin.features.conditional"></a><code>conditional</code></dt> 4493<dd> 4494<p>Used to introduce indirect conditional requirements. The value should have the 4495form:</p> 4496<div class="listingblock"> 4497<div class="content"> 4498<pre>@rulename</pre> 4499</div> 4500</div> 4501<div class="paragraph"> 4502<p>where <em>rulename</em> should be a name of a rule with the following signature:</p> 4503</div> 4504<div class="listingblock"> 4505<div class="content"> 4506<pre>rule rulename ( properties * )</pre> 4507</div> 4508</div> 4509<div class="paragraph"> 4510<p>The rule will be called for each target with its properties and should return 4511any additional properties. See also section <a href="#bbv2.overview.targets.requirements">Requirements</a> for an example.</p> 4512</div> 4513</dd> 4514<dt class="hdlist1"><a id="bbv2.builtin.features.coverage"></a><code>coverage</code></dt> 4515<dd> 4516<p><strong>Allowed values:</strong> <code>off</code>, <code>on</code>.</p> 4517<div class="paragraph"> 4518<p>Enables code instrumentation to generate coverage data during execution.</p> 4519</div> 4520</dd> 4521<dt class="hdlist1"><a id="bbv2.builtin.features.cxxflags"></a><code>cxxflags</code></dt> 4522<dd> 4523<p>See <a href="#bbv2.builtin.features.cflags"><code><cflags></code></a>.</p> 4524</dd> 4525<dt class="hdlist1"><a id="bbv2.builtin.features.cxxstd"></a><code>cxxstd</code></dt> 4526<dd> 4527<p><strong>Allowed values</strong>: <code>98</code>, <code>03</code>, <code>0x</code>, <code>11</code>, <code>1y</code>, <code>14</code>, <code>1z</code>, <code>17</code>, <code>2a</code>, <code>20</code>, 4528<code>latest</code>.</p> 4529<div class="paragraph"> 4530<p>Specifies the version of the C++ Standard Language to build with. All the 4531official versions of the standard since "98" are included. It is also possible 4532to specify using the experimental, work in progress, <code>latest</code> version. Some 4533compilers specified intermediate versions for the experimental versions leading 4534up to the released standard version. Those are included following the GNU 4535nomenclature as <code>0x</code>, <code>1y</code>, <code>1z</code>, and <code>2a</code>. Depending on the compiler <code>latest</code> 4536would map to one of those.</p> 4537</div> 4538</dd> 4539</dl> 4540</div> 4541<div class="admonitionblock note"> 4542<table> 4543<tr> 4544<td class="icon"> 4545<div class="title">ℹ</div> 4546</td> 4547<td class="content"> 4548This is an <code>optional</code> feature. Hence when not specified the compiler 4549default behaviour is used. 4550</td> 4551</tr> 4552</table> 4553</div> 4554<div class="admonitionblock note"> 4555<table> 4556<tr> 4557<td class="icon"> 4558<div class="title">ℹ</div> 4559</td> 4560<td class="content"> 4561Please consult the toolset specific documentation for which <code>cxxstd</code> 4562is supported. 4563</td> 4564</tr> 4565</table> 4566</div> 4567<div class="dlist"> 4568<dl> 4569<dt class="hdlist1"><a id="bbv2.builtin.features.cxxstd-dialect"></a><code>cxxstd-dialect</code></dt> 4570<dd> 4571<p><strong>Subfeature of</strong> <code>cxxstd</code></p> 4572<div class="paragraph"> 4573<p><strong>Allowed values</strong>: <code>iso</code>, <code>gnu</code>, <code>ms</code>.</p> 4574</div> 4575<div class="paragraph"> 4576<p>Indicates if a non-standard dialect should be used. These usually have 4577either/or extensions or platform specific functionality. Not specifying the 4578dialect will default to 'iso' which will attempt to use ISO C++ Standard 4579conformance to the best of the compiler’s ability.</p> 4580</div> 4581</dd> 4582<dt class="hdlist1"><a id="bbv2.builtin.features.cxxabi"></a><code>c++abi</code></dt> 4583<dd> 4584<p>Selects a specific variant of C++ ABI if the compiler supports several.</p> 4585</dd> 4586<dt class="hdlist1"><a id="bbv2.builtin.features.cpp-template-depth"></a><code>c++-template-depth</code></dt> 4587<dd> 4588<p><strong>Allowed values:</strong> Any positive integer.</p> 4589<div class="paragraph"> 4590<p>Allows configuring a C++ compiler with the maximal template instantiation 4591depth parameter. Specific toolsets may or may not provide support for this 4592feature depending on whether their compilers provide a corresponding 4593command-line option.</p> 4594</div> 4595<div class="admonitionblock note"> 4596<table> 4597<tr> 4598<td class="icon"> 4599<div class="title">ℹ</div> 4600</td> 4601<td class="content"> 4602Due to some internal details in the current B2 implementation it 4603is not possible to have features whose valid values are all positive integer. 4604As a workaround a large set of allowed values has been defined for this feature 4605and, if a different one is needed, user can easily add it by calling the 4606feature.extend rule. 4607</td> 4608</tr> 4609</table> 4610</div> 4611</dd> 4612<dt class="hdlist1"><a id="bbv2.builtin.features.debug-symbols"></a><code>debug-symbols</code></dt> 4613<dd> 4614<p><strong>Allowed values:</strong> <code>on</code>, <code>off</code>.</p> 4615<div class="paragraph"> 4616<p>Specifies if produced object files, executables, and libraries should include 4617debug information. Typically, the value of this feature is implicitly set by 4618the <code>variant</code> feature, but it can be explicitly specified by the user. The most 4619common usage is to build release variant with debugging information.</p> 4620</div> 4621</dd> 4622<dt class="hdlist1"><a id="bbv2.builtin.features.define"></a><code>define</code></dt> 4623<dd> 4624<p>Specifies a preprocessor symbol that should be defined on the command line. 4625You may either specify just the symbol, which will be defined without any 4626value, or both the symbol and the value, separated by equal sign.</p> 4627</dd> 4628<dt class="hdlist1"><a id="bbv2.builtin.features.def-file"></a><code>def-file</code></dt> 4629<dd> 4630<p>Provides a means to specify def-file for windows DLLs.</p> 4631</dd> 4632<dt class="hdlist1"><a id="bbv2.builtin.features.dependency"></a><code>dependency</code></dt> 4633<dd> 4634<p>Introduces a dependency on the target named by the value of this feature (so it 4635will be brought up-to-date whenever the target being declared is). The 4636dependency is not used in any other way.</p> 4637</dd> 4638<dt class="hdlist1"><a id="bbv2.builtin.features.dll-path"></a><code>dll-path</code></dt> 4639<dd> 4640<p>Specifies an additional directory where the system should look for shared 4641libraries when the executable or shared library is run. This feature only 4642affects Unix compilers. Please see 4643<a href="#bbv2.faq.dll-path">Why are the <code>dll-path</code> and <code>hardcode-dll-paths</code> properties useful?</a> 4644in <a href="#bbv2.faq">Frequently Asked Questions</a> for details.</p> 4645</dd> 4646<dt class="hdlist1"><a id="bbv2.builtin.features.embed-manifest"></a><code>embed-manifest</code></dt> 4647<dd> 4648<p><strong>Allowed values:</strong> <code>on</code>, <code>off</code>.</p> 4649<div class="paragraph"> 4650<p>This feature is specific to the <code>msvc</code> toolset (see <a href="#bbv2.reference.tools.compiler.msvc">Microsoft Visual C++</a>), 4651and controls whether the manifest files should be embedded inside executables 4652and shared libraries, or placed alongside them. This feature corresponds to the 4653IDE option found in the project settings dialog, under Configuration Properties 4654→ Manifest Tool → Input and Output → Embed manifest.</p> 4655</div> 4656</dd> 4657<dt class="hdlist1"><a id="bbv2.builtin.features.embed-manifest-file"></a><code>embed-manifest-file</code></dt> 4658<dd> 4659<p>This feature is specific to the <code>msvc</code> toolset (see <a href="#bbv2.reference.tools.compiler.msvc">Microsoft Visual C++</a>), 4660and controls which manifest files should be embedded inside executables and 4661shared libraries. This feature corresponds to the IDE option found in the 4662project settings dialog, under Configuration Properties → Manifest Tool → 4663Input and Output → Additional Manifest Files.</p> 4664</dd> 4665<dt class="hdlist1"><a id="bbv2.builtin.features.embed-manifest-via"></a><code>embed-manifest-via</code></dt> 4666<dd> 4667<p>This feature is specific to the <code>msvc</code> toolset (see <a href="#bbv2.reference.tools.compiler.msvc">Microsoft Visual C++</a>), 4668and controls whether a manifest should be embedded via linker or manifest tool.</p> 4669</dd> 4670<dt class="hdlist1"><a id="bbv2.builtin.features.exception-handling"></a><code>exception-handling</code></dt> 4671<dd> 4672<p><strong>Allowed values:</strong> <code>on</code>, <code>off</code>.</p> 4673<div class="paragraph"> 4674<p>Disables exceptions.</p> 4675</div> 4676</dd> 4677<dt class="hdlist1"><a id="bbv2.builtin.features.extern-c-nothrow"></a><code>extern-c-nothrow</code></dt> 4678<dd> 4679<p><strong>Allowed values:</strong> <code>off</code>, <code>on</code>.</p> 4680<div class="paragraph"> 4681<p>Selects whether all <code>extern "C"</code> functions are considered <code>nothrow</code> by default.</p> 4682</div> 4683</dd> 4684<dt class="hdlist1"><a id="bbv2.builtin.features.fflags"></a><code>fflags</code></dt> 4685<dd> 4686<p>The value of this feature is passed without modification to the tool when 4687compiling Fortran sources.</p> 4688</dd> 4689<dt class="hdlist1"><a id="bbv2.builtin.features.file"></a><code>file</code></dt> 4690<dd> 4691<p>When used in requirements of a prebuilt library target this feature specifies 4692the path to the library file. See <a href="#bbv2.tutorial.prebuilt">Prebuilt targets</a> for examples.</p> 4693</dd> 4694<dt class="hdlist1"><a id="bbv2.builtin.features.find-shared-library"></a><code>find-shared-library</code></dt> 4695<dd> 4696<p>Adds a shared library to link to. Usually <a href="#bbv2.tasks.libraries"><code>lib</code></a> 4697targets should be preferred over using this feature.</p> 4698</dd> 4699<dt class="hdlist1"><a id="bbv2.builtin.features.find-static-library"></a><code>find-static-library</code></dt> 4700<dd> 4701<p>Adds a static library to link to. Usually <a href="#bbv2.tasks.libraries"><code>lib</code></a> 4702targets should be preferred over using this feature.</p> 4703</dd> 4704<dt class="hdlist1"><a id="bbv2.builtin.features.flags"></a><code>flags</code></dt> 4705<dd> 4706<p>This feature is used for generic, i.e. non-language specific, flags for tools. 4707The value of this feature is passed without modification to the tool that will 4708build the target.</p> 4709</dd> 4710<dt class="hdlist1"><a id="bbv2.builtin.features.hardcode-dll-paths"></a><code>hardcode-dll-paths</code></dt> 4711<dd> 4712<p><strong>Allowed values:</strong> <code>true</code>, <code>false</code>.</p> 4713<div class="paragraph"> 4714<p>Controls automatic generation of dll-path properties.</p> 4715</div> 4716<div class="paragraph"> 4717<p>This property is specific to Unix systems. If an executable is built with 4718<code><hardcode-dll-paths>true</code>, the generated binary will contain the list of all 4719the paths to the used shared libraries. As the result, the executable can be 4720run without changing system paths to shared libraries or installing the 4721libraries to system paths. This is very convenient during development. Please 4722see the <a href="#bbv2.faq.dll-path">FAQ entry</a> for details. Note that on Mac OSX, 4723the paths are unconditionally hardcoded by the linker, and it is not possible 4724to disable that behavior</p> 4725</div> 4726</dd> 4727<dt class="hdlist1"><a id="bbv2.builtin.features.implicit-dependency"></a><code>implicit-dependency</code></dt> 4728<dd> 4729<p>Indicates that the target named by the value of this feature may produce files 4730that are included by the sources of the target being declared. See the section 4731<a href="#bbv2.reference.generated_headers">Generated headers</a> for more information.</p> 4732</dd> 4733<dt class="hdlist1"><a id="bbv2.builtin.features.force-include"></a><code>force-include</code></dt> 4734<dd> 4735<p>Specifies an include path that has to be included in a way like if 4736<code>#include "file"</code> appeared as the first line of every target’s source file.</p> 4737</dd> 4738</dl> 4739</div> 4740<div class="paragraph"> 4741<p>The include order is not guaranteed if used multiple times on a single target.</p> 4742</div> 4743<div class="dlist"> 4744<dl> 4745<dt class="hdlist1"><a id="bbv2.builtin.features.include"></a><code>include</code></dt> 4746<dd> 4747<p>Specifies an additional include path that is to be passed to C and C++ 4748compilers.</p> 4749</dd> 4750<dt class="hdlist1"><a id="bbv2.builtin.features.inlining"></a><code>inlining</code></dt> 4751<dd> 4752<p><strong>Allowed values:</strong> <code>off</code>, <code>on</code>, <code>full</code>.</p> 4753<div class="paragraph"> 4754<p>Enables inlining.</p> 4755</div> 4756</dd> 4757<dt class="hdlist1"><a id="bbv2.builtin.features.install-package"></a><code>install-package</code></dt> 4758<dd> 4759<p>Specifies the name of the package to which installed files belong. This is 4760used for default installation prefix on certain platforms.</p> 4761</dd> 4762<dt class="hdlist1"><a id="bbv2.builtin.features.install-prefix"></a><code>install-<name></code></dt> 4763<dd> 4764<p>Specifies installation prefix for <a href="#bbv2.tasks.installing"><code>install</code></a> targets. 4765These named installation prefixes are registered by default:</p> 4766<div class="ulist"> 4767<ul> 4768<li> 4769<p><code>prefix</code>: <code>C:\<package name></code> if <code><target-os>windows</code> is in the property set, 4770<code>/usr/local</code> otherwise</p> 4771</li> 4772<li> 4773<p><code>exec-prefix</code>: <code>(prefix)</code></p> 4774</li> 4775<li> 4776<p><code>bindir</code>: <code>(exec-prefix)/bin</code></p> 4777</li> 4778<li> 4779<p><code>sbindir</code>: <code>(exec-prefix)/sbin</code></p> 4780</li> 4781<li> 4782<p><code>libexecdir</code>: <code>(exec-prefix)/libexec</code></p> 4783</li> 4784<li> 4785<p><code>libdir</code>: <code>(exec-prefix)/lib</code></p> 4786</li> 4787<li> 4788<p><code>datarootdir</code>: <code>(prefix)/share</code></p> 4789</li> 4790<li> 4791<p><code>datadir</code>: <code>(datarootdir)</code></p> 4792</li> 4793<li> 4794<p><code>sysconfdir</code>: <code>(prefix)/etc</code></p> 4795</li> 4796<li> 4797<p><code>sharedstatedir</code>: <code>(prefix)/com</code></p> 4798</li> 4799<li> 4800<p><code>localstatedir</code>: <code>(prefix)/var</code></p> 4801</li> 4802<li> 4803<p><code>runstatedir</code>: <code>(localstatedir)/run</code></p> 4804</li> 4805<li> 4806<p><code>includedir</code>: <code>(prefix)/include</code></p> 4807</li> 4808<li> 4809<p><code>oldincludedir</code>: <code>/usr/include</code></p> 4810</li> 4811<li> 4812<p><code>docdir</code>: <code>(datarootdir)/doc/<package name></code></p> 4813</li> 4814<li> 4815<p><code>infodir</code>: <code>(datarootdir)/info</code></p> 4816</li> 4817<li> 4818<p><code>htmldir</code>: <code>(docdir)</code></p> 4819</li> 4820<li> 4821<p><code>dvidir</code> : <code>(docdir)</code></p> 4822</li> 4823<li> 4824<p><code>pdfdir</code> : <code>(docdir)</code></p> 4825</li> 4826<li> 4827<p><code>psdir</code> : <code>(docdir)</code></p> 4828</li> 4829<li> 4830<p><code>lispdir</code>: <code>(datarootdir)/emacs/site-lisp</code></p> 4831</li> 4832<li> 4833<p><code>localedir</code>: <code>(datarootdir)/locale</code></p> 4834</li> 4835<li> 4836<p><code>mandir</code>: <code>(datarootdir)/man</code></p> 4837</li> 4838</ul> 4839</div> 4840</dd> 4841</dl> 4842</div> 4843<div class="paragraph"> 4844<p>If more are necessary, they could be added with 4845<a href="#bbv2.reference.modules.stage.add-install-dir"><code>stage.add-install-dir</code></a>.</p> 4846</div> 4847<div class="dlist"> 4848<dl> 4849<dt class="hdlist1"><a id="bbv2.builtin.features.instruction-set"></a><code>instruction-set</code></dt> 4850<dd> 4851<p><strong>Allowed values:</strong> depends on the used toolset.</p> 4852<div class="paragraph"> 4853<p>Specifies for which specific instruction set the code should be generated. The 4854code in general might not run on processors with older/different instruction 4855sets.</p> 4856</div> 4857<div class="paragraph"> 4858<p>While B2 allows a large set of possible values for this features, 4859whether a given value works depends on which compiler you use. Please see 4860the section <a href="#bbv2.reference.tools.compilers">C++ Compilers</a> for details.</p> 4861</div> 4862</dd> 4863<dt class="hdlist1"><a id="bbv2.builtin.features.library"></a><code>library</code></dt> 4864<dd> 4865<p>This feature is almost equivalent to the 4866<a href="#bbv2.builtin.features.library"><code><source></code></a> feature, except that it takes 4867effect only for linking. When you want to link all targets in a Jamfile to 4868certain library, the <code><library></code> feature is preferred over <code><source>X</code> — the 4869latter will add the library to all targets, even those that have nothing to do 4870with libraries.</p> 4871</dd> 4872<dt class="hdlist1"><a id="bbv2.builtin.features.library-path"></a><code>library-path</code></dt> 4873<dd> 4874<p>Adds to the list of directories which will be used by the linker to search for 4875libraries.</p> 4876</dd> 4877<dt class="hdlist1"><a id="bbv2.builtin.features.leak-sanitizer"></a><code>leak-sanitizer</code></dt> 4878<dd> 4879<p><strong>Allowed values:</strong> <code>on</code>, <code>norecover</code>.</p> 4880<div class="paragraph"> 4881<p>Enables leak sanitizer. Value <code>norecover</code> disables recovery for the 4882sanitizer. The feature is optional, thus no sanitizer is enabled by default.</p> 4883</div> 4884</dd> 4885<dt class="hdlist1"><a id="bbv2.builtin.features.link"></a><code>link</code></dt> 4886<dd> 4887<p><strong>Allowed values:</strong> <code>shared</code>, <code>static</code></p> 4888<div class="paragraph"> 4889<p>Controls how libraries are built.</p> 4890</div> 4891</dd> 4892<dt class="hdlist1"><a id="bbv2.builtin.features.linkflags"></a><code>linkflags</code></dt> 4893<dd> 4894<p>See <a href="#bbv2.builtin.features.cflags"><code><cflags></code></a>.</p> 4895</dd> 4896<dt class="hdlist1"><a id="bbv2.builtin.features.local-visibility"></a><code>local-visibility</code></dt> 4897<dd> 4898<p><strong>Allowed values:</strong> <code>global</code>, <code>protected</code>, <code>hidden</code>.</p> 4899<div class="paragraph"> 4900<p>This feature has the same effect as the 4901<a href="#bbv2.builtin.features.visibility"><code>visibility</code></a> feature but is intended 4902to be used by targets that require a particular symbol visibility. Unlike the 4903<code>visibility</code> feature, <code>local-visibility</code> is not inherited by the target 4904dependencies and only affects the target to which it is applied.</p> 4905</div> 4906<div class="paragraph"> 4907<p>The <code>local-visibility</code> feature supports the same values with the same meaning 4908as the <code>visibility</code> feature. By default, if <code>local-visibility</code> is not specified 4909for a target, the value of the <code>visibility</code> feature is used.</p> 4910</div> 4911</dd> 4912<dt class="hdlist1"><a id="bbv2.builtin.features.location"></a><code>location</code></dt> 4913<dd> 4914<p>Specifies the build directory for a target. The feature is used primarily with 4915<a href="#bbv2.tasks.installing"><code><install></code></a> rule.</p> 4916</dd> 4917<dt class="hdlist1"><a id="bbv2.builtin.features.location-prefix"></a><code>location-prefix</code></dt> 4918<dd> 4919<p>Sets the build directory for a target as the project’s build directory prefixed 4920with the value of this feature. See section <a href="#bbv2.reference.buildprocess.targetpath">Target Paths</a> for an example.</p> 4921</dd> 4922<dt class="hdlist1"><a id="bbv2.builtin.features.mflags"></a><code>mflags</code></dt> 4923<dd> 4924<p>The value of this feature is passed without modification to the tool when 4925compiling Objective C sources.</p> 4926</dd> 4927<dt class="hdlist1"><a id="bbv2.builtin.features.mmflags"></a><code>mmflags</code></dt> 4928<dd> 4929<p>The value of this feature is passed without modification to the tool when 4930compiling Objective C++ sources.</p> 4931</dd> 4932<dt class="hdlist1"><a id="bbv2.builtin.features.name"></a><code>name</code></dt> 4933<dd> 4934<p>When used in requirements of a prebuilt library target this feature specifies 4935the name of the library (the name of the library file without any 4936platform-specific suffixes or prefixes). See <a href="#bbv2.tutorial.prebuilt">Prebuilt targets</a> for examples.</p> 4937<div class="paragraph"> 4938<p>When used in requirements of an <code><install></code> target it specifies the name of the 4939target file.</p> 4940</div> 4941</dd> 4942<dt class="hdlist1"><a id="bbv2.builtin.features.optimization"></a><code>optimization</code></dt> 4943<dd> 4944<p><strong>Allowed values:</strong> <code>off</code>, <code>speed</code>, <code>space</code>.</p> 4945<div class="paragraph"> 4946<p>Enables optimization. <code>speed</code> optimizes for faster code, <code>space</code> optimizes for 4947smaller binary.</p> 4948</div> 4949</dd> 4950<dt class="hdlist1"><a id="bbv2.builtin.features.profiling"></a><code>profiling</code></dt> 4951<dd> 4952<p><strong>Allowed values:</strong> <code>off</code>, <code>on</code>.</p> 4953<div class="paragraph"> 4954<p>Enables generation of extra code to write profile information.</p> 4955</div> 4956</dd> 4957<dt class="hdlist1"><a id="bbv2.builtin.features.relevant"></a><code>relevant</code></dt> 4958<dd> 4959<p><strong>Allowed values:</strong> the name of any feature.</p> 4960<div class="paragraph"> 4961<p>Indicates which other features are relevant for a given target. It is usually 4962not necessary to manage it explicitly, as B2 can deduce it in most 4963cases. Features which are not relevant will not affect target paths, and will 4964not cause conflicts.</p> 4965</div> 4966<div class="ulist"> 4967<ul> 4968<li> 4969<p>A feature will be considered relevant if any of the following are true</p> 4970<div class="ulist"> 4971<ul> 4972<li> 4973<p>It is referenced by <code>toolset.flags</code> or <code>toolset.uses-features</code></p> 4974</li> 4975<li> 4976<p>It is used by the requirements of a generator</p> 4977</li> 4978<li> 4979<p>It is a sub-feature of a relevant feature</p> 4980</li> 4981<li> 4982<p>It has a sub-feature which is relevant</p> 4983</li> 4984<li> 4985<p>It is a composite feature, and any composed feature is relevant</p> 4986</li> 4987<li> 4988<p>It affects target alternative selection for a main target</p> 4989</li> 4990<li> 4991<p>It is a propagated feature and is relevant for any dependency</p> 4992</li> 4993<li> 4994<p>It is relevant for any dependency created by the same main target</p> 4995</li> 4996<li> 4997<p>It is used in the condition of a conditional property and the corresponding 4998value is relevant</p> 4999</li> 5000<li> 5001<p>It is explicitly named as relevant</p> 5002</li> 5003</ul> 5004</div> 5005</li> 5006<li> 5007<p>Relevant features cannot be automatically deduced in the following cases:</p> 5008<div class="ulist"> 5009<ul> 5010<li> 5011<p>Indirect conditionals. Solution: return properties of the form 5012<code><relevant>result-feature:<relevant>condition-feature</code></p> 5013<div class="admonitionblock note"> 5014<table> 5015<tr> 5016<td class="icon"> 5017<div class="title">ℹ</div> 5018</td> 5019<td class="content"> 5020This isn’t really a conditional, although for most purposes it functions 5021like one. In particular, it does not support multiple comma-separated elements 5022in the condition, and it does work correctly even in contexts where conditional 5023properties are not allowed 5024</td> 5025</tr> 5026</table> 5027</div> 5028</li> 5029<li> 5030<p>Action rules that read properties. Solution: add toolset.uses-features to 5031tell B2 that the feature is actually used.</p> 5032</li> 5033<li> 5034<p>Generators and targets that manipulate property-sets directly. Solution: 5035set <relevant> manually.</p> 5036</li> 5037</ul> 5038</div> 5039</li> 5040</ul> 5041</div> 5042</dd> 5043<dt class="hdlist1"><a id="bbv2.builtin.features.rtti"></a><code>rtti</code></dt> 5044<dd> 5045<p><strong>Allowed values:</strong> <code>on</code>, <code>off</code>.</p> 5046<div class="paragraph"> 5047<p>Disables run-time type information.</p> 5048</div> 5049</dd> 5050<dt class="hdlist1"><a id="bbv2.builtin.features.runtime-debugging"></a><code>runtime-debugging</code></dt> 5051<dd> 5052<p><strong>Allowed values:</strong> <code>on</code>, <code>off</code>.</p> 5053<div class="paragraph"> 5054<p>Specifies whether produced object files, executables, and libraries should 5055include behavior useful only for debugging, such as asserts. Typically, the 5056value of this feature is implicitly set by the <code>variant</code> feature, but it can be 5057explicitly specified by the user. The most common usage is to build release 5058variant with debugging output.</p> 5059</div> 5060</dd> 5061<dt class="hdlist1"><a id="bbv2.builtin.features.runtime-link"></a><code>runtime-link</code></dt> 5062<dd> 5063<p><strong>Allowed values:</strong> <code>shared</code>, <code>static</code></p> 5064<div class="paragraph"> 5065<p>Controls if a static or shared C/C++ runtime should be used. There are some 5066restrictions how this feature can be used, for example on some compilers an 5067application using static runtime should not use shared libraries at all, and on 5068some compilers, mixing static and shared runtime requires extreme care. Check 5069your compiler documentation for more details.</p> 5070</div> 5071</dd> 5072<dt class="hdlist1"><a id="bbv2.builtin.features.search"></a><code>search</code></dt> 5073<dd> 5074<p>When used in requirements of a prebuilt library target this feature adds to the 5075list of directories to search for the library file. See <a href="#bbv2.tutorial.prebuilt">Prebuilt targets</a> 5076for examples.</p> 5077</dd> 5078<dt class="hdlist1"><a id="bbv2.builtin.features.source"></a><code>source</code></dt> 5079<dd> 5080<p>The <code><source>X</code> property has the same effect on building a target as putting X 5081in the list of sources. It is useful when you want to add the same source to 5082all targets in the project (you can put <code><source></code> in requirements) or to 5083conditionally include a source (using conditional requirements, see 5084the section <a href="#bbv2.tutorial.conditions">Conditions and alternatives</a>. See also the 5085<a href="#bbv2.builtin.features.library"><code><library></code></a> feature.</p> 5086</dd> 5087<dt class="hdlist1"><a id="bbv2.builtin.features.staging-prefix"></a><code>staging-prefix</code></dt> 5088<dd> 5089<p>Specifies staging prefix for <a href="#bbv2.tasks.installing"><code>install</code></a> targets. 5090If present, it will be used instead of the path to named directory <code>prefix</code>. 5091Example:</p> 5092<div class="listingblock"> 5093<div class="content"> 5094<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-nb">project</span><span class="tok-w"> </span>:<span class="tok-w"> </span>requirements<span class="tok-w"> </span><span class="tok-na"><install-prefix></span>x/y/z<span class="tok-w"> </span>;<span class="tok-w"></span> 5095<span class="tok-nb">install</span><span class="tok-w"> </span>a1<span class="tok-w"> </span>:<span class="tok-w"> </span>a<span class="tok-w"> </span>:<span class="tok-w"> </span><span class="tok-na"><location></span>(bindir)<span class="tok-w"> </span>;<span class="tok-w"> </span><span class="tok-c1"># installs into x/y/z/bin</span> 5096<span class="tok-nb">install</span><span class="tok-w"> </span>a2<span class="tok-w"> </span>:<span class="tok-w"> </span>a<span class="tok-w"> </span>:<span class="tok-w"> </span><span class="tok-na"><location></span>(bindir)<span class="tok-w"> </span><span class="tok-na"><staging-prefix></span>q<span class="tok-w"> </span>;<span class="tok-w"> </span><span class="tok-c1"># installs into q/bin</span></code></pre> 5097</div> 5098</div> 5099<div class="paragraph"> 5100<p>The feature is useful when you cannot (or don’t want to) put build artfiacts 5101into their intented locations during the build (such as when cross-compiling), 5102but still need to communicate those intended locations to the build system, 5103e.g. to generate configuration files.</p> 5104</div> 5105</dd> 5106<dt class="hdlist1"><a id="bbv2.builtin.features.stdlib"></a><code>stdlib</code></dt> 5107<dd> 5108<p><strong>Allowed values</strong>: <code>native</code>, <code>gnu</code>, <code>gnu11</code>, <code>libc++</code>, <code>sun-stlport</code>, <code>apache</code>.</p> 5109<div class="paragraph"> 5110<p>Specifies C++ standard library to link to and in some cases the library ABI to 5111use:</p> 5112</div> 5113<div class="dlist"> 5114<dl> 5115<dt class="hdlist1"><code>native</code></dt> 5116<dd> 5117<p>Use compiler’s default.</p> 5118</dd> 5119<dt class="hdlist1"><code>gnu</code></dt> 5120<dd> 5121<p>Use GNU Standard Library (a.k.a. libstdc++) with the old ABI.</p> 5122</dd> 5123<dt class="hdlist1"><code>gnu11</code></dt> 5124<dd> 5125<p>Use GNU Standard Library with the new ABI.</p> 5126</dd> 5127<dt class="hdlist1"><code>libc++</code></dt> 5128<dd> 5129<p>Use LLVM libc++.</p> 5130</dd> 5131<dt class="hdlist1"><code>sun-stlport</code></dt> 5132<dd> 5133<p>Use the STLport implementation of the standard library 5134provided with the Solaris Studio compiler.</p> 5135</dd> 5136<dt class="hdlist1"><code>apache</code></dt> 5137<dd> 5138<p>Use the Apache stdcxx version 4 C++ standard library provided with 5139the Solaris Studio compiler.</p> 5140</dd> 5141</dl> 5142</div> 5143</dd> 5144<dt class="hdlist1"><a id="bbv2.builtin.features.strip"></a><code>strip</code></dt> 5145<dd> 5146<p><strong>Allowed values:</strong> <code>off</code>, <code>on</code>.</p> 5147<div class="paragraph"> 5148<p>Controls whether the binary should be stripped — that is have everything not 5149necessary to running removed.</p> 5150</div> 5151<div class="admonitionblock note"> 5152<table> 5153<tr> 5154<td class="icon"> 5155<div class="title">ℹ</div> 5156</td> 5157<td class="content"> 5158This feature will show up in target paths of everything, not just 5159binaries. 5160</td> 5161</tr> 5162</table> 5163</div> 5164</dd> 5165<dt class="hdlist1"><a id="bbv2.builtin.features.suppress-import-lib"></a><code>suppress-import-lib</code></dt> 5166<dd> 5167<p>Suppresses creation of import library by the linker.</p> 5168</dd> 5169<dt class="hdlist1"><a id="bbv2.builtin.features.tag"></a><code>tag</code></dt> 5170<dd> 5171<p>Used to customize the name of the generated files. The value should have the 5172form:</p> 5173<div class="listingblock"> 5174<div class="content"> 5175<pre>@rulename</pre> 5176</div> 5177</div> 5178<div class="paragraph"> 5179<p>where <em>rulename</em> should be a name of a rule with the following signature:</p> 5180</div> 5181<div class="listingblock"> 5182<div class="content"> 5183<pre>rule tag ( name : type ? : property-set )</pre> 5184</div> 5185</div> 5186<div class="paragraph"> 5187<p>The rule will be called for each target with the default name computed by 5188B2, the type of the target, and property set. The rule can either 5189return a string that must be used as the name of the target, or an empty 5190string, in which case the default name will be used.</p> 5191</div> 5192<div class="paragraph"> 5193<p>Most typical use of the <code>tag</code> feature is to encode build properties, or library 5194version in library target names. You should take care to return non-empty 5195string from the tag rule only for types you care about — otherwise, you might 5196end up modifying names of object files, generated header file and other targets 5197for which changing names does not make sense.</p> 5198</div> 5199</dd> 5200<dt class="hdlist1"><a id="bbv2.builtin.features.target-os"></a><code>target-os</code></dt> 5201<dd> 5202<p><strong>Allowed values:</strong> <code>aix</code>, <code>android</code>, <code>appletv</code>, <code>bsd</code>, <code>cygwin</code>, <code>darwin</code>, 5203<code>freebsd</code>, <code>haiku</code>, <code>hpux</code>, <code>iphone</code>, <code>linux</code>, <code>netbsd</code>, <code>openbsd</code>, <code>osf</code>, 5204<code>qnx</code>, <code>qnxnto</code>, <code>sgi</code>, <code>solaris</code>, <code>unix</code>, <code>unixware</code>, <code>windows</code>, <code>vms</code>, 5205<code>vxworks</code>, <code>freertos</code>.</p> 5206<div class="paragraph"> 5207<p>Specifies the operating system for which the code is to be generated. The 5208compiler you used should be the compiler for that operating system. This option 5209causes B2 to use naming conventions suitable for that operating 5210system, and adjust build process accordingly. For example, with gcc, it 5211controls if import libraries are produced for shared libraries or not.</p> 5212</div> 5213<div class="paragraph"> 5214<p>See the section <a href="#bbv2.tasks.crosscompile">Cross-compilation</a> for details of cross-compilation.</p> 5215</div> 5216</dd> 5217<dt class="hdlist1"><a id="bbv2.builtin.features.threading"></a><code>threading</code></dt> 5218<dd> 5219<p><strong>Allowed values:</strong> <code>single</code>, <code>multi</code></p> 5220<div class="paragraph"> 5221<p>Controls if the project should be built in multi-threaded mode. This feature 5222does not necessary change code generation in the compiler, but it causes the 5223compiler to link to additional or different runtime libraries, and define 5224additional preprocessor symbols (for example, <code>_MT</code> on Windows and <code>_REENTRANT</code> 5225on Linux). How those symbols affect the compiled code depends on the code 5226itself.</p> 5227</div> 5228</dd> 5229<dt class="hdlist1"><a id="bbv2.builtin.features.thread-sanitizer"></a><code>thread-sanitizer</code></dt> 5230<dd> 5231<p><strong>Allowed values:</strong> <code>on</code>, <code>norecover</code>.</p> 5232<div class="paragraph"> 5233<p>Enables thread sanitizer. Value <code>norecover</code> disables recovery for the 5234sanitizer. The feature is optional, thus no sanitizer is enabled by default.</p> 5235</div> 5236</dd> 5237<dt class="hdlist1"><a id="bbv2.builtin.features.toolset"></a><code>toolset</code></dt> 5238<dd> 5239<p><strong>Allowed values:</strong> any of the toolset modules.</p> 5240<div class="paragraph"> 5241<p>Selects the toolset that will be used to build binary targets. The full list of 5242toolset modules is in the <a href="#bbv2.reference.tools">Builtin tools</a> section.</p> 5243</div> 5244</dd> 5245<dt class="hdlist1"><a id="bbv2.builtin.features.undef"></a><code>undef</code></dt> 5246<dd> 5247<p>Specifies a preprocessor symbol to undefine.</p> 5248</dd> 5249<dt class="hdlist1"><a id="bbv2.builtin.features.undefined-sanitizer"></a><code>undefined-sanitizer</code></dt> 5250<dd> 5251<p><strong>Allowed values:</strong> <code>on</code>, <code>norecover</code>.</p> 5252<div class="paragraph"> 5253<p>Enables undefined behavior sanitizer. Value <code>norecover</code> disables recovery for 5254the sanitizer. The feature is optional, thus no sanitizer is enabled by 5255default.</p> 5256</div> 5257</dd> 5258<dt class="hdlist1"><a id="bbv2.builtin.features.use"></a><code>use</code></dt> 5259<dd> 5260<p>Introduces a dependency on the target named by the value of this feature (so it 5261will be brought up-to-date whenever the target being declared is), and adds its 5262usage requirements to the build properties of the target being declared. The 5263dependency is not used in any other way. The primary use case is when you want 5264the usage requirements (such as <code>#include</code> paths) of some library to be 5265applied, but do not want to link to it.</p> 5266</dd> 5267<dt class="hdlist1"><a id="bbv2.builtin.features.user-interface"></a><code>user-interface</code></dt> 5268<dd> 5269<p><strong>Allowed values:</strong> <code>console</code>, <code>gui</code>, <code>wince</code>, <code>native</code>, <code>auto</code>.</p> 5270<div class="paragraph"> 5271<p>Specifies the environment for the executable which affects the entry point 5272symbol (or entry point function) that the linker will select. This feature is 5273Windows-specific.</p> 5274</div> 5275<div class="dlist"> 5276<dl> 5277<dt class="hdlist1"><code>console</code></dt> 5278<dd> 5279<p>console application.</p> 5280</dd> 5281<dt class="hdlist1"><code>gui</code></dt> 5282<dd> 5283<p>application does not require a console (it is supposed to create its 5284own windows.</p> 5285</dd> 5286<dt class="hdlist1"><code>wince</code></dt> 5287<dd> 5288<p>application is intended to run on a device that has a version of the 5289Windows CE kernel.</p> 5290</dd> 5291<dt class="hdlist1"><code>native</code></dt> 5292<dd> 5293<p>application runs without a subsystem environment.</p> 5294</dd> 5295<dt class="hdlist1"><code>auto</code></dt> 5296<dd> 5297<p>application runs in the POSIX subsystem in Windows.</p> 5298</dd> 5299</dl> 5300</div> 5301</dd> 5302<dt class="hdlist1"><a id="bbv2.builtin.features.variant"></a><code>variant</code></dt> 5303<dd> 5304<p><strong>Allowed values:</strong> <code>debug</code>, <code>release</code>, <code>profile</code>.</p> 5305<div class="paragraph"> 5306<p>A feature combining several low-level features, making it easy to 5307request common build configurations.</p> 5308</div> 5309<div class="paragraph"> 5310<p>The value <code>debug</code> expands to</p> 5311</div> 5312<div class="listingblock"> 5313<div class="content"> 5314<pre><optimization>off <debug-symbols>on <inlining>off <runtime-debugging>on</pre> 5315</div> 5316</div> 5317<div class="paragraph"> 5318<p>The value <code>release</code> expands to</p> 5319</div> 5320<div class="listingblock"> 5321<div class="content"> 5322<pre><optimization>speed <debug-symbols>off <inlining>full <runtime-debugging>off</pre> 5323</div> 5324</div> 5325<div class="paragraph"> 5326<p>The value <code>profile</code> expands to the same as <code>release</code>, plus:</p> 5327</div> 5328<div class="listingblock"> 5329<div class="content"> 5330<pre><profiling>on <debug-symbols>on</pre> 5331</div> 5332</div> 5333<div class="paragraph"> 5334<p>Users can define their own build variants using the <code>variant</code> rule 5335from the <code>common</code> module.</p> 5336</div> 5337<div class="admonitionblock note"> 5338<table> 5339<tr> 5340<td class="icon"> 5341<div class="title">ℹ</div> 5342</td> 5343<td class="content"> 5344Runtime debugging is on in debug builds to suit the expectations of 5345people used to various IDEs. 5346</td> 5347</tr> 5348</table> 5349</div> 5350</dd> 5351<dt class="hdlist1"><a id="bbv2.builtin.features.vectorize"></a><code>vectorize</code></dt> 5352<dd> 5353<p><strong>Allowed values:</strong> <code>off</code>, <code>on</code>, <code>full</code>.</p> 5354<div class="paragraph"> 5355<p>Enables vectorization.</p> 5356</div> 5357</dd> 5358<dt class="hdlist1"><a id="bbv2.builtin.features.version"></a><code>version</code></dt> 5359<dd> 5360<p>This feature isn’t used by any of the builtin tools, but can be used, for 5361example, to adjust target’s name via <a href="#bbv2.builtin.features.tag"><code><tag></code></a> 5362feature.</p> 5363</dd> 5364<dt class="hdlist1"><a id="bbv2.builtin.features.visibility"></a><code>visibility</code></dt> 5365<dd> 5366<p><strong>Allowed values:</strong> <code>global</code>, <code>protected</code>, <code>hidden</code>.</p> 5367<div class="paragraph"> 5368<p>Specifies the default symbol visibility in compiled binaries. Not all values 5369are supported on all platforms and on some platforms (for example, Windows) 5370symbol visibility is not supported at all.</p> 5371</div> 5372<div class="paragraph"> 5373<p>The supported values have the following meaning:</p> 5374</div> 5375<div class="dlist"> 5376<dl> 5377<dt class="hdlist1"><code>global</code></dt> 5378<dd> 5379<p>a.k.a. "default" in gcc documentation. Global symbols are 5380considered public, they are exported from shared libraries and can be 5381redefined by another shared library or executable.</p> 5382</dd> 5383<dt class="hdlist1"><code>protected</code></dt> 5384<dd> 5385<p>a.k.a. "symbolic". Protected symbols are exported from shared 5386ibraries but cannot be redefined by another shared library or executable. 5387This mode is not supported on some platforms, for example OS X.</p> 5388</dd> 5389<dt class="hdlist1"><code>hidden</code></dt> 5390<dd> 5391<p>Hidden symbols are not exported from shared libraries and cannot 5392be redefined by a different shared library or executable loaded in a process. 5393In this mode, public symbols have to be explicitly marked in the source code 5394to be exported from shared libraries. This is the recommended mode.</p> 5395<div class="paragraph"> 5396<p>By default compiler default visibility mode is used (no compiler flags are 5397added).</p> 5398</div> 5399<div class="admonitionblock note"> 5400<table> 5401<tr> 5402<td class="icon"> 5403<div class="title">ℹ</div> 5404</td> 5405<td class="content"> 5406In Boost super-project Jamroot file this property is set to the default 5407value of <code>hidden</code>. This means that Boost libraries are built with hidden 5408visibility by default, unless the user overrides it with a different 5409<code>visibility</code> or a library sets a different <code>local-visibility</code> (see below). 5410</td> 5411</tr> 5412</table> 5413</div> 5414</dd> 5415</dl> 5416</div> 5417</dd> 5418<dt class="hdlist1"><a id="bbv2.builtin.features.warnings"></a><code>warnings</code></dt> 5419<dd> 5420<p><strong>Allowed values:</strong> <code>on</code>, <code>all</code>, <code>extra</code>, <code>pedantic</code>, <code>off</code>.</p> 5421<div class="paragraph"> 5422<p>Controls the warning level of compilers.</p> 5423</div> 5424<div class="dlist"> 5425<dl> 5426<dt class="hdlist1"><code>on</code></dt> 5427<dd> 5428<p>enable default/"reasonable" warning level.</p> 5429</dd> 5430<dt class="hdlist1"><code>all</code></dt> 5431<dd> 5432<p>enable most warnings.</p> 5433</dd> 5434<dt class="hdlist1"><code>extra</code></dt> 5435<dd> 5436<p>enable extra, possibly conflicting, warnings.</p> 5437</dd> 5438<dt class="hdlist1"><code>pedantic</code></dt> 5439<dd> 5440<p>enable likely inconsequential, and conflicting, warnings.</p> 5441</dd> 5442<dt class="hdlist1"><code>off</code></dt> 5443<dd> 5444<p>disable all warnings.</p> 5445<div class="paragraph"> 5446<p>Default value is <code>all</code>.</p> 5447</div> 5448</dd> 5449</dl> 5450</div> 5451</dd> 5452<dt class="hdlist1"><a id="bbv2.builtin.features.warnings-as-errors"></a><code>warnings-as-errors</code></dt> 5453<dd> 5454<p><strong>Allowed values:</strong> <code>off</code>, <code>on</code>.</p> 5455<div class="paragraph"> 5456<p>Makes it possible to treat warnings as errors and abort compilation on a 5457warning.</p> 5458</div> 5459</dd> 5460<dt class="hdlist1"><a id="bbv2.builtin.features.translate-path"></a><code>translate-path</code></dt> 5461<dd> 5462<p>Used to introduce custom path feature translation. The value should have the 5463form:</p> 5464<div class="listingblock"> 5465<div class="content"> 5466<pre>@rulename</pre> 5467</div> 5468</div> 5469<div class="paragraph"> 5470<p>where <em>rulename</em> should be a name of a rule with the following signature:</p> 5471</div> 5472<div class="listingblock"> 5473<div class="content"> 5474<pre>rule rulename ( feature value : properties * : project-id : project-location )</pre> 5475</div> 5476</div> 5477<div class="paragraph"> 5478<p>The rule is called for each target with the <code>feature</code> of a path property, 5479the path property value, target properties, the target project ID, and 5480the target project location. It should return the translated path value. 5481Or return nothing if it doesn’t do path translation. Leaving it do the 5482default path translation.</p> 5483</div> 5484</dd> 5485<dt class="hdlist1"><a id="bbv2.builtin.features.lto"></a><code>lto</code></dt> 5486<dd> 5487<p><strong>Allowed values:</strong> <code>on</code>.</p> 5488<div class="paragraph"> 5489<p>Enables link time optimizations (also known as interprocedural optimizations or 5490whole-program optimizations). Currently supported toolsets are <a href="#bbv2.reference.tools.compiler.gcc">GNU C++</a>, 5491clang and <a href="#bbv2.reference.tools.compiler.msvc">Microsoft Visual C++</a>. The feature is optional.</p> 5492</div> 5493</dd> 5494<dt class="hdlist1"><a id="bbv2.builtin.features.lto-mode"></a><code>lto-mode</code></dt> 5495<dd> 5496<p><strong>Subfeature of</strong> <code>lto</code></p> 5497<div class="paragraph"> 5498<p><strong>Allowed values:</strong> <code>full</code>, <code>thin</code>, <code>fat</code>.</p> 5499</div> 5500<div class="paragraph"> 5501<p>Specifies the type of LTO to use.</p> 5502</div> 5503<div class="dlist"> 5504<dl> 5505<dt class="hdlist1"><code>full</code></dt> 5506<dd> 5507<p>Use the monolithic LTO: on linking all input is merged into a single 5508module.</p> 5509</dd> 5510<dt class="hdlist1"><code>thin</code></dt> 5511<dd> 5512<p>Use clang’s ThinLTO: each compiled file contains a summary of the 5513module, these summaries are merged into a single index. This allows to avoid 5514merging all modules together, which greatly reduces linking time.</p> 5515</dd> 5516<dt class="hdlist1"><code>fat</code></dt> 5517<dd> 5518<p>Produce gcc’s fat LTO objects: compiled files contain both the 5519intermidiate language suitable for LTO and object code suitable for regular 5520linking.</p> 5521</dd> 5522</dl> 5523</div> 5524</dd> 5525</dl> 5526</div> 5527</div> 5528<div class="sect2"> 5529<h3 id="bbv2.reference.tools"><a class="anchor" href="#bbv2.reference.tools"></a>5.4. Builtin tools</h3> 5530<div class="paragraph"> 5531<p>B2 comes with support for a large number of C++ compilers, and 5532other tools. This section documents how to use those tools.</p> 5533</div> 5534<div class="paragraph"> 5535<p>Before using any tool, you must declare your intention, and possibly 5536specify additional information about the tool’s configuration. This is 5537done by calling the <code>using</code> rule, typically in your <code>user-config.jam</code>, 5538for example:</p> 5539</div> 5540<div class="listingblock"> 5541<div class="content"> 5542<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-nb">using</span><span class="tok-w"> </span>gcc<span class="tok-w"> </span>;<span class="tok-w"></span></code></pre> 5543</div> 5544</div> 5545<div class="paragraph"> 5546<p>additional parameters can be passed just like for other rules, for 5547example:</p> 5548</div> 5549<div class="listingblock"> 5550<div class="content"> 5551<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-nb">using</span><span class="tok-w"> </span>gcc<span class="tok-w"> </span>:<span class="tok-w"> </span>4.0<span class="tok-w"> </span>:<span class="tok-w"> </span>g++-4.0<span class="tok-w"> </span>;<span class="tok-w"></span></code></pre> 5552</div> 5553</div> 5554<div class="paragraph"> 5555<p>The options that can be passed to each tool are documented in the 5556subsequent sections.</p> 5557</div> 5558<div class="sect3"> 5559<h4 id="bbv2.reference.tools.compilers"><a class="anchor" href="#bbv2.reference.tools.compilers"></a>5.4.1. C++ Compilers</h4> 5560<div class="paragraph"> 5561<p>This section lists all B2 modules that support C++ compilers 5562and documents how each one can be initialized. The name of support 5563module for compiler is also the value for the <code>toolset</code> feature that can 5564be used to explicitly request that compiler.</p> 5565</div> 5566<div class="sect4"> 5567<h5 id="bbv2.reference.tools.compiler.acc"><a class="anchor" href="#bbv2.reference.tools.compiler.acc"></a>HP aC++ compiler</h5> 5568<div class="paragraph"> 5569<p>The <code>acc</code> module supports the 5570<a href="http://h21007.www2.hp.com/dspp/tech/tech_TechSoftwareDetailPage_IDX/1,1703,1740,00.html">HP 5571aC++ compiler</a> for the HP-UX operating system.</p> 5572</div> 5573<div class="paragraph"> 5574<p>The module is initialized using the following syntax:</p> 5575</div> 5576<div class="listingblock"> 5577<div class="content"> 5578<pre>using acc : [version] : [c++-compile-command] : [compiler options] ;</pre> 5579</div> 5580</div> 5581<div class="paragraph"> 5582<p>This statement may be repeated several times, if you want to configure 5583several versions of the compiler.</p> 5584</div> 5585<div class="paragraph"> 5586<p>If the command is not specified, the <code>aCC</code> binary will be searched in 5587PATH.</p> 5588</div> 5589<div class="paragraph"> 5590<p>The following options can be provided, using 5591<em>`<option-name>option-value syntax`</em>:</p> 5592</div> 5593<div class="dlist"> 5594<dl> 5595<dt class="hdlist1"><code>cflags</code></dt> 5596<dd> 5597<p>Specifies additional compiler flags that will be used when compiling C 5598sources.</p> 5599</dd> 5600<dt class="hdlist1"><code>cxxflags</code></dt> 5601<dd> 5602<p>Specifies additional compiler flags that will be used when compiling C++ 5603sources.</p> 5604</dd> 5605<dt class="hdlist1"><code>compileflags</code></dt> 5606<dd> 5607<p>Specifies additional compiler flags that will be used when compiling both C 5608and C++ sources.</p> 5609</dd> 5610<dt class="hdlist1"><code>linkflags</code></dt> 5611<dd> 5612<p>Specifies additional command line options that will be passed to the linker.</p> 5613</dd> 5614</dl> 5615</div> 5616</div> 5617<div class="sect4"> 5618<h5 id="bbv2.reference.tools.compiler.borland"><a class="anchor" href="#bbv2.reference.tools.compiler.borland"></a>Borland C++ Compiler</h5> 5619<div class="paragraph"> 5620<p>The <code>borland</code> module supports the 32-bit command line C compilers 5621running on Microsoft Windows. This is the bcc32 executable for all 5622versions of Borland C and C Builder, as well as the command line 5623compatible compiler bcc32c on later versions of C Builder.</p> 5624</div> 5625<div class="paragraph"> 5626<p>The module is initialized using the following syntax:</p> 5627</div> 5628<div class="listingblock"> 5629<div class="content"> 5630<pre>using borland : [version] : [c++-compile-command] : [compiler options] ;</pre> 5631</div> 5632</div> 5633<div class="paragraph"> 5634<p>This statement may be repeated several times, if you want to configure 5635several versions of the compiler.</p> 5636</div> 5637<div class="paragraph"> 5638<p>If the command is not specified, Boost.Build will search for a binary 5639named <code>bcc32</code> in PATH.</p> 5640</div> 5641<div class="paragraph"> 5642<p>The following options can be provided, using 5643<em>`<option-name>option-value syntax`</em>:</p> 5644</div> 5645<div class="dlist"> 5646<dl> 5647<dt class="hdlist1"><code>cflags</code></dt> 5648<dd> 5649<p>Specifies additional compiler flags that will be used when compiling C 5650sources.</p> 5651</dd> 5652<dt class="hdlist1"><code>cxxflags</code></dt> 5653<dd> 5654<p>Specifies additional compiler flags that will be used when compiling C++ 5655sources.</p> 5656</dd> 5657<dt class="hdlist1"><code>compileflags</code></dt> 5658<dd> 5659<p>Specifies additional compiler flags that will be used when compiling both C 5660and C++ sources.</p> 5661</dd> 5662<dt class="hdlist1"><code>linkflags</code></dt> 5663<dd> 5664<p>Specifies additional command line options that will be passed to the linker.</p> 5665</dd> 5666<dt class="hdlist1"><code>user-interface</code></dt> 5667<dd> 5668<p>Specifies the user interface for applications. Valid choices are <code>console</code> 5669for a console applicatiuon and <code>gui</code> for a Windows application.</p> 5670</dd> 5671</dl> 5672</div> 5673</div> 5674<div class="sect4"> 5675<h5 id="bbv2.reference.tools.compiler.como"><a class="anchor" href="#bbv2.reference.tools.compiler.como"></a>Comeau C/C++ Compiler</h5> 5676<div class="paragraph"> 5677<p>The <code>como-linux</code> and the <code>como-win</code> modules supports the 5678<a href="http://www.comeaucomputing.com/">Comeau C/C++ Compiler</a> on Linux and 5679Windows respectively.</p> 5680</div> 5681<div class="paragraph"> 5682<p>The module is initialized using the following syntax:</p> 5683</div> 5684<div class="listingblock"> 5685<div class="content"> 5686<pre>using como : [version] : [c++-compile-command] : [compiler options] ;</pre> 5687</div> 5688</div> 5689<div class="paragraph"> 5690<p>This statement may be repeated several times, if you want to configure 5691several versions of the compiler.</p> 5692</div> 5693<div class="paragraph"> 5694<p>If the command is not specified, B2 will search for a binary 5695named <code>como</code> in PATH.</p> 5696</div> 5697<div class="paragraph"> 5698<p>The following options can be provided, using 5699<em>`<option-name>option-value syntax`</em>:</p> 5700</div> 5701<div class="dlist"> 5702<dl> 5703<dt class="hdlist1"><code>cflags</code></dt> 5704<dd> 5705<p>Specifies additional compiler flags that will be used when compiling C 5706sources.</p> 5707</dd> 5708<dt class="hdlist1"><code>cxxflags</code></dt> 5709<dd> 5710<p>Specifies additional compiler flags that will be used when compiling C++ 5711sources.</p> 5712</dd> 5713<dt class="hdlist1"><code>compileflags</code></dt> 5714<dd> 5715<p>Specifies additional compiler flags that will be used when compiling both C 5716and C++ sources.</p> 5717</dd> 5718<dt class="hdlist1"><code>linkflags</code></dt> 5719<dd> 5720<p>Specifies additional command line options that will be passed to the linker.</p> 5721</dd> 5722</dl> 5723</div> 5724<div class="paragraph"> 5725<p>Before using the Windows version of the compiler, you need to setup 5726necessary environment variables per compiler’s documentation. In 5727particular, the COMO_XXX_INCLUDE variable should be set, where XXX 5728corresponds to the used backend C compiler.</p> 5729</div> 5730</div> 5731<div class="sect4"> 5732<h5 id="bbv2.reference.tools.compiler.cw"><a class="anchor" href="#bbv2.reference.tools.compiler.cw"></a>Code Warrior</h5> 5733<div class="paragraph"> 5734<p>The <code>cw</code> module support CodeWarrior compiler, originally produced by 5735Metrowerks and presently developed by Freescale. B2 supports 5736only the versions of the compiler that target x86 processors. All such 5737versions were released by Metrowerks before acquisition and are not sold 5738any longer. The last version known to work is 9.4.</p> 5739</div> 5740<div class="paragraph"> 5741<p>The module is initialized using the following syntax:</p> 5742</div> 5743<div class="listingblock"> 5744<div class="content"> 5745<pre>using cw : [version] : [c++-compile-command] : [compiler options] ;</pre> 5746</div> 5747</div> 5748<div class="paragraph"> 5749<p>This statement may be repeated several times, if you want to configure 5750several versions of the compiler.</p> 5751</div> 5752<div class="paragraph"> 5753<p>If the command is not specified, B2 will search for a binary 5754named <code>mwcc</code> in default installation paths and in PATH.</p> 5755</div> 5756<div class="paragraph"> 5757<p>The following options can be provided, using 5758<em>`<option-name>option-value syntax`</em>:</p> 5759</div> 5760<div class="dlist"> 5761<dl> 5762<dt class="hdlist1"><code>cflags</code></dt> 5763<dd> 5764<p>Specifies additional compiler flags that will be used when compiling C 5765sources.</p> 5766</dd> 5767<dt class="hdlist1"><code>cxxflags</code></dt> 5768<dd> 5769<p>Specifies additional compiler flags that will be used when compiling C++ 5770sources.</p> 5771</dd> 5772<dt class="hdlist1"><code>compileflags</code></dt> 5773<dd> 5774<p>Specifies additional compiler flags that will be used when compiling both C 5775and C++ sources.</p> 5776</dd> 5777<dt class="hdlist1"><code>linkflags</code></dt> 5778<dd> 5779<p>Specifies additional command line options that will be passed to the linker.</p> 5780</dd> 5781<dt class="hdlist1"><code>setup</code></dt> 5782<dd> 5783<p>The command that sets up environment variables prior to invoking the 5784compiler. If not specified, <code>cwenv.bat</code> alongside the compiler binary 5785will be used.</p> 5786</dd> 5787<dt class="hdlist1"><code>compiler</code></dt> 5788<dd> 5789<p>The command that compiles C and C++ sources. If not specified, <code>mwcc</code> 5790will be used. The command will be invoked after the setup script was 5791executed and adjusted the PATH variable.</p> 5792</dd> 5793<dt class="hdlist1"><code>linker</code></dt> 5794<dd> 5795<p>The command that links executables and dynamic libraries. If not 5796specified, <code>mwld</code> will be used. The command will be invoked after the 5797setup script was executed and adjusted the PATH variable.</p> 5798</dd> 5799</dl> 5800</div> 5801</div> 5802<div class="sect4"> 5803<h5 id="bbv2.reference.tools.compiler.dmc"><a class="anchor" href="#bbv2.reference.tools.compiler.dmc"></a>Digital Mars C/C++ Compiler</h5> 5804<div class="paragraph"> 5805<p>The <code>dmc</code> module supports the <a href="http://www.digitalmars.com/">Digital Mars 5806C++ compiler.</a></p> 5807</div> 5808<div class="paragraph"> 5809<p>The module is initialized using the following syntax:</p> 5810</div> 5811<div class="listingblock"> 5812<div class="content"> 5813<pre>using dmc : [version] : [c++-compile-command] : [compiler options] ;</pre> 5814</div> 5815</div> 5816<div class="paragraph"> 5817<p>This statement may be repeated several times, if you want to configure 5818several versions of the compiler.</p> 5819</div> 5820<div class="paragraph"> 5821<p>If the command is not specified, B2 will search for a binary 5822named <code>dmc</code> in PATH.</p> 5823</div> 5824<div class="paragraph"> 5825<p>The following options can be provided, using 5826<em>`<option-name>option-value syntax`</em>:</p> 5827</div> 5828<div class="dlist"> 5829<dl> 5830<dt class="hdlist1"><code>cflags</code></dt> 5831<dd> 5832<p>Specifies additional compiler flags that will be used when compiling C 5833sources.</p> 5834</dd> 5835<dt class="hdlist1"><code>cxxflags</code></dt> 5836<dd> 5837<p>Specifies additional compiler flags that will be used when compiling C++ 5838sources.</p> 5839</dd> 5840<dt class="hdlist1"><code>compileflags</code></dt> 5841<dd> 5842<p>Specifies additional compiler flags that will be used when compiling both C 5843and C++ sources.</p> 5844</dd> 5845<dt class="hdlist1"><code>linkflags</code></dt> 5846<dd> 5847<p>Specifies additional command line options that will be passed to the linker.</p> 5848</dd> 5849</dl> 5850</div> 5851</div> 5852<div class="sect4"> 5853<h5 id="bbv2.reference.tools.compiler.gcc"><a class="anchor" href="#bbv2.reference.tools.compiler.gcc"></a>GNU C++</h5> 5854<div class="paragraph"> 5855<p>The <code>gcc</code> module supports the <a href="http://gcc.gnu.org">GNU C++ compiler</a> on 5856Linux, a number of Unix-like system including SunOS and on Windows 5857(either <a href="http://www.cygwin.com">Cygwin</a> or <a href="http://www.mingw.org">MinGW</a>).</p> 5858</div> 5859<div class="paragraph"> 5860<p>The <code>gcc</code> module is initialized using the following syntax:</p> 5861</div> 5862<div class="listingblock"> 5863<div class="content"> 5864<pre>using gcc : [version] : [c++-compile-command] : [compiler options] ;</pre> 5865</div> 5866</div> 5867<div class="paragraph"> 5868<p>This statement may be repeated several times, if you want to configure 5869several versions of the compiler.</p> 5870</div> 5871<div class="paragraph"> 5872<p>If the version is not explicitly specified, it will be automatically 5873detected by running the compiler with the <code>-v</code> option. If the command is 5874not specified, the <code>g++</code> binary will be searched in PATH.</p> 5875</div> 5876<div class="paragraph"> 5877<p>The following options can be provided, using 5878<em>`<option-name>option-value syntax`</em>:</p> 5879</div> 5880<div class="dlist"> 5881<dl> 5882<dt class="hdlist1"><code>cflags</code></dt> 5883<dd> 5884<p>Specifies additional compiler flags that will be used when compiling C 5885sources.</p> 5886</dd> 5887<dt class="hdlist1"><code>cxxflags</code></dt> 5888<dd> 5889<p>Specifies additional compiler flags that will be used when compiling C++ 5890sources.</p> 5891</dd> 5892<dt class="hdlist1"><code>compileflags</code></dt> 5893<dd> 5894<p>Specifies additional compiler flags that will be used when compiling both C 5895and C++ sources.</p> 5896</dd> 5897<dt class="hdlist1"><code>linkflags</code></dt> 5898<dd> 5899<p>Specifies additional command line options that will be passed to the linker.</p> 5900</dd> 5901<dt class="hdlist1"><code>root</code></dt> 5902<dd> 5903<p>Specifies root directory of the compiler installation. This option is 5904necessary only if it is not possible to detect this information from the 5905compiler command—​for example if the specified compiler command is a user 5906script.</p> 5907</dd> 5908<dt class="hdlist1"><code>archiver</code></dt> 5909<dd> 5910<p>Specifies the archiver command that is used to produce static 5911libraries. Normally, it is autodetected using gcc <code>-print-prog-name</code> 5912option or defaulted to <code>ar</code>, but in some cases you might want to 5913override it, for example to explicitly use a system version instead of 5914one included with gcc.</p> 5915</dd> 5916<dt class="hdlist1"><code>ranlib</code></dt> 5917<dd> 5918<p>Specifies the ranlib command that is used to generated symbol table 5919for static libraries. Normally, it is autodetected using gcc 5920<code>-print-prog-name</code> option or defaulted to <code>ranlib</code>, but in some cases 5921you might want to override it, for example to explicitly use a system 5922version instead of one included with gcc.</p> 5923</dd> 5924<dt class="hdlist1"><code>rc</code></dt> 5925<dd> 5926<p>Specifies the resource compiler command that will be used with the 5927version of gcc that is being configured. This setting makes sense only 5928for Windows and only if you plan to use resource files. By default 5929<code>windres</code> will be used.</p> 5930</dd> 5931<dt class="hdlist1"><code>rc-type</code></dt> 5932<dd> 5933<p>Specifies the type of resource compiler. The value can be either 5934<code>windres</code> for msvc resource compiler, or <code>rc</code> for borland’s resource 5935compiler.</p> 5936</dd> 5937</dl> 5938</div> 5939<div class="paragraph"> 5940<p>In order to compile 64-bit applications, you have to specify 5941<code>address-model=64</code>, and the <code>instruction-set</code> feature should refer to a 64 5942bit processor. Currently, those include <code>nocona</code>, <code>opteron</code>, <code>athlon64</code> and 5943<code>athlon-fx</code>.</p> 5944</div> 5945</div> 5946<div class="sect4"> 5947<h5 id="bbv2.reference.tools.compiler.hp_cxx"><a class="anchor" href="#bbv2.reference.tools.compiler.hp_cxx"></a>HP C++ Compiler for Tru64 Unix</h5> 5948<div class="paragraph"> 5949<p>The <code>hp_cxx</code> modules supports the 5950<a href="http://h30097.www3.hp.com/cplus/?jumpid=reg_R1002_USEN">HP C++ Compiler</a> 5951for Tru64 Unix.</p> 5952</div> 5953<div class="paragraph"> 5954<p>The module is initialized using the following syntax:</p> 5955</div> 5956<div class="listingblock"> 5957<div class="content"> 5958<pre>using hp_cxx : [version] : [c++-compile-command] : [compiler options] ;</pre> 5959</div> 5960</div> 5961<div class="paragraph"> 5962<p>This statement may be repeated several times, if you want to configure 5963several versions of the compiler.</p> 5964</div> 5965<div class="paragraph"> 5966<p>If the command is not specified, B2 will search for a binary 5967named <code>hp_cxx</code> in PATH.</p> 5968</div> 5969<div class="paragraph"> 5970<p>The following options can be provided, using 5971<em>`<option-name>option-value syntax`</em>:</p> 5972</div> 5973<div class="dlist"> 5974<dl> 5975<dt class="hdlist1"><code>cflags</code></dt> 5976<dd> 5977<p>Specifies additional compiler flags that will be used when compiling C 5978sources.</p> 5979</dd> 5980<dt class="hdlist1"><code>cxxflags</code></dt> 5981<dd> 5982<p>Specifies additional compiler flags that will be used when compiling C++ 5983sources.</p> 5984</dd> 5985<dt class="hdlist1"><code>compileflags</code></dt> 5986<dd> 5987<p>Specifies additional compiler flags that will be used when compiling both C 5988and C++ sources.</p> 5989</dd> 5990<dt class="hdlist1"><code>linkflags</code></dt> 5991<dd> 5992<p>Specifies additional command line options that will be passed to the linker.</p> 5993</dd> 5994</dl> 5995</div> 5996</div> 5997<div class="sect4"> 5998<h5 id="bbv2.reference.tools.compiler.intel"><a class="anchor" href="#bbv2.reference.tools.compiler.intel"></a>Intel C++</h5> 5999<div class="paragraph"> 6000<p>The <code>intel-*</code> modules support the Intel C++ command-line compiler.</p> 6001</div> 6002<div class="paragraph"> 6003<p>The module is initialized using the following syntax:</p> 6004</div> 6005<div class="listingblock"> 6006<div class="content"> 6007<pre>using intel : [version] : [c++-compile-command] : [compiler options] ;</pre> 6008</div> 6009</div> 6010<div class="paragraph"> 6011<p>This statement may be repeated several times, if you want to configure 6012several versions of the compiler.</p> 6013</div> 6014<div class="paragraph"> 6015<p>If compiler command is not specified, then B2 will look in PATH 6016for an executable <code>icpc</code> (on Linux), or <code>icl.exe</code> (on Windows).</p> 6017</div> 6018<div class="paragraph"> 6019<p>The following options can be provided, using 6020<em>`<option-name>option-value syntax`</em>:</p> 6021</div> 6022<div class="dlist"> 6023<dl> 6024<dt class="hdlist1"><code>cflags</code></dt> 6025<dd> 6026<p>Specifies additional compiler flags that will be used when compiling C 6027sources.</p> 6028</dd> 6029<dt class="hdlist1"><code>cxxflags</code></dt> 6030<dd> 6031<p>Specifies additional compiler flags that will be used when compiling C++ 6032sources.</p> 6033</dd> 6034<dt class="hdlist1"><code>compileflags</code></dt> 6035<dd> 6036<p>Specifies additional compiler flags that will be used when compiling both C 6037and C++ sources.</p> 6038</dd> 6039<dt class="hdlist1"><code>linkflags</code></dt> 6040<dd> 6041<p>Specifies additional command line options that will be passed to the linker.</p> 6042</dd> 6043<dt class="hdlist1"><code>root</code></dt> 6044<dd> 6045<p>For the Linux version, specifies the root directory of the compiler installation. 6046This option is necessary only if it is not possible to detect this information 6047from the compiler command — for example if the specified compiler command is 6048a user script. For the Windows version, specifies the directory where the 6049<code>iclvars.bat</code> file for configuring the compiler exists. Specifying the <code>root</code> 6050option without specifying the compiler command allows the end-user not to have 6051to worry about whether he is compiling 32-bit or 64-bit code, as the toolset will 6052automatically configure the compiler for the appropriate address model and compiler 6053command using the <code>iclvars.bat</code> batch file.</p> 6054</dd> 6055</dl> 6056</div> 6057</div> 6058<div class="sect4"> 6059<h5 id="bbv2.reference.tools.compiler.msvc"><a class="anchor" href="#bbv2.reference.tools.compiler.msvc"></a>Microsoft Visual C++</h5> 6060<div class="paragraph"> 6061<p>The <code>msvc</code> module supports the 6062<a href="http://msdn.microsoft.com/visualc/">Microsoft Visual C++</a> command-line 6063tools on Microsoft Windows. The supported products and versions of 6064command line tools are listed below:</p> 6065</div> 6066<div class="ulist"> 6067<ul> 6068<li> 6069<p>Visual Studio 2019-14.2</p> 6070</li> 6071<li> 6072<p>Visual Studio 2017—14.1</p> 6073</li> 6074<li> 6075<p>Visual Studio 2015—14.0</p> 6076</li> 6077<li> 6078<p>Visual Studio 2013—12.0</p> 6079</li> 6080<li> 6081<p>Visual Studio 2012—11.0</p> 6082</li> 6083<li> 6084<p>Visual Studio 2010—10.0</p> 6085</li> 6086<li> 6087<p>Visual Studio 2008—9.0</p> 6088</li> 6089<li> 6090<p>Visual Studio 2005—8.0</p> 6091</li> 6092<li> 6093<p>Visual Studio .NET 2003—7.1</p> 6094</li> 6095<li> 6096<p>Visual Studio .NET—7.0</p> 6097</li> 6098<li> 6099<p>Visual Studio 6.0, Service Pack 5—​6.5</p> 6100</li> 6101</ul> 6102</div> 6103<div class="paragraph"> 6104<p>The user would then call the boost build executable with the toolset set 6105equal to <code>msvc-[version number]</code> for example to build with Visual Studio 61062019 one could run:</p> 6107</div> 6108<div class="listingblock"> 6109<div class="content"> 6110<pre>.\b2 toolset=msvc-14.2 target</pre> 6111</div> 6112</div> 6113<div class="paragraph"> 6114<p>The <code>msvc</code> module is initialized using the following syntax:</p> 6115</div> 6116<div class="listingblock"> 6117<div class="content"> 6118<pre>using msvc : [version] : [c++-compile-command] : [compiler options] ;</pre> 6119</div> 6120</div> 6121<div class="paragraph"> 6122<p>This statement may be repeated several times, if you want to configure 6123several versions of the compiler.</p> 6124</div> 6125<div class="paragraph"> 6126<p>If the version is not explicitly specified, the most recent version 6127found in the registry will be used instead. If the special value <code>all</code> 6128is passed as the version, all versions found in the registry will be 6129configured. If a version is specified, but the command is not, the 6130compiler binary will be searched in standard installation paths for that 6131version, followed by PATH.</p> 6132</div> 6133<div class="paragraph"> 6134<p>The compiler command should be specified using forward slashes, and 6135quoted.</p> 6136</div> 6137<div class="paragraph"> 6138<p>The following options can be provided, using 6139<em>`<option-name>option-value syntax`</em>:</p> 6140</div> 6141<div class="dlist"> 6142<dl> 6143<dt class="hdlist1"><code>cflags</code></dt> 6144<dd> 6145<p>Specifies additional compiler flags that will be used when compiling C 6146sources.</p> 6147</dd> 6148<dt class="hdlist1"><code>cxxflags</code></dt> 6149<dd> 6150<p>Specifies additional compiler flags that will be used when compiling C++ 6151sources.</p> 6152</dd> 6153<dt class="hdlist1"><code>compileflags</code></dt> 6154<dd> 6155<p>Specifies additional compiler flags that will be used when compiling both C 6156and C++ sources.</p> 6157</dd> 6158<dt class="hdlist1"><code>linkflags</code></dt> 6159<dd> 6160<p>Specifies additional command line options that will be passed to the linker.</p> 6161</dd> 6162<dt class="hdlist1"><code>assembler</code></dt> 6163<dd> 6164<p>The command that compiles assembler sources. If not specified, <code>ml</code> 6165will be used. The command will be invoked after the setup script was 6166executed and adjusted the PATH variable.</p> 6167</dd> 6168<dt class="hdlist1"><code>compiler</code></dt> 6169<dd> 6170<p>The command that compiles C and C++ sources. If not specified, <code>cl</code> 6171will be used. The command will be invoked after the setup script was 6172executed and adjusted the PATH variable.</p> 6173</dd> 6174<dt class="hdlist1"><code>compiler-filter</code></dt> 6175<dd> 6176<p>Command through which to pipe the output of running the compiler. For 6177 example to pass the output to STLfilt.</p> 6178</dd> 6179<dt class="hdlist1"><code>idl-compiler</code></dt> 6180<dd> 6181<p>The command that compiles Microsoft COM interface definition files. If 6182not specified, <code>midl</code> will be used. The command will be invoked after 6183the setup script was executed and adjusted the PATH variable.</p> 6184</dd> 6185<dt class="hdlist1"><code>linker</code></dt> 6186<dd> 6187<p>The command that links executables and dynamic libraries. If not 6188specified, <code>link</code> will be used. The command will be invoked after the 6189setup script was executed and adjusted the PATH variable.</p> 6190</dd> 6191<dt class="hdlist1"><code>mc-compiler</code></dt> 6192<dd> 6193<p>The command that compiles Microsoft message catalog files. If not 6194specified, <code>mc</code> will be used. The command will be invoked after the 6195setup script was executed and adjusted the PATH variable.</p> 6196</dd> 6197<dt class="hdlist1"><code>resource-compiler</code></dt> 6198<dd> 6199<p>The command that compiles resource files. If not specified, <code>rc</code> will 6200be used. The command will be invoked after the setup script was 6201executed and adjusted the PATH variable.</p> 6202</dd> 6203<dt class="hdlist1"><code>setup</code></dt> 6204<dd> 6205<p>The filename of the global environment setup script to run before 6206invoking any of the tools defined in this toolset. Will not be used in 6207case a target platform specific script has been explicitly specified 6208for the current target platform. Used setup script will be passed the 6209target platform identifier (x86, x86_amd64, x86_ia64, amd64 or ia64) 6210as a parameter. If not specified a default script is chosen based on 6211the used compiler binary, e.g. <code>vcvars32.bat</code> or <code>vsvars32.bat</code>.</p> 6212</dd> 6213<dt class="hdlist1"><code>setup-amd64</code>; <code>setup-i386</code>; <code>setup-ia64</code></dt> 6214<dd> 6215<p>The filename of the target platform specific environment setup script 6216to run before invoking any of the tools defined in this toolset. If 6217not specified the global environment setup script is used.</p> 6218</dd> 6219</dl> 6220</div> 6221<div class="sect5"> 6222<h6 id="bbv2.reference.tools.compiler.msvc.64"><a class="anchor" href="#bbv2.reference.tools.compiler.msvc.64"></a>64-bit support</h6> 6223<div class="paragraph"> 6224<p>Starting with version 8.0, Microsoft Visual Studio can generate binaries 6225for 64-bit processor, both 64-bit flavours of x86 (codenamed 6226AMD64/EM64T), and Itanium (codenamed IA64). In addition, compilers that 6227are itself run in 64-bit mode, for better performance, are provided. The 6228complete list of compiler configurations are as follows (we abbreviate 6229AMD64/EM64T to just AMD64):</p> 6230</div> 6231<div class="ulist"> 6232<ul> 6233<li> 6234<p>32-bit x86 host, 32-bit x86 target</p> 6235</li> 6236<li> 6237<p>32-bit x86 host, 64-bit AMD64 target</p> 6238</li> 6239<li> 6240<p>32-bit x86 host, 64-bit IA64 target</p> 6241</li> 6242<li> 6243<p>64-bit AMD64 host, 64-bit AMD64 target</p> 6244</li> 6245<li> 6246<p>64-bit IA64 host, 64-bit IA64 target</p> 6247</li> 6248</ul> 6249</div> 6250<div class="paragraph"> 6251<p>The 32-bit host compilers can be always used, even on 64-bit Windows. On 6252the contrary, 64-bit host compilers require both 64-bit host processor 6253and 64-bit Windows, but can be faster. By default, only 32-bit host, 625432-bit target compiler is installed, and additional compilers need to be 6255installed explicitly.</p> 6256</div> 6257<div class="paragraph"> 6258<p>To use 64-bit compilation you should:</p> 6259</div> 6260<div class="olist arabic"> 6261<ol class="arabic"> 6262<li> 6263<p>Configure you compiler as usual. If you provide a path to the 6264compiler explicitly, provide the path to the 32-bit compiler. If you try 6265to specify the path to any of 64-bit compilers, configuration will not 6266work.</p> 6267</li> 6268<li> 6269<p>When compiling, use <code>address-model=64</code>, to generate AMD64 code.</p> 6270</li> 6271<li> 6272<p>To generate IA64 code, use <code>architecture=ia64</code></p> 6273</li> 6274</ol> 6275</div> 6276<div class="paragraph"> 6277<p>The (AMD64 host, AMD64 target) compiler will be used automatically when 6278you are generating AMD64 code and are running 64-bit Windows on AMD64. 6279The (IA64 host, IA64 target) compiler will never be used, since nobody 6280has an IA64 machine to test.</p> 6281</div> 6282<div class="paragraph"> 6283<p>It is believed that AMD64 and EM64T targets are essentially compatible. 6284The compiler options <code>/favor:AMD64</code> and <code>/favor:EM64T</code>, which are 6285accepted only by AMD64 targeting compilers, cause the generated code to 6286be tuned to a specific flavor of 64-bit x86. B2 will make use 6287of those options depending on the value of the`instruction-set` feature.</p> 6288</div> 6289</div> 6290<div class="sect5"> 6291<h6 id="bbv2.reference.tools.compiler.msvc.winrt"><a class="anchor" href="#bbv2.reference.tools.compiler.msvc.winrt"></a>Windows Runtime support</h6> 6292<div class="paragraph"> 6293<p>Starting with version 11.0, Microsoft Visual Studio can produce binaries 6294for Windows Store and Phone in addition to traditional Win32 desktop. To 6295specify which Windows API set to target, use the <code>windows-api</code> feature. 6296Available options are <code>desktop</code>, <code>store</code>, or <code>phone</code>. If not specified, 6297<code>desktop</code> will be used.</p> 6298</div> 6299<div class="paragraph"> 6300<p>When using <code>store</code> or <code>phone</code> the specified toolset determines what 6301Windows version is targeted. The following options are available:</p> 6302</div> 6303<div class="ulist"> 6304<ul> 6305<li> 6306<p>Windows 8.0: toolset=msvc-11.0 windows-api=store</p> 6307</li> 6308<li> 6309<p>Windows 8.1: toolset=msvc-12.0 windows-api=store</p> 6310</li> 6311<li> 6312<p>Windows Phone 8.0: toolset=msvc-11.0 windows-api=phone</p> 6313</li> 6314<li> 6315<p>Windows Phone 8.1: toolset=msvc-12.0 windows-api=phone</p> 6316</li> 6317</ul> 6318</div> 6319<div class="paragraph"> 6320<p>For example use the following to build for Windows Store 8.1 with the 6321ARM architecture:</p> 6322</div> 6323<div class="listingblock"> 6324<div class="content"> 6325<pre>.\b2 toolset=msvc-12.0 windows-api=store architecture=arm</pre> 6326</div> 6327</div> 6328<div class="paragraph"> 6329<p>Note that when targeting Windows Phone 8.1, version 12.0 didn’t include 6330the vcvars phone setup scripts. They can be separately downloaded from 6331<a href="http://blogs.msdn.com/b/vcblog/archive/2014/07/18/using-boost-libraries-in-windows-store-and-phone-applications.aspx">here</a>.</p> 6332</div> 6333</div> 6334</div> 6335<div class="sect4"> 6336<h5 id="bbv2.reference.tools.compiler.sun"><a class="anchor" href="#bbv2.reference.tools.compiler.sun"></a>Sun Studio</h5> 6337<div class="paragraph"> 6338<p>The <code>sun</code> module supports the 6339<a href="http://developers.sun.com/sunstudio/index.jsp">Sun Studio</a> C++ compilers 6340for the Solaris OS.</p> 6341</div> 6342<div class="paragraph"> 6343<p>The module is initialized using the following syntax:</p> 6344</div> 6345<div class="listingblock"> 6346<div class="content"> 6347<pre>using sun : [version] : [c++-compile-command] : [compiler options] ;</pre> 6348</div> 6349</div> 6350<div class="paragraph"> 6351<p>This statement may be repeated several times, if you want to configure 6352several versions of the compiler.</p> 6353</div> 6354<div class="paragraph"> 6355<p>If the command is not specified, B2 will search for a binary 6356named <code>CC</code> in <code>/opt/SUNWspro/bin</code> and in PATH.</p> 6357</div> 6358<div class="paragraph"> 6359<p>When using this compiler on complex C code, such as the 6360http://boost.org[Boost C library], it is recommended to specify the 6361following options when initializing the <code>sun</code> module:</p> 6362</div> 6363<div class="listingblock"> 6364<div class="content"> 6365<pre>-library=stlport4 -features=tmplife -features=tmplrefstatic</pre> 6366</div> 6367</div> 6368<div class="paragraph"> 6369<p>See the <a href="http://blogs.sun.com/sga/entry/command_line_options">Sun C++ 6370Frontend Tales</a> for details.</p> 6371</div> 6372<div class="paragraph"> 6373<p>The following options can be provided, using 6374<em>`<option-name>option-value syntax`</em>:</p> 6375</div> 6376<div class="dlist"> 6377<dl> 6378<dt class="hdlist1"><code>cflags</code></dt> 6379<dd> 6380<p>Specifies additional compiler flags that will be used when compiling C 6381sources.</p> 6382</dd> 6383<dt class="hdlist1"><code>cxxflags</code></dt> 6384<dd> 6385<p>Specifies additional compiler flags that will be used when compiling C++ 6386sources.</p> 6387</dd> 6388<dt class="hdlist1"><code>compileflags</code></dt> 6389<dd> 6390<p>Specifies additional compiler flags that will be used when compiling both C 6391and C++ sources.</p> 6392</dd> 6393<dt class="hdlist1"><code>linkflags</code></dt> 6394<dd> 6395<p>Specifies additional command line options that will be passed to the linker.</p> 6396</dd> 6397</dl> 6398</div> 6399<div class="paragraph"> 6400<p>Starting with Sun Studio 12, you can create 64-bit applications by using 6401the <code>address-model=64</code> property.</p> 6402</div> 6403</div> 6404<div class="sect4"> 6405<h5 id="bbv2.reference.tools.compiler.vacpp"><a class="anchor" href="#bbv2.reference.tools.compiler.vacpp"></a>IBM Visual Age</h5> 6406<div class="paragraph"> 6407<p>The <code>vacpp</code> module supports the <a href="http://www.ibm.com/software/ad/vacpp">IBM 6408Visual Age</a> C++ Compiler, for the AIX operating system. Versions 7.1 and 64098.0 are known to work.</p> 6410</div> 6411<div class="paragraph"> 6412<p>The module is initialized using the following syntax:</p> 6413</div> 6414<div class="listingblock"> 6415<div class="content"> 6416<pre>using vacpp ;</pre> 6417</div> 6418</div> 6419<div class="paragraph"> 6420<p>The module does not accept any initialization options. The compiler 6421should be installed in the <code>/usr/vacpp/bin</code> directory.</p> 6422</div> 6423<div class="paragraph"> 6424<p>Later versions of Visual Age are known as XL C/C++. They were not tested 6425with the the <code>vacpp</code> module.</p> 6426</div> 6427</div> 6428</div> 6429<div class="sect3"> 6430<h4 id="_third_party_libraries"><a class="anchor" href="#_third_party_libraries"></a>5.4.2. Third-party libraries</h4> 6431<div class="paragraph"> 6432<p>B2 provides special support for some third-party C++ libraries, 6433documented below.</p> 6434</div> 6435<div class="sect4"> 6436<h5 id="bbv2.reference.tools.libraries.stlport"><a class="anchor" href="#bbv2.reference.tools.libraries.stlport"></a>STLport library</h5> 6437<div class="paragraph"> 6438<p>The <a href="http://stlport.org">STLport</a> library is an alternative implementation 6439of C++ runtime library. B2 supports using that library on 6440Windows platform. Linux is hampered by different naming of libraries in 6441each STLport version and is not officially supported.</p> 6442</div> 6443<div class="paragraph"> 6444<p>Before using STLport, you need to configure it in <code>user-config.jam</code> 6445using the following syntax:</p> 6446</div> 6447<div class="listingblock"> 6448<div class="content"> 6449<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-nb">using</span><span class="tok-w"> </span>stlport<span class="tok-w"> </span>:<span class="tok-w"> </span>version<span class="tok-w"> </span>:<span class="tok-w"> </span>header-path<span class="tok-w"> </span>:<span class="tok-w"> </span>library-path<span class="tok-w"> </span>;<span class="tok-w"></span></code></pre> 6450</div> 6451</div> 6452<div class="paragraph"> 6453<p>Where version is the version of STLport, for example <code>5.1.4</code>, headers is 6454the location where STLport headers can be found, and libraries is the 6455location where STLport libraries can be found. The version should always 6456be provided, and the library path should be provided if you’re using 6457STLport’s implementation of <code>iostreams</code>. Note that STLport 5.* always uses 6458its own <code>iostream</code> implementation, so the library path is required.</p> 6459</div> 6460<div class="paragraph"> 6461<p>When STLport is configured, you can build with STLport by requesting 6462<code>stdlib=stlport</code> on the command line.</p> 6463</div> 6464</div> 6465<div class="sect4"> 6466<h5 id="bbv2.reference.tools.libraries.zlib"><a class="anchor" href="#bbv2.reference.tools.libraries.zlib"></a>zlib</h5> 6467<div class="paragraph"> 6468<p>Provides support for the <a href="http://www.zlib.net">zlib</a> library. zlib can be 6469configured either to use precompiled binaries or to build the library 6470from source.</p> 6471</div> 6472<div class="paragraph"> 6473<p>zlib can be initialized using the following syntax</p> 6474</div> 6475<div class="listingblock"> 6476<div class="content"> 6477<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-nb">using</span><span class="tok-w"> </span>zlib<span class="tok-w"> </span>:<span class="tok-w"> </span>version<span class="tok-w"> </span>:<span class="tok-w"> </span>options<span class="tok-w"> </span>:<span class="tok-w"> </span>condition<span class="tok-w"> </span>:<span class="tok-w"> </span>is-default<span class="tok-w"> </span>;<span class="tok-w"></span></code></pre> 6478</div> 6479</div> 6480<div class="paragraph"> 6481<p>Options for using a prebuilt library:</p> 6482</div> 6483<div class="dlist"> 6484<dl> 6485<dt class="hdlist1"><code>search</code></dt> 6486<dd> 6487<p>The directory containing the zlib binaries.</p> 6488</dd> 6489<dt class="hdlist1"><code>name</code></dt> 6490<dd> 6491<p>Overrides the default library name.</p> 6492</dd> 6493<dt class="hdlist1"><code>include</code></dt> 6494<dd> 6495<p>The directory containing the zlib headers.</p> 6496</dd> 6497</dl> 6498</div> 6499<div class="paragraph"> 6500<p>If none of these options is specified, then the environmental variables 6501ZLIB_LIBRARY_PATH, ZLIB_NAME, and ZLIB_INCLUDE will be used instead.</p> 6502</div> 6503<div class="paragraph"> 6504<p>Options for building zlib from source:</p> 6505</div> 6506<div class="dlist"> 6507<dl> 6508<dt class="hdlist1"><code>source</code></dt> 6509<dd> 6510<p>The zlib source directory. Defaults to the environmental variable 6511ZLIB_SOURCE.</p> 6512</dd> 6513<dt class="hdlist1"><code>tag</code></dt> 6514<dd> 6515<p>Sets the <a href="#bbv2.builtin.features.tag">tag</a> property to adjust the 6516file name of the library. Ignored when using precompiled binaries.</p> 6517</dd> 6518<dt class="hdlist1"><code>build-name</code></dt> 6519<dd> 6520<p>The base name to use for the compiled library. Ignored when using 6521precompiled binaries.</p> 6522</dd> 6523</dl> 6524</div> 6525<div class="paragraph"> 6526<p>Examples:</p> 6527</div> 6528<div class="listingblock"> 6529<div class="content"> 6530<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-c1"># Find zlib in the default system location</span> 6531<span class="tok-nb">using</span><span class="tok-w"> </span>zlib<span class="tok-w"> </span>;<span class="tok-w"></span> 6532<span class="tok-c1"># Build zlib from source</span> 6533<span class="tok-nb">using</span><span class="tok-w"> </span>zlib<span class="tok-w"> </span>:<span class="tok-w"> </span>1.2.7<span class="tok-w"> </span>:<span class="tok-w"> </span><span class="tok-na"><source></span>/home/steven/zlib-1.2.7<span class="tok-w"> </span>;<span class="tok-w"></span> 6534<span class="tok-c1"># Find zlib in /usr/local</span> 6535<span class="tok-nb">using</span><span class="tok-w"> </span>zlib<span class="tok-w"> </span>:<span class="tok-w"> </span>1.2.7<span class="tok-w"> </span>:<span class="tok-w"> </span><span class="tok-na"><include></span>/usr/local/include<span class="tok-w"> </span><span class="tok-na"><search></span>/usr/local/lib<span class="tok-w"> </span>;<span class="tok-w"></span> 6536<span class="tok-c1"># Build zlib from source for msvc and find</span> 6537<span class="tok-c1"># prebuilt binaries for gcc.</span> 6538<span class="tok-nb">using</span><span class="tok-w"> </span>zlib<span class="tok-w"> </span>:<span class="tok-w"> </span>1.2.7<span class="tok-w"> </span>:<span class="tok-w"> </span><span class="tok-na"><source></span>C:/Devel/src/zlib-1.2.7<span class="tok-w"> </span>:<span class="tok-w"> </span><span class="tok-na"><toolset></span>msvc<span class="tok-w"> </span>;<span class="tok-w"></span> 6539<span class="tok-nb">using</span><span class="tok-w"> </span>zlib<span class="tok-w"> </span>:<span class="tok-w"> </span>1.2.7<span class="tok-w"> </span>:<span class="tok-w"> </span>:<span class="tok-w"> </span><span class="tok-na"><toolset></span>gcc<span class="tok-w"> </span>;<span class="tok-w"></span></code></pre> 6540</div> 6541</div> 6542</div> 6543<div class="sect4"> 6544<h5 id="bbv2.reference.tools.libraries.bzip2"><a class="anchor" href="#bbv2.reference.tools.libraries.bzip2"></a>bzip2</h5> 6545<div class="paragraph"> 6546<p>Provides support for the <a href="http://www.bzip.org">bzip2</a> library. bzip2 can 6547be configured either to use precompiled binaries or to build the library 6548from source.</p> 6549</div> 6550<div class="paragraph"> 6551<p>bzip2 can be initialized using the following syntax</p> 6552</div> 6553<div class="listingblock"> 6554<div class="content"> 6555<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-nb">using</span><span class="tok-w"> </span>bzip2<span class="tok-w"> </span>:<span class="tok-w"> </span>version<span class="tok-w"> </span>:<span class="tok-w"> </span>options<span class="tok-w"> </span>:<span class="tok-w"> </span>condition<span class="tok-w"> </span>:<span class="tok-w"> </span>is-default<span class="tok-w"> </span>;<span class="tok-w"></span></code></pre> 6556</div> 6557</div> 6558<div class="paragraph"> 6559<p>Options for using a prebuilt library:</p> 6560</div> 6561<div class="dlist"> 6562<dl> 6563<dt class="hdlist1"><code>search</code></dt> 6564<dd> 6565<p>The directory containing the bzip2 binaries.</p> 6566</dd> 6567<dt class="hdlist1"><code>name</code></dt> 6568<dd> 6569<p>Overrides the default library name.</p> 6570</dd> 6571<dt class="hdlist1"><code>include</code></dt> 6572<dd> 6573<p>The directory containing the bzip2 headers.</p> 6574</dd> 6575</dl> 6576</div> 6577<div class="paragraph"> 6578<p>If none of these options is specified, then the environmental variables 6579BZIP2_LIBRARY_PATH, BZIP2_NAME, and BZIP2_INCLUDE will be used instead.</p> 6580</div> 6581<div class="paragraph"> 6582<p>Options for building bzip2 from source:</p> 6583</div> 6584<div class="dlist"> 6585<dl> 6586<dt class="hdlist1"><code>source</code></dt> 6587<dd> 6588<p>The bzip2 source directory. Defaults to the environmental variable 6589BZIP2_SOURCE.</p> 6590</dd> 6591<dt class="hdlist1"><code>tag</code></dt> 6592<dd> 6593<p>Sets the <a href="#bbv2.builtin.features.tag">tag</a> property to adjust the 6594file name of the library. Ignored when using precompiled binaries.</p> 6595</dd> 6596<dt class="hdlist1"><code>build-name</code></dt> 6597<dd> 6598<p>The base name to use for the compiled library. Ignored when using 6599precompiled binaries.</p> 6600</dd> 6601</dl> 6602</div> 6603<div class="paragraph"> 6604<p>Examples:</p> 6605</div> 6606<div class="listingblock"> 6607<div class="content"> 6608<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-c1"># Find bzip in the default system location</span> 6609<span class="tok-nb">using</span><span class="tok-w"> </span>bzip2<span class="tok-w"> </span>;<span class="tok-w"></span> 6610<span class="tok-c1"># Build bzip from source</span> 6611<span class="tok-nb">using</span><span class="tok-w"> </span>bzip2<span class="tok-w"> </span>:<span class="tok-w"> </span>1.0.6<span class="tok-w"> </span>:<span class="tok-w"> </span><span class="tok-na"><source></span>/home/sergey/src/bzip2-1.0.6<span class="tok-w"> </span>;<span class="tok-w"></span> 6612<span class="tok-c1"># Find bzip in /usr/local</span> 6613<span class="tok-nb">using</span><span class="tok-w"> </span>bzip2<span class="tok-w"> </span>:<span class="tok-w"> </span>1.0.6<span class="tok-w"> </span>:<span class="tok-w"> </span><span class="tok-na"><include></span>/usr/local/include<span class="tok-w"> </span><span class="tok-na"><search></span>/usr/local/lib<span class="tok-w"> </span>;<span class="tok-w"></span> 6614<span class="tok-c1"># Build bzip from source for msvc and find</span> 6615<span class="tok-c1"># prebuilt binaries for gcc.</span> 6616<span class="tok-nb">using</span><span class="tok-w"> </span>bzip2<span class="tok-w"> </span>:<span class="tok-w"> </span>1.0.6<span class="tok-w"> </span>:<span class="tok-w"> </span><span class="tok-na"><source></span>C:/Devel/src/bzip2-1.0.6<span class="tok-w"> </span>:<span class="tok-w"> </span><span class="tok-na"><toolset></span>msvc<span class="tok-w"> </span>;<span class="tok-w"></span> 6617<span class="tok-nb">using</span><span class="tok-w"> </span>bzip2<span class="tok-w"> </span>:<span class="tok-w"> </span>1.0.6<span class="tok-w"> </span>:<span class="tok-w"> </span>:<span class="tok-w"> </span><span class="tok-na"><toolset></span>gcc<span class="tok-w"> </span>;<span class="tok-w"></span></code></pre> 6618</div> 6619</div> 6620</div> 6621<div class="sect4"> 6622<h5 id="bbv2.reference.tools.libraries.python"><a class="anchor" href="#bbv2.reference.tools.libraries.python"></a>Python</h5> 6623<div class="paragraph"> 6624<p>Provides support for the <a href="http://www.python.org">python</a> language 6625environment to be linked in as a library.</p> 6626</div> 6627<div class="paragraph"> 6628<p>python can be initialized using the following syntax</p> 6629</div> 6630<div class="listingblock"> 6631<div class="content"> 6632<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-nb">using</span><span class="tok-w"> </span>python<span class="tok-w"> </span>:<span class="tok-w"> </span>[version]<span class="tok-w"> </span>:<span class="tok-w"> </span>[command-or-prefix]<span class="tok-w"> </span>:<span class="tok-w"> </span>[includes]<span class="tok-w"> </span>:<span class="tok-w"> </span>[libraries]<span class="tok-w"> </span>:<span class="tok-w"> </span>[conditions]<span class="tok-w"> </span>:<span class="tok-w"> </span>[extension-suffix]<span class="tok-w"> </span>;<span class="tok-w"></span></code></pre> 6633</div> 6634</div> 6635<div class="paragraph"> 6636<p>Options for using python:</p> 6637</div> 6638<div class="dlist"> 6639<dl> 6640<dt class="hdlist1"><code>version</code></dt> 6641<dd> 6642<p>The version of Python to use. Should be in Major.Minor format, for example 66432.3. Do not include the sub-minor version.</p> 6644</dd> 6645<dt class="hdlist1"><code>command-or-prefix</code></dt> 6646<dd> 6647<p>Preferably, a command that invokes a Python interpreter. Alternatively, the 6648installation prefix for Python libraries and includes. If empty, will be 6649guessed from the version, the platform’s installation patterns, and the 6650python executables that can be found in PATH.</p> 6651</dd> 6652<dt class="hdlist1"><code>includes</code></dt> 6653<dd> 6654<p>the include path to Python headers. If empty, will be guessed.</p> 6655</dd> 6656<dt class="hdlist1"><code>libraries</code></dt> 6657<dd> 6658<p>the path to Python library binaries. If empty, will be guessed. On 6659MacOS/Darwin, you can also pass the path of the Python framework.</p> 6660</dd> 6661<dt class="hdlist1"><code>conditions</code></dt> 6662<dd> 6663<p>if specified, should be a set of properties that are matched against the 6664build configuration when B2 selects a Python configuration to use.</p> 6665</dd> 6666<dt class="hdlist1"><code>extension-suffix</code></dt> 6667<dd> 6668<p>A string to append to the name of extension modules before the true filename 6669extension. Ordinarily we would just compute this based on the value of the 6670<code><python-debugging></code> feature. However ubuntu’s <code>python-dbg</code> package uses the 6671windows convention of appending _d to debug-build extension modules. We have 6672no way of detecting ubuntu, or of probing python for the "_d" requirement, 6673and if you configure and build python using <code>--with-pydebug</code>, you’ll be using 6674the standard *nix convention. Defaults to "" (or "_d" when targeting windows 6675and <python-debugging> is set).</p> 6676</dd> 6677</dl> 6678</div> 6679<div class="paragraph"> 6680<p>Examples:</p> 6681</div> 6682<div class="listingblock"> 6683<div class="content"> 6684<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-c1"># Find python in the default system location</span> 6685<span class="tok-nb">using</span><span class="tok-w"> </span>python<span class="tok-w"> </span>;<span class="tok-w"></span> 6686<span class="tok-c1"># 2.7</span> 6687<span class="tok-nb">using</span><span class="tok-w"> </span>python<span class="tok-w"> </span>:<span class="tok-w"> </span>2.7<span class="tok-w"> </span>;<span class="tok-w"></span> 6688<span class="tok-c1"># 3.5</span> 6689<span class="tok-nb">using</span><span class="tok-w"> </span>python<span class="tok-w"> </span>:<span class="tok-w"> </span>3.5<span class="tok-w"> </span>;<span class="tok-w"></span> 6690 6691<span class="tok-c1"># On ubuntu 16.04</span> 6692<span class="tok-nb">using</span><span class="tok-w"> </span>python<span class="tok-w"></span> 6693:<span class="tok-w"> </span>2.7<span class="tok-w"> </span><span class="tok-c1"># version</span> 6694:<span class="tok-w"> </span><span class="tok-c1"># Interpreter/path to dir</span> 6695:<span class="tok-w"> </span>/usr/include/python2.7<span class="tok-w"> </span><span class="tok-c1"># includes</span> 6696:<span class="tok-w"> </span>/usr/lib/x86_64-linux-gnu<span class="tok-w"> </span><span class="tok-c1"># libs</span> 6697:<span class="tok-w"> </span><span class="tok-c1"># conditions</span> 6698;<span class="tok-w"></span> 6699 6700<span class="tok-nb">using</span><span class="tok-w"> </span>python<span class="tok-w"></span> 6701:<span class="tok-w"> </span>3.5<span class="tok-w"> </span><span class="tok-c1"># version</span> 6702:<span class="tok-w"> </span><span class="tok-c1"># Interpreter/path to dir</span> 6703:<span class="tok-w"> </span>/usr/include/python3.5<span class="tok-w"> </span><span class="tok-c1"># includes</span> 6704:<span class="tok-w"> </span>/usr/lib/x86_64-linux-gnu<span class="tok-w"> </span><span class="tok-c1"># libs</span> 6705:<span class="tok-w"> </span><span class="tok-c1"># conditions</span> 6706;<span class="tok-w"></span> 6707 6708<span class="tok-c1"># On windows</span> 6709<span class="tok-nb">using</span><span class="tok-w"> </span>python<span class="tok-w"></span> 6710:<span class="tok-w"> </span>2.7<span class="tok-w"> </span><span class="tok-c1"># version</span> 6711:<span class="tok-w"> </span>C:\\Python27-32\\python.exe<span class="tok-w"> </span><span class="tok-c1"># Interperter/path to dir</span> 6712:<span class="tok-w"> </span>C:\\Python27-32\\include<span class="tok-w"> </span><span class="tok-c1"># includes</span> 6713:<span class="tok-w"> </span>C:\\Python27-32\\libs<span class="tok-w"> </span><span class="tok-c1"># libs</span> 6714:<span class="tok-w"> </span><span class="tok-na"><address-model></span>32<span class="tok-w"> </span><span class="tok-na"><address-model></span><span class="tok-w"> </span><span class="tok-c1"># conditions - both 32 and unspecified</span> 6715;<span class="tok-w"></span> 6716 6717<span class="tok-nb">using</span><span class="tok-w"> </span>python<span class="tok-w"></span> 6718:<span class="tok-w"> </span>2.7<span class="tok-w"> </span><span class="tok-c1"># version</span> 6719:<span class="tok-w"> </span>C:\\Python27-64\\python.exe<span class="tok-w"> </span><span class="tok-c1"># Interperter/path to dir</span> 6720:<span class="tok-w"> </span>C:\\Python27-64\\include<span class="tok-w"> </span><span class="tok-c1"># includes</span> 6721:<span class="tok-w"> </span>C:\\Python27-64\\libs<span class="tok-w"> </span><span class="tok-c1"># libs</span> 6722:<span class="tok-w"> </span><span class="tok-na"><address-model></span>64<span class="tok-w"> </span><span class="tok-c1"># conditions</span> 6723;<span class="tok-w"></span></code></pre> 6724</div> 6725</div> 6726</div> 6727</div> 6728<div class="sect3"> 6729<h4 id="_documentation_tools"><a class="anchor" href="#_documentation_tools"></a>5.4.3. Documentation tools</h4> 6730<div class="paragraph"> 6731<p>B2 support for the Boost documentation tools is documented 6732below.</p> 6733</div> 6734<div class="sect4"> 6735<h5 id="bbv2.reference.tools.doc.xsltproc"><a class="anchor" href="#bbv2.reference.tools.doc.xsltproc"></a>xsltproc</h5> 6736<div class="paragraph"> 6737<p>To use xsltproc, you first need to configure it using the following 6738syntax:</p> 6739</div> 6740<div class="listingblock"> 6741<div class="content"> 6742<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-nb">using</span><span class="tok-w"> </span>xsltproc<span class="tok-w"> </span>:<span class="tok-w"> </span>xsltproc<span class="tok-w"> </span>;<span class="tok-w"></span></code></pre> 6743</div> 6744</div> 6745<div class="paragraph"> 6746<p>Where xsltproc is the xsltproc executable. If xsltproc is not specified, 6747and the variable XSLTPROC is set, the value of XSLTPROC will be used. 6748Otherwise, xsltproc will be searched for in PATH.</p> 6749</div> 6750<div class="paragraph"> 6751<p>The following options can be provided, using 6752<em>`<option-name>option-value syntax`</em>:</p> 6753</div> 6754<div class="dlist"> 6755<dl> 6756<dt class="hdlist1"><code>xsl:param</code></dt> 6757<dd> 6758<p>Values should have the form name=value</p> 6759</dd> 6760<dt class="hdlist1"><code>xsl:path</code></dt> 6761<dd> 6762<p>Sets an additional search path for xi:include elements.</p> 6763</dd> 6764<dt class="hdlist1"><code>catalog</code></dt> 6765<dd> 6766<p>A catalog file used to rewrite remote URL’s to a local copy.</p> 6767</dd> 6768</dl> 6769</div> 6770<div class="paragraph"> 6771<p>The xsltproc module provides the following rules. Note that these 6772operate on jam targets and are intended to be used by another toolset, 6773such as boostbook, rather than directly by users.</p> 6774</div> 6775<div class="dlist"> 6776<dl> 6777<dt class="hdlist1"><code>xslt</code></dt> 6778<dd> 6779<div class="listingblock"> 6780<div class="content"> 6781<pre>rule xslt ( target : source stylesheet : properties * )</pre> 6782</div> 6783</div> 6784<div class="paragraph"> 6785<p>Runs xsltproc to create a single output file.</p> 6786</div> 6787</dd> 6788<dt class="hdlist1"><code>xslt-dir</code></dt> 6789<dd> 6790<div class="listingblock"> 6791<div class="content"> 6792<pre>rule xslt-dir ( target : source stylesheet : properties * : dirname )</pre> 6793</div> 6794</div> 6795<div class="paragraph"> 6796<p>Runs xsltproc to create multiple outputs in a directory. <code>dirname</code> is 6797unused, but exists for historical reasons. The output directory is 6798determined from the target.</p> 6799</div> 6800</dd> 6801</dl> 6802</div> 6803</div> 6804<div class="sect4"> 6805<h5 id="bbv2.reference.tools.doc.boostbook"><a class="anchor" href="#bbv2.reference.tools.doc.boostbook"></a>boostbook</h5> 6806<div class="paragraph"> 6807<p>To use boostbook, you first need to configure it using the following 6808syntax:</p> 6809</div> 6810<div class="listingblock"> 6811<div class="content"> 6812<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-nb">using</span><span class="tok-w"> </span>boostbook<span class="tok-w"> </span>:<span class="tok-w"> </span>docbook-xsl-dir<span class="tok-w"> </span>:<span class="tok-w"> </span>docbook-dtd-dir<span class="tok-w"> </span>:<span class="tok-w"> </span>boostbook-dir<span class="tok-w"> </span>;<span class="tok-w"></span></code></pre> 6813</div> 6814</div> 6815<div class="paragraph"> 6816<p><code>docbook-xsl-dir</code> is the DocBook XSL stylesheet directory. If not 6817provided, we use <code>DOCBOOK_XSL_DIR</code> from the environment (if available) or 6818look in standard locations. Otherwise, we let the XML processor load the 6819stylesheets remotely.</p> 6820</div> 6821<div class="paragraph"> 6822<p><code>docbook-dtd-dir</code> is the DocBook DTD directory. If not provided, we use 6823<code>DOCBOOK_DTD_DIR</code> From the environment (if available) or look in standard 6824locations. Otherwise, we let the XML processor load the DTD remotely.</p> 6825</div> 6826<div class="paragraph"> 6827<p><code>boostbook-dir</code> is the BoostBook directory with the DTD and XSL sub-dirs.</p> 6828</div> 6829<div class="paragraph"> 6830<p>The boostbook module depends on xsltproc. For pdf or ps output, it also 6831depends on fop.</p> 6832</div> 6833<div class="paragraph"> 6834<p>The following options can be provided, using 6835<em>`<option-name>option-value syntax`</em>:</p> 6836</div> 6837<div class="dlist"> 6838<dl> 6839<dt class="hdlist1"><code>format</code></dt> 6840<dd> 6841<div class="paragraph"> 6842<p><strong>Allowed values:</strong> <code>html</code>, <code>xhtml</code>, <code>htmlhelp</code>, <code>onehtml</code>, <code>man</code>, 6843<code>pdf</code>, <code>ps</code>, <code>docbook</code>, <code>fo</code>, <code>tests</code>.</p> 6844</div> 6845<div class="paragraph"> 6846<p>The <code>format</code> feature determines the type of output produced by the 6847boostbook rule.</p> 6848</div> 6849</dd> 6850</dl> 6851</div> 6852<div class="paragraph"> 6853<p>The boostbook module defines a rule for creating a target following the 6854common syntax.</p> 6855</div> 6856<div class="dlist"> 6857<dl> 6858<dt class="hdlist1"><code>boostbook</code></dt> 6859<dd> 6860<div class="listingblock"> 6861<div class="content"> 6862<pre>rule boostbook ( target-name : sources * : requirements * : default-build * )</pre> 6863</div> 6864</div> 6865<div class="paragraph"> 6866<p>Creates a boostbook target.</p> 6867</div> 6868</dd> 6869</dl> 6870</div> 6871</div> 6872<div class="sect4"> 6873<h5 id="bbv2.reference.tools.doc.doxygen"><a class="anchor" href="#bbv2.reference.tools.doc.doxygen"></a>doxygen</h5> 6874<div class="paragraph"> 6875<p>To use doxygen, you first need to configure it using the following 6876syntax:</p> 6877</div> 6878<div class="listingblock"> 6879<div class="content"> 6880<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-nb">using</span><span class="tok-w"> </span>doxygen<span class="tok-w"> </span>:<span class="tok-w"> </span>name<span class="tok-w"> </span>;<span class="tok-w"></span></code></pre> 6881</div> 6882</div> 6883<div class="paragraph"> 6884<p><code>name</code> is the doxygen command. If it is not specified, it will be found in 6885the PATH.</p> 6886</div> 6887<div class="paragraph"> 6888<p>The doxygen module depends on the boostbook module when generating 6889BoostBook XML.</p> 6890</div> 6891<div class="paragraph"> 6892<p>The following options can be provided, using 6893<em>`<option-name>option-value syntax`</em>:</p> 6894</div> 6895<div class="dlist"> 6896<dl> 6897<dt class="hdlist1"><code>doxygen:param</code></dt> 6898<dd> 6899<div class="paragraph"> 6900<p>All the values of <code>doxygen:param</code> are added to the <code>doxyfile</code>.</p> 6901</div> 6902</dd> 6903<dt class="hdlist1"><code>prefix</code></dt> 6904<dd> 6905<div class="paragraph"> 6906<p>Specifies the common prefix of all headers when generating BoostBook 6907XML. Everything before this will be stripped off.</p> 6908</div> 6909</dd> 6910<dt class="hdlist1"><code>reftitle</code></dt> 6911<dd> 6912<div class="paragraph"> 6913<p>Specifies the title of the library-reference section, when generating 6914BoostBook XML.</p> 6915</div> 6916</dd> 6917<dt class="hdlist1"><code>doxygen:xml-imagedir</code></dt> 6918<dd> 6919<div class="paragraph"> 6920<p>When generating BoostBook XML, specifies the directory in which to 6921place the images generated from LaTex formulae.</p> 6922</div> 6923<div class="admonitionblock warning"> 6924<table> 6925<tr> 6926<td class="icon"> 6927<div class="title">⚠</div> 6928</td> 6929<td class="content"> 6930The path is interpreted relative to the current working directory, 6931not relative to the Jamfile. This is necessary to match the behavior of 6932BoostBook. 6933</td> 6934</tr> 6935</table> 6936</div> 6937</dd> 6938</dl> 6939</div> 6940<div class="paragraph"> 6941<p>The doxygen module defines a rule for creating a target following the 6942common syntax.</p> 6943</div> 6944<div class="dlist"> 6945<dl> 6946<dt class="hdlist1"><code>doxygen</code></dt> 6947<dd> 6948<div class="listingblock"> 6949<div class="content"> 6950<pre>rule doxygen ( target : sources * : requirements * : default-build * : usage-requirements * )</pre> 6951</div> 6952</div> 6953<div class="paragraph"> 6954<p>Creates a doxygen target. If the target name ends with .html, then 6955this will generate an html directory. Otherwise it will generate 6956BoostBook XML.</p> 6957</div> 6958</dd> 6959</dl> 6960</div> 6961</div> 6962<div class="sect4"> 6963<h5 id="bbv2.reference.tools.doc.quickbook"><a class="anchor" href="#bbv2.reference.tools.doc.quickbook"></a>quickbook</h5> 6964<div class="paragraph"> 6965<p>The quickbook module provides a generator to convert from Quickbook to 6966BoostBook XML.</p> 6967</div> 6968<div class="paragraph"> 6969<p>To use quickbook, you first need to configure it using the following 6970syntax:</p> 6971</div> 6972<div class="listingblock"> 6973<div class="content"> 6974<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-nb">using</span><span class="tok-w"> </span>quickbook<span class="tok-w"> </span>:<span class="tok-w"> </span>command<span class="tok-w"> </span>;<span class="tok-w"></span></code></pre> 6975</div> 6976</div> 6977<div class="paragraph"> 6978<p><code>command</code> is the quickbook executable. If it is not specified, B2 6979will compile it from source. If it is unable to find the source it will 6980search for a quickbook executable in PATH.</p> 6981</div> 6982</div> 6983<div class="sect4"> 6984<h5 id="bbv2.reference.tools.doc.fop"><a class="anchor" href="#bbv2.reference.tools.doc.fop"></a>fop</h5> 6985<div class="paragraph"> 6986<p>The fop module provides generators to convert from XSL formatting 6987objects to Postscript and PDF.</p> 6988</div> 6989<div class="paragraph"> 6990<p>To use fop, you first need to configure it using the following syntax:</p> 6991</div> 6992<div class="listingblock"> 6993<div class="content"> 6994<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-nb">using</span><span class="tok-w"> </span>fop<span class="tok-w"> </span>:<span class="tok-w"> </span>fop-command<span class="tok-w"> </span>:<span class="tok-w"> </span>java-home<span class="tok-w"> </span>:<span class="tok-w"> </span>java<span class="tok-w"> </span>;<span class="tok-w"></span></code></pre> 6995</div> 6996</div> 6997<div class="paragraph"> 6998<p><code>fop-command</code> is the command to run fop. If it is not specified, 6999B2 will search for it in PATH and FOP_HOME.</p> 7000</div> 7001<div class="paragraph"> 7002<p>Either <code>java-home</code> or <code>java</code> can be used to specify where to find java.</p> 7003</div> 7004</div> 7005</div> 7006</div> 7007<div class="sect2"> 7008<h3 id="bbv2.reference.modules"><a class="anchor" href="#bbv2.reference.modules"></a>5.5. Builtin modules</h3> 7009<div class="paragraph"> 7010<p>This section describes the modules that are provided by B2. The 7011import rule allows rules from one module to be used in another module or 7012Jamfile.</p> 7013</div> 7014<div class="sect3"> 7015<h4 id="bbv2.reference.modules.modules"><a class="anchor" href="#bbv2.reference.modules.modules"></a>5.5.1. modules</h4> 7016<div class="paragraph"> 7017<p>The <code>modules</code> module defines basic functionality for handling modules.</p> 7018</div> 7019<div class="paragraph"> 7020<p>A module defines a number of rules that can be used in other modules. 7021Modules can contain code at the top level to initialize the module. This 7022code is executed the first time the module is loaded.</p> 7023</div> 7024<div class="admonitionblock note"> 7025<table> 7026<tr> 7027<td class="icon"> 7028<div class="title">ℹ</div> 7029</td> 7030<td class="content"> 7031A Jamfile is a special kind of module which is managed by the build 7032system. Although they cannot be loaded directly by users, the other 7033features of modules are still useful for Jamfiles. 7034</td> 7035</tr> 7036</table> 7037</div> 7038<div class="paragraph"> 7039<p>Each module has its own namespaces for variables and rules. If two 7040modules A and B both use a variable named X, each one gets its own copy 7041of X. They won’t interfere with each other in any way. Similarly, 7042importing rules into one module has no effect on any other module.</p> 7043</div> 7044<div class="paragraph"> 7045<p>Every module has two special variables. <code>$(<em>file</em>)</code> contains the name 7046of the file that the module was loaded from and <code>$(<em>name</em>)</code> contains 7047the name of the module.</p> 7048</div> 7049<div class="admonitionblock note"> 7050<table> 7051<tr> 7052<td class="icon"> 7053<div class="title">ℹ</div> 7054</td> 7055<td class="content"> 7056<code>$(<em>file</em>)</code> does not contain the full path to the file. If you need 7057this, use <code>modules.binding</code>. 7058</td> 7059</tr> 7060</table> 7061</div> 7062<div class="olist arabic"> 7063<ol class="arabic"> 7064<li> 7065<p><code>rule binding ( module-name )</code></p> 7066<div class="paragraph"> 7067<p>Returns the filesystem binding of the given module.</p> 7068</div> 7069<div class="paragraph"> 7070<p>For example, a module can get its own location with:</p> 7071</div> 7072<div class="listingblock"> 7073<div class="content"> 7074<pre class="pygments highlight"><code data-lang="jam"><span></span>me<span class="tok-w"> </span>=<span class="tok-w"> </span>[<span class="tok-w"> </span>modules.binding<span class="tok-w"> </span><span class="tok-si">$(__name__)</span><span class="tok-w"> </span>]<span class="tok-w"> </span>;<span class="tok-w"></span></code></pre> 7075</div> 7076</div> 7077</li> 7078<li> 7079<p><code>rule poke ( module-name ? : variables + : value * )</code></p> 7080<div class="paragraph"> 7081<p>Sets the module-local value of a variable.</p> 7082</div> 7083<div class="paragraph"> 7084<p>For example, to set a variable in the global module:</p> 7085</div> 7086<div class="listingblock"> 7087<div class="content"> 7088<pre class="pygments highlight"><code data-lang="jam"><span></span>modules.poke<span class="tok-w"> </span>:<span class="tok-w"> </span>ZLIB_INCLUDE<span class="tok-w"> </span>:<span class="tok-w"> </span>/usr/local/include<span class="tok-w"> </span>;<span class="tok-w"></span></code></pre> 7089</div> 7090</div> 7091</li> 7092<li> 7093<p><code>rule peek ( module-name ? : variables + )</code></p> 7094<div class="paragraph"> 7095<p>Returns the module-local value of a variable.</p> 7096</div> 7097<div class="paragraph"> 7098<p>For example, to read a variable from the global module:</p> 7099</div> 7100<div class="listingblock"> 7101<div class="content"> 7102<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-k">local</span><span class="tok-w"> </span>ZLIB_INCLUDE<span class="tok-w"> </span>=<span class="tok-w"> </span>[<span class="tok-w"> </span>modules.peek<span class="tok-w"> </span>:<span class="tok-w"> </span>ZLIB_INCLUDE<span class="tok-w"> </span>]<span class="tok-w"> </span>;<span class="tok-w"></span></code></pre> 7103</div> 7104</div> 7105</li> 7106<li> 7107<p><code>rule call-in ( module-name ? : rule-name args * : * )</code></p> 7108<div class="paragraph"> 7109<p>Call the given rule locally in the given module. Use this for rules 7110accepting rule names as arguments, so that the passed rule may be 7111invoked in the context of the rule’s caller (for example, if the rule 7112accesses module globals or is a local rule).</p> 7113</div> 7114<div class="admonitionblock note"> 7115<table> 7116<tr> 7117<td class="icon"> 7118<div class="title">ℹ</div> 7119</td> 7120<td class="content"> 7121rules called this way may accept at most 8 parameters. 7122</td> 7123</tr> 7124</table> 7125</div> 7126<div class="paragraph"> 7127<p>Example:</p> 7128</div> 7129<div class="listingblock"> 7130<div class="content"> 7131<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-k">rule</span><span class="tok-w"> </span><span class="tok-nf">filter</span><span class="tok-w"> </span><span class="tok-p">(</span><span class="tok-w"> </span><span class="tok-nv">f</span><span class="tok-w"> </span><span class="tok-p">:</span><span class="tok-w"> </span><span class="tok-nv">values</span><span class="tok-w"> </span><span class="tok-p">*</span><span class="tok-w"> </span><span class="tok-p">)</span><span class="tok-w"></span> 7132{<span class="tok-w"></span> 7133<span class="tok-w"> </span><span class="tok-k">local</span><span class="tok-w"> </span>m<span class="tok-w"> </span>=<span class="tok-w"> </span>[<span class="tok-w"> </span><span class="tok-nb">CALLER_MODULE</span><span class="tok-w"> </span>]<span class="tok-w"> </span>;<span class="tok-w"></span> 7134<span class="tok-w"> </span><span class="tok-k">local</span><span class="tok-w"> </span>result<span class="tok-w"> </span>;<span class="tok-w"></span> 7135<span class="tok-w"> </span><span class="tok-k">for</span><span class="tok-w"> </span>v<span class="tok-w"> </span><span class="tok-k">in</span><span class="tok-w"> </span><span class="tok-si">$(values)</span><span class="tok-w"></span> 7136<span class="tok-w"> </span>{<span class="tok-w"></span> 7137<span class="tok-w"> </span><span class="tok-k">if</span><span class="tok-w"> </span>[<span class="tok-w"> </span>modules.call-in<span class="tok-w"> </span><span class="tok-si">$(m)</span><span class="tok-w"> </span>:<span class="tok-w"> </span><span class="tok-si">$(f)</span><span class="tok-w"> </span><span class="tok-si">$(v)</span><span class="tok-w"> </span>]<span class="tok-w"></span> 7138<span class="tok-w"> </span>{<span class="tok-w"></span> 7139<span class="tok-w"> </span>result<span class="tok-w"> </span>+=<span class="tok-w"> </span><span class="tok-si">$(v)</span><span class="tok-w"> </span>;<span class="tok-w"></span> 7140<span class="tok-w"> </span>}<span class="tok-w"></span> 7141<span class="tok-w"> </span>}<span class="tok-w"></span> 7142<span class="tok-w"> </span><span class="tok-k">return</span><span class="tok-w"> </span>result<span class="tok-w"> </span>;<span class="tok-w"></span> 7143}<span class="tok-w"></span></code></pre> 7144</div> 7145</div> 7146</li> 7147<li> 7148<p><code>rule load ( module-name : filename ? : search * )</code></p> 7149<div class="paragraph"> 7150<p>Load the indicated module if it is not already loaded.</p> 7151</div> 7152<div class="dlist"> 7153<dl> 7154<dt class="hdlist1"><code>module-name</code></dt> 7155<dd> 7156<p>Name of module to load.</p> 7157</dd> 7158<dt class="hdlist1"><code>filename</code></dt> 7159<dd> 7160<p>(partial) path to file; Defaults to <code>$(module-name).jam</code></p> 7161</dd> 7162<dt class="hdlist1"><code>search</code></dt> 7163<dd> 7164<p>Directories in which to search for filename. Defaults to 7165<code>$(BOOST_BUILD_PATH)</code>.</p> 7166</dd> 7167</dl> 7168</div> 7169</li> 7170<li> 7171<p><code>rule import ( module-names + : rules-opt * : rename-opt * )</code></p> 7172<div class="paragraph"> 7173<p>Load the indicated module and import rule names into the current module. 7174Any members of <code>rules-opt</code> will be available without qualification in 7175the caller’s module. Any members of <code>rename-opt</code> will be taken as the 7176names of the rules in the caller’s module, in place of the names they 7177have in the imported module. If <code>rules-opt = '*'</code>, all rules from the 7178indicated module are imported into the caller’s module. If <code>rename-opt</code> 7179is supplied, it must have the same number of elements as <code>rules-opt</code>.</p> 7180</div> 7181<div class="admonitionblock note"> 7182<table> 7183<tr> 7184<td class="icon"> 7185<div class="title">ℹ</div> 7186</td> 7187<td class="content"> 7188The <code>import</code> rule is available without qualification in all modules. 7189</td> 7190</tr> 7191</table> 7192</div> 7193<div class="paragraph"> 7194<p>Examples:</p> 7195</div> 7196<div class="listingblock"> 7197<div class="content"> 7198<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-nb">import</span><span class="tok-w"> </span>path<span class="tok-w"> </span>;<span class="tok-w"></span> 7199<span class="tok-nb">import</span><span class="tok-w"> </span>path<span class="tok-w"> </span>:<span class="tok-w"> </span>*<span class="tok-w"> </span>;<span class="tok-w"></span> 7200<span class="tok-nb">import</span><span class="tok-w"> </span>path<span class="tok-w"> </span>:<span class="tok-w"> </span>join<span class="tok-w"> </span>;<span class="tok-w"></span> 7201<span class="tok-nb">import</span><span class="tok-w"> </span>path<span class="tok-w"> </span>:<span class="tok-w"> </span>native<span class="tok-w"> </span><span class="tok-nb">make</span><span class="tok-w"> </span>:<span class="tok-w"> </span>native-path<span class="tok-w"> </span><span class="tok-nb">make</span>-path<span class="tok-w"> </span>;<span class="tok-w"></span></code></pre> 7202</div> 7203</div> 7204</li> 7205<li> 7206<p><code>rule clone-rules ( source-module target-module )</code></p> 7207<div class="paragraph"> 7208<p>Define exported copies in <code>$(target-module)</code> of all rules exported from 7209<code>$(source-module)</code>. Also make them available in the global module with 7210qualification, so that it is just as though the rules were defined 7211originally in <code>$(target-module)</code>.</p> 7212</div> 7213</li> 7214</ol> 7215</div> 7216</div> 7217<div class="sect3"> 7218<h4 id="bbv2.reference.modules.path"><a class="anchor" href="#bbv2.reference.modules.path"></a>5.5.2. path</h4> 7219<div class="paragraph"> 7220<p>Performs various path manipulations. Paths are always in a 'normalized' 7221representation. In it, a path may be either:</p> 7222</div> 7223<div class="ulist"> 7224<ul> 7225<li> 7226<p><code>'.'</code>, or</p> 7227</li> 7228<li> 7229<p><code>['/'] [ ( '..' '/' )* (token '/')* token ]</code></p> 7230</li> 7231</ul> 7232</div> 7233<div class="paragraph"> 7234<p>In plain english, a path can be rooted, <code>'..'</code> elements are allowed only 7235at the beginning, and it never ends in slash, except for the path 7236consisting of slash only.</p> 7237</div> 7238<div class="olist arabic"> 7239<ol class="arabic"> 7240<li> 7241<p><a id="bbv2.reference.modules.path.make"></a> <code>rule make ( native )</code></p> 7242<div class="paragraph"> 7243<p>Converts the native path into normalized form.</p> 7244</div> 7245</li> 7246<li> 7247<p><a id="bbv2.reference.modules.path.native"></a> <code>rule native ( path )</code></p> 7248<div class="paragraph"> 7249<p>Builds the native representation of the path.</p> 7250</div> 7251</li> 7252<li> 7253<p><a id="bbv2.reference.modules.path.is-rooted"></a> <code>rule is-rooted ( path )</code></p> 7254<div class="paragraph"> 7255<p>Tests if a path is rooted.</p> 7256</div> 7257</li> 7258<li> 7259<p><a id="bbv2.reference.modules.path.has-parent"></a> <code>rule has-parent ( path )</code></p> 7260<div class="paragraph"> 7261<p>Tests if a path has a parent.</p> 7262</div> 7263</li> 7264<li> 7265<p><a id="bbv2.reference.modules.path.basename"></a> <code>rule basename ( path )</code></p> 7266<div class="paragraph"> 7267<p>Returns the path without any directory components.</p> 7268</div> 7269</li> 7270<li> 7271<p><a id="bbv2.reference.modules.path.parent"></a> <code>rule parent ( path )</code></p> 7272<div class="paragraph"> 7273<p>Returns the parent directory of the path. If no parent exists, an error 7274is issued.</p> 7275</div> 7276</li> 7277<li> 7278<p><a id="bbv2.reference.modules.path.reverse"></a> <code>rule reverse ( path )</code></p> 7279<div class="paragraph"> 7280<p>Returns <code>path2</code> such that <code>[ join path path2 ] = "."</code>. The path may not 7281contain <code>".."</code> element or be rooted.</p> 7282</div> 7283</li> 7284<li> 7285<p><a id="bbv2.reference.modules.path.join"></a> <code>rule join ( elements + )</code></p> 7286<div class="paragraph"> 7287<p>Concatenates the passed path elements. Generates an error if any element 7288other than the first one is rooted. Skips any empty or undefined path 7289elements.</p> 7290</div> 7291</li> 7292<li> 7293<p><a id="bbv2.reference.modules.path.root"></a> <code>rule root ( path root )</code></p> 7294<div class="paragraph"> 7295<p>If <code>path</code> is relative, it is rooted at <code>root</code>. Otherwise, it is 7296unchanged.</p> 7297</div> 7298</li> 7299<li> 7300<p><a id="bbv2.reference.modules.path.pwd"></a> <code>rule pwd ( )</code></p> 7301<div class="paragraph"> 7302<p>Returns the current working directory.</p> 7303</div> 7304</li> 7305<li> 7306<p><a id="bbv2.reference.modules.path.glob"></a> <code>rule glob ( dirs * : patterns + : exclude-patterns * )</code></p> 7307<div class="paragraph"> 7308<p>Returns the list of files matching the given pattern in the specified 7309directory. Both directories and patterns are supplied as portable paths. 7310Each pattern should be a non-absolute path, and can’t contain "." or 7311".." elements. Each slash separated element of a pattern can contain the 7312following special characters:</p> 7313</div> 7314<div class="ulist"> 7315<ul> 7316<li> 7317<p>'?' matches any character</p> 7318</li> 7319<li> 7320<p>'*' matches an arbitrary number of characters</p> 7321<div class="paragraph"> 7322<p>A file <code>$(d)/e1/e2/e3</code> (where 'd' is in <code>$(dirs)</code>) matches the pattern 7323p1/p2/p3 if and only if e1 matches p1, e2 matches p2 and so on. For 7324example:</p> 7325</div> 7326<div class="listingblock"> 7327<div class="content"> 7328<pre class="pygments highlight"><code data-lang="jam"><span></span>[<span class="tok-w"> </span><span class="tok-nb">glob</span><span class="tok-w"> </span>.<span class="tok-w"> </span>:<span class="tok-w"> </span>*.cpp<span class="tok-w"> </span>]<span class="tok-w"></span> 7329[<span class="tok-w"> </span><span class="tok-nb">glob</span><span class="tok-w"> </span>.<span class="tok-w"> </span>:<span class="tok-w"> </span>*/build/Jamfile<span class="tok-w"> </span>]<span class="tok-w"></span></code></pre> 7330</div> 7331</div> 7332</li> 7333</ul> 7334</div> 7335</li> 7336<li> 7337<p><a id="bbv2.reference.modules.path.glob-tree"></a> <code>rule glob-tree ( roots * : patterns + : exclude-patterns * )</code></p> 7338<div class="paragraph"> 7339<p>Recursive version of <a href="#bbv2.reference.modules.path.glob">glob</a>. 7340Builds the glob of files while also searching in the subdirectories of 7341the given roots. An optional set of exclusion patterns will filter out 7342the matching entries from the result. The exclusions also apply to the 7343subdirectory scanning, such that directories that match the exclusion 7344patterns will not be searched.</p> 7345</div> 7346</li> 7347<li> 7348<p><a id="bbv2.reference.modules.path.exists"></a> <code>rule exists ( file )</code></p> 7349<div class="paragraph"> 7350<p>Returns true if the specified file exists.</p> 7351</div> 7352</li> 7353<li> 7354<p><a id="bbv2.reference.modules.path.all-parents"></a> <code>rule all-parents ( path : upper_limit ? : cwd ? )</code></p> 7355<div class="paragraph"> 7356<p>Find out the absolute name of path and return the list of all the 7357parents, starting with the immediate one. Parents are returned as 7358relative names. If <code>upper_limit</code> is specified, directories above it will 7359be pruned.</p> 7360</div> 7361</li> 7362<li> 7363<p><a id="bbv2.reference.modules.path.glob-in-parents"></a> <code>rule glob-in-parents ( dir : patterns + : upper-limit ? )</code></p> 7364<div class="paragraph"> 7365<p>Search for <code>patterns</code> in parent directories of <code>dir</code>, up to and 7366including <code>upper_limit</code>, if it is specified, or till the filesystem root 7367otherwise.</p> 7368</div> 7369</li> 7370<li> 7371<p><a id="bbv2.reference.modules.path.relative"></a> <code>rule relative ( child parent : no-error ? )</code></p> 7372<div class="paragraph"> 7373<p>Assuming <code>child</code> is a subdirectory of <code>parent</code>, return the relative path 7374from <code>parent</code> to <code>child</code>.</p> 7375</div> 7376</li> 7377<li> 7378<p><a id="bbv2.reference.modules.path.relative-to"></a> <code>rule relative-to ( path1 path2 )</code></p> 7379<div class="paragraph"> 7380<p>Returns the minimal path to path2 that is relative path1.</p> 7381</div> 7382</li> 7383<li> 7384<p><a id="bbv2.reference.modules.path.programs-path"></a> <code>rule programs-path ( )</code></p> 7385<div class="paragraph"> 7386<p>Returns the list of paths which are used by the operating system for 7387looking up programs.</p> 7388</div> 7389</li> 7390<li> 7391<p><a id="bbv2.reference.modules.path.makedirs"></a> <code>rule makedirs ( path )</code></p> 7392<div class="paragraph"> 7393<p>Creates a directory and all parent directories that do not already 7394exist.</p> 7395</div> 7396</li> 7397</ol> 7398</div> 7399</div> 7400<div class="sect3"> 7401<h4 id="bbv2.reference.modules.regex"><a class="anchor" href="#bbv2.reference.modules.regex"></a>5.5.3. regex</h4> 7402<div class="paragraph"> 7403<p>Contains rules for string processing using regular expressions.</p> 7404</div> 7405<div class="ulist"> 7406<ul> 7407<li> 7408<p><code>"x*"</code> matches the pattern <code>"x"</code> zero or more times.</p> 7409</li> 7410<li> 7411<p><code>"x+"</code> matches <code>"x"</code> one or more times.</p> 7412</li> 7413<li> 7414<p><code>"x?"</code> matches <code>"x"</code> zero or one time.</p> 7415</li> 7416<li> 7417<p><code>"[abcd]"</code> matches any of the characters, <code>"a"</code>, <code>"b"</code>, <code>"c"</code>, and 7418<code>"d"</code>. A character range such as <code>"[a-z]"</code> matches any character between 7419<code>"a"</code> and <code>"z"</code>. <code>"[^abc]"</code> matches any character which is not <code>"a"</code>, 7420<code>"b"</code>, or <code>"c"</code>.</p> 7421</li> 7422<li> 7423<p><code>"x|y"</code> matches either pattern <code>"x"</code> or pattern <code>"y"</code></p> 7424</li> 7425<li> 7426<p><code>(x)</code> matches <code>"x"</code> and captures it.</p> 7427</li> 7428<li> 7429<p><code>"^"</code> matches the beginning of the string.</p> 7430</li> 7431<li> 7432<p><code>"$"</code> matches the end of the string.</p> 7433</li> 7434<li> 7435<p>"\<" matches the beginning of a word.</p> 7436</li> 7437<li> 7438<p>"\>" matches the end of a word.</p> 7439<div class="olist arabic"> 7440<ol class="arabic"> 7441<li> 7442<p><a id="bbv2.reference.modules.regex.split"></a> <code>rule split ( string separator )</code></p> 7443<div class="paragraph"> 7444<p>Returns a list of the following substrings:</p> 7445</div> 7446<div class="olist loweralpha"> 7447<ol class="loweralpha" type="a"> 7448<li> 7449<p>from beginning till the first occurrence of <code>separator</code> or till the 7450end,</p> 7451</li> 7452<li> 7453<p>between each occurrence of <code>separator</code> and the next occurrence,</p> 7454</li> 7455<li> 7456<p>from the last occurrence of <code>separator</code> till the end.</p> 7457<div class="paragraph"> 7458<p>If no separator is present, the result will contain only one element.</p> 7459</div> 7460</li> 7461</ol> 7462</div> 7463</li> 7464<li> 7465<p><a id="bbv2.reference.modules.regex.split-list"></a> <code>rule split-list ( list * : separator )</code></p> 7466<div class="paragraph"> 7467<p>Returns the concatenated results of applying 7468<a href="#bbv2.reference.modules.regex.split">regex.split</a> to every element 7469of the list using the separator pattern.</p> 7470</div> 7471</li> 7472<li> 7473<p><a id="bbv2.reference.modules.regex.match"></a> <code>rule match ( pattern : string : indices * )</code></p> 7474<div class="paragraph"> 7475<p>Match <code>string</code> against <code>pattern</code>, and return the elements indicated by 7476<code>indices</code>.</p> 7477</div> 7478</li> 7479<li> 7480<p><a id="bbv2.reference.modules.regex.transform"></a> <code>rule transform ( list * : pattern : indices * )</code></p> 7481<div class="paragraph"> 7482<p>Matches all elements of <code>list</code> against the <code>pattern</code> and returns a list 7483of elements indicated by <code>indices</code> of all successful matches. If 7484<code>indices</code> is omitted returns a list of first parenthesized groups of all 7485successful matches.</p> 7486</div> 7487</li> 7488<li> 7489<p><a id="bbv2.reference.modules.regex.escape"></a> <code>rule escape ( string : symbols : escape-symbol )</code></p> 7490<div class="paragraph"> 7491<p>Escapes all of the characters in <code>symbols</code> using the escape symbol 7492<code>escape-symbol</code> for the given string, and returns the escaped string.</p> 7493</div> 7494</li> 7495<li> 7496<p><a id="bbv2.reference.modules.regex.replace"></a> <code>rule replace ( string match replacement )</code></p> 7497<div class="paragraph"> 7498<p>Replaces occurrences of a match string in a given string and returns the 7499new string. The match string can be a regex expression.</p> 7500</div> 7501</li> 7502<li> 7503<p><a id="bbv2.reference.modules.regex.replace-list"></a> <code>rule replace-list ( list * : match : replacement )</code></p> 7504<div class="paragraph"> 7505<p>Replaces occurrences of a match string in a given list of strings and 7506returns a list of new strings. The match string can be a regex 7507expression.</p> 7508</div> 7509</li> 7510</ol> 7511</div> 7512</li> 7513</ul> 7514</div> 7515<div class="paragraph"> 7516<p>See also: <a href="#jam.language.rules.builtins.utility._match__">MATCH</a></p> 7517</div> 7518</div> 7519<div class="sect3"> 7520<h4 id="bbv2.reference.modules.sequence"><a class="anchor" href="#bbv2.reference.modules.sequence"></a>5.5.4. sequence</h4> 7521<div class="paragraph"> 7522<p>Various useful list functions. Note that algorithms in this module 7523execute largely in the caller’s module namespace, so that local rules 7524can be used as function objects. Also note that most predicates can be 7525multi-element lists. In that case, all but the first element are 7526prepended to the first argument which is passed to the rule named by the 7527first element.</p> 7528</div> 7529<div class="olist arabic"> 7530<ol class="arabic"> 7531<li> 7532<p><code>rule filter ( predicate + : sequence * )</code></p> 7533<div class="paragraph"> 7534<p>Return the elements <code>e</code> of <code>$(sequence)</code> for which <code>[ $(predicate) e ]</code> 7535has a non-null value.</p> 7536</div> 7537</li> 7538<li> 7539<p><code>rule transform ( function + : sequence * )</code></p> 7540<div class="paragraph"> 7541<p>Return a new sequence consisting of <code>[ $(function) $(e) ]</code> for each 7542element <code>e</code> of <code>$(sequence)</code>.</p> 7543</div> 7544</li> 7545<li> 7546<p><code>rule reverse ( s * )</code></p> 7547<div class="paragraph"> 7548<p>Returns the elements of <code>s</code> in reverse order.</p> 7549</div> 7550</li> 7551<li> 7552<p><code>rule insertion-sort ( s * : ordered * )</code></p> 7553<div class="paragraph"> 7554<p>Insertion-sort <code>s</code> using the BinaryPredicate <code>ordered</code>.</p> 7555</div> 7556</li> 7557<li> 7558<p><code>rule merge ( s1 * : s2 * : ordered * )</code></p> 7559<div class="paragraph"> 7560<p>Merge two ordered sequences using the BinaryPredicate <code>ordered</code>.</p> 7561</div> 7562</li> 7563<li> 7564<p><code>rule join ( s * : joint ? )</code></p> 7565<div class="paragraph"> 7566<p>Join the elements of <code>s</code> into one long string. If <code>joint</code> is supplied, 7567it is used as a separator.</p> 7568</div> 7569</li> 7570<li> 7571<p><code>rule length ( s * )</code></p> 7572<div class="paragraph"> 7573<p>Find the length of any sequence.</p> 7574</div> 7575</li> 7576<li> 7577<p><code>rule unique ( list * : stable ? )</code></p> 7578<div class="paragraph"> 7579<p>Removes duplicates from <code>list</code>. If <code>stable</code> is passed, then the order of 7580the elements will be unchanged.</p> 7581</div> 7582</li> 7583<li> 7584<p><code>rule max-element ( elements + : ordered ? )</code></p> 7585<div class="paragraph"> 7586<p>Returns the maximum number in <code>elements</code>. Uses <code>ordered</code> for comparisons 7587or <code>numbers.less</code> if none is provided.</p> 7588</div> 7589</li> 7590<li> 7591<p><code>rule select-highest-ranked ( elements * : ranks * )</code></p> 7592<div class="paragraph"> 7593<p>Returns all of <code>elements</code> for which the corresponding element in the 7594parallel list <code>rank</code> is equal to the maximum value in <code>rank</code>.</p> 7595</div> 7596</li> 7597</ol> 7598</div> 7599</div> 7600<div class="sect3"> 7601<h4 id="bbv2.reference.modules.stage"><a class="anchor" href="#bbv2.reference.modules.stage"></a>5.5.5. stage</h4> 7602<div class="paragraph"> 7603<p>This module defines the <code>install</code> rule, used to copy a set of targets to a 7604single location.</p> 7605</div> 7606<div id="bbv2.reference.modules.stage.add-install-dir" class="olist arabic"> 7607<ol class="arabic"> 7608<li> 7609<p><code>rule add-install-dir ( name : suffix ? : parent ? : options * )</code></p> 7610<div class="paragraph"> 7611<p>Defines a named installation directory.</p> 7612</div> 7613<div class="paragraph"> 7614<p>For example, <code>add-install-dir foo : bar : baz ;</code> creates feature 7615<a href="#bbv2.builtin.features.install-prefix"><code><install-foo></code></a> and adds support for 7616named directory <code>(foo)</code> to <code>install</code> rule. The rule will try to use the value 7617of <code><install-foo></code> property if present, otherwise will fallback to <code>(baz)/bar</code>.</p> 7618</div> 7619<div class="paragraph"> 7620<p>Arguments:</p> 7621</div> 7622<div class="ulist"> 7623<ul> 7624<li> 7625<p><code>name</code>: the name of the directory.</p> 7626</li> 7627<li> 7628<p><code>suffix</code>: the path suffix appended to the parent named directory.</p> 7629</li> 7630<li> 7631<p><code>parent</code>: the optional name of parent named directory.</p> 7632</li> 7633<li> 7634<p><code>options</code>: special options that modify treatment of the directory. 7635Allowed options:</p> 7636<div class="ulist"> 7637<ul> 7638<li> 7639<p><code>package-suffix</code>: append the package name to the default value. For example:</p> 7640<div class="listingblock"> 7641<div class="content"> 7642<pre class="pygments highlight"><code data-lang="jam"><span></span>add-install-dir<span class="tok-w"> </span>foo<span class="tok-w"> </span>:<span class="tok-w"> </span>bar<span class="tok-w"> </span>:<span class="tok-w"> </span>baz<span class="tok-w"> </span>:<span class="tok-w"> </span>package-suffix<span class="tok-w"> </span>;<span class="tok-w"></span> 7643<span class="tok-nb">install</span><span class="tok-w"> </span>(foo)<span class="tok-w"> </span>:<span class="tok-w"> </span>a<span class="tok-w"> </span>:<span class="tok-w"> </span><span class="tok-na"><install-package></span>xyz<span class="tok-w"> </span>;<span class="tok-w"></span></code></pre> 7644</div> 7645</div> 7646<div class="paragraph"> 7647<p>installs <code>a</code> into <code>(baz)/bar/xyz</code>.</p> 7648</div> 7649</li> 7650</ul> 7651</div> 7652</li> 7653</ul> 7654</div> 7655</li> 7656<li> 7657<p><code>rule install-dir-names ( )</code></p> 7658<div class="paragraph"> 7659<p>Returns names of all registered installation directories.</p> 7660</div> 7661</li> 7662<li> 7663<p><code>rule get-dir ( name : property-set : package-name : flags * )</code></p> 7664<div class="paragraph"> 7665<p>Returns the path to a named installation directory. For a given <code>name=xyz</code> the 7666rule uses the value of <code><install-xyz></code> property if it is present in 7667<code>property-set</code>. Otherwise it tries to construct the default value of the path 7668recursively getting the path to <code>name</code>'s registered base named directory and 7669relative path. For example:</p> 7670</div> 7671<div class="listingblock"> 7672<div class="content"> 7673<pre class="pygments highlight"><code data-lang="jam"><span></span>stage.add-install-dir<span class="tok-w"> </span>foo<span class="tok-w"> </span>:<span class="tok-w"> </span>bar<span class="tok-w"> </span>:<span class="tok-w"> </span>baz<span class="tok-w"> </span>;<span class="tok-w"></span> 7674 7675<span class="tok-k">local</span><span class="tok-w"> </span>ps<span class="tok-w"> </span>=<span class="tok-w"> </span>[<span class="tok-w"> </span>property-set.create<span class="tok-w"> </span><span class="tok-na"><install-foo></span>x/y/z<span class="tok-w"> </span>]<span class="tok-w"> </span>;<span class="tok-w"></span> 7676<span class="tok-nb">echo</span><span class="tok-w"> </span>[<span class="tok-w"> </span>stage.get-dir<span class="tok-w"> </span>foo<span class="tok-w"> </span>:<span class="tok-w"> </span><span class="tok-si">$(ps)</span><span class="tok-w"> </span>:<span class="tok-w"> </span><span class="tok-si">$(__name__)</span><span class="tok-w"> </span>]<span class="tok-w"> </span>;<span class="tok-w"> </span><span class="tok-c1"># outputs x/y/z</span> 7677 7678ps<span class="tok-w"> </span>=<span class="tok-w"> </span>[<span class="tok-w"> </span>property-set.create<span class="tok-w"> </span><span class="tok-na"><install-baz></span>a/b/c/d<span class="tok-w"> </span>]<span class="tok-w"> </span>;<span class="tok-w"></span> 7679<span class="tok-nb">echo</span><span class="tok-w"> </span>[<span class="tok-w"> </span>stage.get-dir<span class="tok-w"> </span>foo<span class="tok-w"> </span>:<span class="tok-w"> </span><span class="tok-si">$(ps)</span><span class="tok-w"> </span>:<span class="tok-w"> </span><span class="tok-si">$(__name__)</span><span class="tok-w"> </span>]<span class="tok-w"> </span>;<span class="tok-w"> </span><span class="tok-c1"># outputs a/b/c/d/bar</span></code></pre> 7680</div> 7681</div> 7682<div class="paragraph"> 7683<p>The argument <code>package-name</code> is used to construct the path for named directories 7684that were registered with <code>package-suffix</code> option and also to construct 7685<code>install-prefix</code> when targeting Windows.</p> 7686</div> 7687<div class="paragraph"> 7688<p>Available <code>flags</code>:</p> 7689</div> 7690<div class="ulist"> 7691<ul> 7692<li> 7693<p><code>staged</code>: take <a href="#bbv2.builtin.features.staging-prefix"><code>staging-prefix</code></a> into 7694account.</p> 7695</li> 7696<li> 7697<p><code>relative</code>: return the path to <code>name</code> relative to its base directory.</p> 7698</li> 7699</ul> 7700</div> 7701</li> 7702<li> 7703<p><code>rule get-package-name ( property-set : project-module ? )</code></p> 7704<div class="paragraph"> 7705<p>Returns the package name that will be used for <code>install</code> targets when 7706constructing installation location. The rule uses the value of 7707<a href="#bbv2.builtin.features.install-package"><code><install-package></code></a> property if it’s 7708present in <code>property-set</code>. Otherwise it deduces the package name using 7709<code>project-module</code>'s attributes. It traverses the project hierarchy up to the 7710root searching for the first project with an id. If none is found, the base 7711name of the root project’s location is used. If <code>project-module</code> is empty, the 7712caller module is used (this allows invoking just <code>[ get-package-name $(ps) ]</code> 7713in project jam files).</p> 7714</div> 7715</li> 7716</ol> 7717</div> 7718</div> 7719<div class="sect3"> 7720<h4 id="bbv2.reference.modules.type"><a class="anchor" href="#bbv2.reference.modules.type"></a>5.5.6. type</h4> 7721<div class="paragraph"> 7722<p>Deals with target type declaration and defines target class which 7723supports typed targets.</p> 7724</div> 7725<div class="olist arabic"> 7726<ol class="arabic"> 7727<li> 7728<p><a id="bbv2.reference.modules.type.register"></a> <code>rule register ( type : suffixes * : base-type ? )</code></p> 7729<div class="paragraph"> 7730<p>Registers a target type, possible derived from a <code>base-type</code>. Providing 7731a list of suffixes here is a shortcut for separately calling the 7732<a href="#bbv2.reference.modules.type.register-suffixes">register-suffixes</a> 7733rule with the given suffixes and the 7734<a href="#bbv2.reference.modules.type.set-generated-target-suffix">set-generated-target-suffix</a> 7735rule with the first given suffix.</p> 7736</div> 7737</li> 7738<li> 7739<p><a id="bbv2.reference.modules.type.register-suffixes"></a> <code>rule register-suffixes ( suffixes + : type )</code></p> 7740<div class="paragraph"> 7741<p>Specifies that files with suffix from <code>suffixes</code> be recognized as 7742targets of type <code>type</code>. Issues an error if a different type is already 7743specified for any of the suffixes.</p> 7744</div> 7745</li> 7746<li> 7747<p><a id="bbv2.reference.modules.type.registered"></a> <code>rule registered ( type )</code></p> 7748<div class="paragraph"> 7749<p>Returns true iff type has been registered.</p> 7750</div> 7751</li> 7752<li> 7753<p><a id="bbv2.reference.modules.type.validate"></a> <code>rule validate ( type )</code></p> 7754<div class="paragraph"> 7755<p>Issues an error if <code>type</code> is unknown.</p> 7756</div> 7757</li> 7758<li> 7759<p><a id="bbv2.reference.modules.type.set-scanner"></a> <code>rule set-scanner ( type : scanner )</code></p> 7760<div class="paragraph"> 7761<p>Sets a scanner class that will be used for this type.</p> 7762</div> 7763</li> 7764<li> 7765<p><a id="bbv2.reference.modules.type.get-scanner"></a> <code>rule get-scanner ( type : property-set )</code></p> 7766<div class="paragraph"> 7767<p>Returns a scanner instance appropriate to <code>type</code> and <code>property-set</code>.</p> 7768</div> 7769</li> 7770<li> 7771<p><a id="bbv2.reference.modules.type.base"></a> <code>rule base ( type )</code></p> 7772<div class="paragraph"> 7773<p>Returns a base type for the given type or nothing in case the given type 7774is not derived.</p> 7775</div> 7776</li> 7777<li> 7778<p><a id="bbv2.reference.modules.type.all-bases"></a> <code>rule all-bases ( type )</code></p> 7779<div class="paragraph"> 7780<p>Returns the given type and all of its base types in order of their 7781distance from type.</p> 7782</div> 7783</li> 7784<li> 7785<p><a id="bbv2.reference.modules.type.all-derived"></a> <code>rule all-derived ( type )</code></p> 7786<div class="paragraph"> 7787<p>Returns the given type and all of its derived types in order of their 7788distance from type.</p> 7789</div> 7790</li> 7791<li> 7792<p><a id="bbv2.reference.modules.type.is-derived"></a> <code>rule is-derived ( type base )</code></p> 7793<div class="paragraph"> 7794<p>Returns true if <code>type</code> is equal to <code>base</code> or has <code>base</code> as its direct or 7795indirect base.</p> 7796</div> 7797</li> 7798<li> 7799<p><a id="bbv2.reference.modules.type.set-generated-target-suffix"></a> <code>rule set-generated-target-suffix ( type : properties * : suffix )</code></p> 7800<div class="paragraph"> 7801<p>Sets a file suffix to be used when generating a target of <code>type</code> with 7802the specified properties. Can be called with no properties if no suffix 7803has already been specified for the <code>type</code>. The <code>suffix</code> parameter can be 7804an empty string (<code>""</code>) to indicate that no suffix should be used.</p> 7805</div> 7806<div class="paragraph"> 7807<p>Note that this does not cause files with <code>suffix</code> to be automatically 7808recognized as being of <code>type</code>. Two different types can use the same 7809suffix for their generated files but only one type can be auto-detected 7810for a file with that suffix. User should explicitly specify which one 7811using the 7812<a href="#bbv2.reference.modules.type.register-suffixes">register-suffixes</a> 7813rule.</p> 7814</div> 7815</li> 7816<li> 7817<p><a id="bbv2.reference.modules.type.change-generated-target-suffix"></a> <code>rule change-generated-target-suffix ( type : properties * : suffix )</code></p> 7818<div class="paragraph"> 7819<p>Change the suffix previously registered for this type/properties 7820combination. If suffix is not yet specified, sets it.</p> 7821</div> 7822</li> 7823<li> 7824<p><a id="bbv2.reference.modules.type.generated-target-suffix"></a> <code>rule generated-target-suffix ( type : property-set )</code></p> 7825<div class="paragraph"> 7826<p>Returns the suffix used when generating a file of <code>type</code> with the given 7827properties.</p> 7828</div> 7829</li> 7830<li> 7831<p><a id="bbv2.reference.modules.type.set-generated-target-prefix"></a> <code>rule set-generated-target-prefix ( type : properties * : prefix )</code></p> 7832<div class="paragraph"> 7833<p>Sets a target prefix that should be used when generating targets of 7834<code>type</code> with the specified properties. Can be called with empty 7835properties if no prefix for <code>type</code> has been specified yet.</p> 7836</div> 7837<div class="paragraph"> 7838<p>The <code>prefix</code> parameter can be empty string (<code>""</code>) to indicate that no 7839prefix should be used.</p> 7840</div> 7841<div class="paragraph"> 7842<p>Usage example: library names use the <code>"lib"</code> prefix on unix.</p> 7843</div> 7844</li> 7845<li> 7846<p><a id="bbv2.reference.modules.type.change-generated-target-prefix"></a> <code>rule change-generated-target-prefix ( type : properties * : prefix )</code></p> 7847<div class="paragraph"> 7848<p>Change the prefix previously registered for this type/properties 7849combination. If prefix is not yet specified, sets it.</p> 7850</div> 7851</li> 7852<li> 7853<p><a id="bbv2.reference.modules.type.generated-target-prefix"></a> <code>rule generated-target-prefix ( type : property-set )</code></p> 7854<div class="paragraph"> 7855<p>Returns the prefix used when generating a file of <code>type</code> with the given 7856properties.</p> 7857</div> 7858</li> 7859<li> 7860<p><a id="bbv2.reference.modules.type.type"></a> <code>rule type ( filename )</code></p> 7861<div class="paragraph"> 7862<p>Returns file type given its name. If there are several dots in filename, 7863tries each suffix. E.g. for name of "file.so.1.2" suffixes "2", "1", and 7864"so" will be tried.</p> 7865</div> 7866</li> 7867</ol> 7868</div> 7869</div> 7870</div> 7871<div class="sect2"> 7872<h3 id="bbv2.reference.class"><a class="anchor" href="#bbv2.reference.class"></a>5.6. Builtin classes</h3> 7873<div class="sect3"> 7874<h4 id="bbv2.reference.class.abstract-target"><a class="anchor" href="#bbv2.reference.class.abstract-target"></a>5.6.1. Class abstract-target</h4> 7875<div class="paragraph"> 7876<p>Base class for all abstract targets.</p> 7877</div> 7878<div class="listingblock"> 7879<div class="content"> 7880<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-k">class</span><span class="tok-w"> </span><span class="tok-nc">abstract-target</span><span class="tok-w"> </span>{<span class="tok-w"></span> 7881<span class="tok-w"> </span><span class="tok-k">rule</span><span class="tok-w"> </span><span class="tok-nf">__init__</span><span class="tok-w"> </span><span class="tok-p">(</span><span class="tok-w"> </span><span class="tok-nv">name</span><span class="tok-w"> </span><span class="tok-p">:</span><span class="tok-w"> </span><span class="tok-nv">project</span><span class="tok-w"> </span><span class="tok-p">)</span><span class="tok-w"></span> 7882<span class="tok-w"> </span><span class="tok-k">rule</span><span class="tok-w"> </span><span class="tok-nf">name</span><span class="tok-w"> </span><span class="tok-p">(</span><span class="tok-w"> </span><span class="tok-p">)</span><span class="tok-w"></span> 7883<span class="tok-w"> </span><span class="tok-k">rule</span><span class="tok-w"> </span><span class="tok-nf">project</span><span class="tok-w"> </span><span class="tok-p">(</span><span class="tok-w"> </span><span class="tok-p">)</span><span class="tok-w"></span> 7884<span class="tok-w"> </span><span class="tok-k">rule</span><span class="tok-w"> </span><span class="tok-nf">location</span><span class="tok-w"> </span><span class="tok-p">(</span><span class="tok-w"> </span><span class="tok-p">)</span><span class="tok-w"></span> 7885<span class="tok-w"> </span><span class="tok-k">rule</span><span class="tok-w"> </span><span class="tok-nf">full-name</span><span class="tok-w"> </span><span class="tok-p">(</span><span class="tok-w"> </span><span class="tok-p">)</span><span class="tok-w"></span> 7886<span class="tok-w"> </span><span class="tok-k">rule</span><span class="tok-w"> </span><span class="tok-nf">generate</span><span class="tok-w"> </span><span class="tok-p">(</span><span class="tok-w"> </span><span class="tok-nv">property-set</span><span class="tok-w"> </span><span class="tok-p">)</span><span class="tok-w"></span> 7887}<span class="tok-w"></span></code></pre> 7888</div> 7889</div> 7890<div class="paragraph"> 7891<p>Classes derived from 7892<a href="#bbv2.reference.class.abstract-target">abstract-target</a>:</p> 7893</div> 7894<div class="ulist"> 7895<ul> 7896<li> 7897<p>project-target</p> 7898</li> 7899<li> 7900<p>main-target</p> 7901</li> 7902<li> 7903<p>basic-target</p> 7904</li> 7905</ul> 7906</div> 7907<div class="openblock"> 7908<div class="content"> 7909<div class="olist arabic"> 7910<ol class="arabic"> 7911<li> 7912<p><code>rule <em>init</em> ( name : project )</code></p> 7913<div class="dlist"> 7914<dl> 7915<dt class="hdlist1"><code>name</code></dt> 7916<dd> 7917<p>The name of the target in the Jamfile.</p> 7918</dd> 7919<dt class="hdlist1"><code>project</code></dt> 7920<dd> 7921<p>The <a href="#bbv2.reference.class.project-target">project</a> to which this 7922target belongs.</p> 7923</dd> 7924</dl> 7925</div> 7926</li> 7927<li> 7928<p><code>rule name ( )</code></p> 7929<div class="paragraph"> 7930<p>Returns the name of this target.</p> 7931</div> 7932</li> 7933<li> 7934<p><code>rule project ( )</code></p> 7935<div class="paragraph"> 7936<p>Returns the <a href="#bbv2.reference.class.project-target">project</a> for this 7937target.</p> 7938</div> 7939</li> 7940<li> 7941<p><code>rule location ( )</code></p> 7942<div class="paragraph"> 7943<p>Returns the location where the target was declared.</p> 7944</div> 7945</li> 7946<li> 7947<p><code>rule full-name ( )</code></p> 7948<div class="paragraph"> 7949<p>Returns a user-readable name for this target.</p> 7950</div> 7951</li> 7952<li> 7953<p><a id="bbv2.reference.class.abstract-target.generate"></a> <code>rule generate ( property-set )</code></p> 7954<div class="paragraph"> 7955<p>Generates virtual targets for this abstract target using the specified 7956properties, unless a different value of some feature is required by the 7957target. This is an abstract method which must be overridden by derived 7958classes.</p> 7959</div> 7960<div class="paragraph"> 7961<p>On success, returns:</p> 7962</div> 7963<div class="ulist"> 7964<ul> 7965<li> 7966<p>a property-set with the usage requirements to be applied to dependents</p> 7967</li> 7968<li> 7969<p>a list of produced virtual targets, which may be empty.</p> 7970<div class="paragraph"> 7971<p>If <code>property-set</code> is empty, performs the default build of this target, 7972in a way specific to the derived class.</p> 7973</div> 7974</li> 7975</ul> 7976</div> 7977</li> 7978</ol> 7979</div> 7980</div> 7981</div> 7982</div> 7983<div class="sect3"> 7984<h4 id="bbv2.reference.class.project-target"><a class="anchor" href="#bbv2.reference.class.project-target"></a>5.6.2. Class project-target</h4> 7985<div class="listingblock"> 7986<div class="content"> 7987<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-k">class</span><span class="tok-w"> </span><span class="tok-nc">project-target</span><span class="tok-w"> </span><span class="tok-p">:</span><span class="tok-w"> </span><span class="tok-nc">abstract-target</span><span class="tok-w"> </span>{<span class="tok-w"></span> 7988<span class="tok-w"> </span><span class="tok-k">rule</span><span class="tok-w"> </span><span class="tok-nf">generate</span><span class="tok-w"> </span><span class="tok-p">(</span><span class="tok-w"> </span><span class="tok-nv">property-set</span><span class="tok-w"> </span><span class="tok-p">)</span><span class="tok-w"></span> 7989<span class="tok-w"> </span><span class="tok-k">rule</span><span class="tok-w"> </span><span class="tok-nf">build-dir</span><span class="tok-w"> </span><span class="tok-p">(</span><span class="tok-w"> </span><span class="tok-p">)</span><span class="tok-w"></span> 7990<span class="tok-w"> </span><span class="tok-k">rule</span><span class="tok-w"> </span><span class="tok-nf">main-target</span><span class="tok-w"> </span><span class="tok-p">(</span><span class="tok-w"> </span><span class="tok-nv">name</span><span class="tok-w"> </span><span class="tok-p">)</span><span class="tok-w"></span> 7991<span class="tok-w"> </span><span class="tok-k">rule</span><span class="tok-w"> </span><span class="tok-nf">has-main-target</span><span class="tok-w"> </span><span class="tok-p">(</span><span class="tok-w"> </span><span class="tok-nv">name</span><span class="tok-w"> </span><span class="tok-p">)</span><span class="tok-w"></span> 7992<span class="tok-w"> </span><span class="tok-k">rule</span><span class="tok-w"> </span><span class="tok-nf">find</span><span class="tok-w"> </span><span class="tok-p">(</span><span class="tok-w"> </span><span class="tok-nv">id</span><span class="tok-w"> </span><span class="tok-p">:</span><span class="tok-w"> </span><span class="tok-nv">no-error</span><span class="tok-w"> </span><span class="tok-p">?</span><span class="tok-w"> </span><span class="tok-p">)</span><span class="tok-w"></span> 7993 7994<span class="tok-w"> </span><span class="tok-c1"># Methods inherited from abstract-target</span> 7995<span class="tok-w"> </span><span class="tok-k">rule</span><span class="tok-w"> </span><span class="tok-nf">name</span><span class="tok-w"> </span><span class="tok-p">(</span><span class="tok-w"> </span><span class="tok-p">)</span><span class="tok-w"></span> 7996<span class="tok-w"> </span><span class="tok-k">rule</span><span class="tok-w"> </span><span class="tok-nf">project</span><span class="tok-w"> </span><span class="tok-p">(</span><span class="tok-w"> </span><span class="tok-p">)</span><span class="tok-w"></span> 7997<span class="tok-w"> </span><span class="tok-k">rule</span><span class="tok-w"> </span><span class="tok-nf">location</span><span class="tok-w"> </span><span class="tok-p">(</span><span class="tok-w"> </span><span class="tok-p">)</span><span class="tok-w"></span> 7998<span class="tok-w"> </span><span class="tok-k">rule</span><span class="tok-w"> </span><span class="tok-nf">full-name</span><span class="tok-w"> </span><span class="tok-p">(</span><span class="tok-w"> </span><span class="tok-p">)</span><span class="tok-w"></span> 7999}<span class="tok-w"></span></code></pre> 8000</div> 8001</div> 8002<div class="paragraph"> 8003<p>This class has the following responsibilities:</p> 8004</div> 8005<div class="ulist"> 8006<ul> 8007<li> 8008<p>Maintaining a list of main targets in this project and building them.</p> 8009</li> 8010</ul> 8011</div> 8012<div class="openblock"> 8013<div class="content"> 8014<div class="olist arabic"> 8015<ol class="arabic"> 8016<li> 8017<p><a id="bbv2.reference.class.project-target.generate"></a> <code>rule generate ( property-set )</code></p> 8018<div class="paragraph"> 8019<p>Overrides 8020<a href="#bbv2.reference.class.abstract-target.generate">abstract-target.generate</a>. 8021Generates virtual targets for all the targets contained in this project.</p> 8022</div> 8023<div class="paragraph"> 8024<p>On success, returns:</p> 8025</div> 8026<div class="ulist"> 8027<ul> 8028<li> 8029<p>a property-set with the usage requirements to be applied to dependents</p> 8030</li> 8031<li> 8032<p>a list of produced virtual targets, which may be empty.</p> 8033</li> 8034</ul> 8035</div> 8036</li> 8037<li> 8038<p><code>rule build-dir ( )</code></p> 8039<div class="paragraph"> 8040<p>Returns the root build directory of the project.</p> 8041</div> 8042</li> 8043<li> 8044<p><code>rule main-target ( name )</code></p> 8045<div class="paragraph"> 8046<p>Returns a <a href="#bbv2.reference.class.main-target">main-target</a> class 8047instance corresponding to <code>name</code>. Can only be called after the project 8048has been fully loaded.</p> 8049</div> 8050</li> 8051<li> 8052<p><code>rule has-main-target ( name )</code></p> 8053<div class="paragraph"> 8054<p>Returns whether a <a href="#bbv2.reference.class.main-target">main-target</a> 8055with the specified name exists. Can only be called after the project has 8056been fully loaded.</p> 8057</div> 8058</li> 8059<li> 8060<p><code>rule find ( id : no-error ? )</code></p> 8061<div class="paragraph"> 8062<p>Find and return the target with the specified id, treated relative to 8063self. Id may specify either a target or a file name with the target 8064taking priority. May report an error or return nothing if the target is 8065not found depending on the <code>no-error</code> parameter.</p> 8066</div> 8067</li> 8068</ol> 8069</div> 8070</div> 8071</div> 8072</div> 8073<div class="sect3"> 8074<h4 id="bbv2.reference.class.main-target"><a class="anchor" href="#bbv2.reference.class.main-target"></a>5.6.3. Class main-target</h4> 8075<div class="listingblock"> 8076<div class="content"> 8077<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-k">class</span><span class="tok-w"> </span><span class="tok-nc">main-target</span><span class="tok-w"> </span><span class="tok-p">:</span><span class="tok-w"> </span><span class="tok-nc">abstract-target</span><span class="tok-w"> </span>{<span class="tok-w"></span> 8078<span class="tok-w"> </span><span class="tok-k">rule</span><span class="tok-w"> </span><span class="tok-nf">generate</span><span class="tok-w"> </span><span class="tok-p">(</span><span class="tok-w"> </span><span class="tok-nv">property-set</span><span class="tok-w"> </span><span class="tok-p">)</span><span class="tok-w"></span> 8079 8080<span class="tok-w"> </span><span class="tok-c1"># Methods inherited from abstract-target</span> 8081<span class="tok-w"> </span><span class="tok-k">rule</span><span class="tok-w"> </span><span class="tok-nf">name</span><span class="tok-w"> </span><span class="tok-p">(</span><span class="tok-w"> </span><span class="tok-p">)</span><span class="tok-w"></span> 8082<span class="tok-w"> </span><span class="tok-k">rule</span><span class="tok-w"> </span><span class="tok-nf">project</span><span class="tok-w"> </span><span class="tok-p">(</span><span class="tok-w"> </span><span class="tok-p">)</span><span class="tok-w"></span> 8083<span class="tok-w"> </span><span class="tok-k">rule</span><span class="tok-w"> </span><span class="tok-nf">location</span><span class="tok-w"> </span><span class="tok-p">(</span><span class="tok-w"> </span><span class="tok-p">)</span><span class="tok-w"></span> 8084<span class="tok-w"> </span><span class="tok-k">rule</span><span class="tok-w"> </span><span class="tok-nf">full-name</span><span class="tok-w"> </span><span class="tok-p">(</span><span class="tok-w"> </span><span class="tok-p">)</span><span class="tok-w"></span> 8085}<span class="tok-w"></span></code></pre> 8086</div> 8087</div> 8088<div class="paragraph"> 8089<p>A <a href="#bbv2.reference.class.main-target">main-target</a> represents a named 8090top-level target in a Jamfile.</p> 8091</div> 8092<div class="openblock"> 8093<div class="content"> 8094<div class="olist arabic"> 8095<ol class="arabic"> 8096<li> 8097<p><a id="bbv2.reference.class.main-target.generate"></a> <code>rule generate ( property-set )</code></p> 8098<div class="paragraph"> 8099<p>Overrides 8100<a href="#bbv2.reference.class.abstract-target.generate">abstract-target.generate</a>. 8101Select an alternative for this main target, by finding all alternatives 8102whose requirements are satisfied by <code>property-set</code> and picking the one 8103with the longest requirements set. Returns the result of calling 8104<a href="#bbv2.reference.class.basic-target.generate">generate</a> on that 8105alternative.</p> 8106</div> 8107<div class="paragraph"> 8108<p>On success, returns:</p> 8109</div> 8110<div class="ulist"> 8111<ul> 8112<li> 8113<p>a property-set with the usage requirements to be applied to dependents</p> 8114</li> 8115<li> 8116<p>a list of produced virtual targets, which may be empty.</p> 8117</li> 8118</ul> 8119</div> 8120</li> 8121</ol> 8122</div> 8123</div> 8124</div> 8125</div> 8126<div class="sect3"> 8127<h4 id="bbv2.reference.class.basic-target"><a class="anchor" href="#bbv2.reference.class.basic-target"></a>5.6.4. Class basic-target</h4> 8128<div class="listingblock"> 8129<div class="content"> 8130<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-k">class</span><span class="tok-w"> </span><span class="tok-nc">basic-target</span><span class="tok-w"> </span><span class="tok-p">:</span><span class="tok-w"> </span><span class="tok-nc">abstract-target</span><span class="tok-w"> </span>{<span class="tok-w"></span> 8131<span class="tok-w"> </span><span class="tok-k">rule</span><span class="tok-w"> </span><span class="tok-nf">__init__</span><span class="tok-w"> </span><span class="tok-p">(</span><span class="tok-w"> </span><span class="tok-nv">name</span><span class="tok-w"> </span><span class="tok-p">:</span><span class="tok-w"> </span><span class="tok-nv">project</span><span class="tok-w"> </span><span class="tok-p">:</span><span class="tok-w"> </span><span class="tok-nv">sources</span><span class="tok-w"> </span><span class="tok-p">*</span><span class="tok-w"> </span><span class="tok-p">:</span><span class="tok-w"> </span><span class="tok-nv">requirements</span><span class="tok-w"> </span><span class="tok-p">*</span><span class="tok-w"> </span><span class="tok-p">:</span><span class="tok-w"> </span><span class="tok-nv">default-build</span><span class="tok-w"> </span><span class="tok-p">*</span><span class="tok-w"> </span><span class="tok-p">:</span><span class="tok-w"> </span><span class="tok-nv">usage-requirements</span><span class="tok-w"> </span><span class="tok-p">*</span><span class="tok-w"> </span><span class="tok-p">)</span><span class="tok-w"></span> 8132<span class="tok-w"> </span><span class="tok-k">rule</span><span class="tok-w"> </span><span class="tok-nf">generate</span><span class="tok-w"> </span><span class="tok-p">(</span><span class="tok-w"> </span><span class="tok-nv">property-set</span><span class="tok-w"> </span><span class="tok-p">)</span><span class="tok-w"></span> 8133<span class="tok-w"> </span><span class="tok-k">rule</span><span class="tok-w"> </span><span class="tok-nf">construct</span><span class="tok-w"> </span><span class="tok-p">(</span><span class="tok-w"> </span><span class="tok-nv">name</span><span class="tok-w"> </span><span class="tok-p">:</span><span class="tok-w"> </span><span class="tok-nv">source-targets</span><span class="tok-w"> </span><span class="tok-p">*</span><span class="tok-w"> </span><span class="tok-p">:</span><span class="tok-w"> </span><span class="tok-nv">property-set</span><span class="tok-w"> </span><span class="tok-p">)</span><span class="tok-w"></span> 8134 8135<span class="tok-w"> </span><span class="tok-c1"># Methods inherited from abstract-target</span> 8136<span class="tok-w"> </span><span class="tok-k">rule</span><span class="tok-w"> </span><span class="tok-nf">name</span><span class="tok-w"> </span><span class="tok-p">(</span><span class="tok-w"> </span><span class="tok-p">)</span><span class="tok-w"></span> 8137<span class="tok-w"> </span><span class="tok-k">rule</span><span class="tok-w"> </span><span class="tok-nf">project</span><span class="tok-w"> </span><span class="tok-p">(</span><span class="tok-w"> </span><span class="tok-p">)</span><span class="tok-w"></span> 8138<span class="tok-w"> </span><span class="tok-k">rule</span><span class="tok-w"> </span><span class="tok-nf">location</span><span class="tok-w"> </span><span class="tok-p">(</span><span class="tok-w"> </span><span class="tok-p">)</span><span class="tok-w"></span> 8139<span class="tok-w"> </span><span class="tok-k">rule</span><span class="tok-w"> </span><span class="tok-nf">full-name</span><span class="tok-w"> </span><span class="tok-p">(</span><span class="tok-w"> </span><span class="tok-p">)</span><span class="tok-w"></span> 8140}<span class="tok-w"></span></code></pre> 8141</div> 8142</div> 8143<div class="paragraph"> 8144<p>Implements the most standard way of constructing main target alternative 8145from sources. Allows sources to be either files or other main targets 8146and handles generation of those dependency targets.</p> 8147</div> 8148<div class="openblock"> 8149<div class="content"> 8150<div class="olist arabic"> 8151<ol class="arabic"> 8152<li> 8153<p><code>rule <em>init</em> ( name : project : sources * : requirements * : default-build * : usage-requirements * )</code></p> 8154<div class="dlist"> 8155<dl> 8156<dt class="hdlist1"><code>name</code></dt> 8157<dd> 8158<p>The name of the target</p> 8159</dd> 8160<dt class="hdlist1"><code>project</code></dt> 8161<dd> 8162<p>The <a href="#bbv2.reference.class.project-target">project</a> in which the 8163target is declared.</p> 8164</dd> 8165</dl> 8166</div> 8167</li> 8168<li> 8169<p><a id="bbv2.reference.class.basic-target.generate"></a> <code>rule generate ( property-set )</code></p> 8170<div class="paragraph"> 8171<p>Overrides 8172<a href="#bbv2.reference.class.abstract-target.generate">abstract-target.generate</a>. 8173Determines final build properties, generates sources, and calls 8174<a href="#bbv2.reference.class.basic-target.construct">construct</a>. This 8175method should not be overridden.</p> 8176</div> 8177<div class="paragraph"> 8178<p>On success, returns:</p> 8179</div> 8180<div class="ulist"> 8181<ul> 8182<li> 8183<p>a property-set with the usage requirements to be applied to dependents</p> 8184</li> 8185<li> 8186<p>a list of produced virtual targets, which may be empty.</p> 8187</li> 8188</ul> 8189</div> 8190</li> 8191<li> 8192<p><a id="bbv2.reference.class.basic-target.construct"></a> <code>rule construct ( name : source-targets * : property-set )</code></p> 8193<div class="paragraph"> 8194<p>Constructs virtual targets for this abstract target. Returns a 8195usage-requirements property-set and a list of virtual targets. Should be 8196overridden in derived classes.</p> 8197</div> 8198</li> 8199</ol> 8200</div> 8201</div> 8202</div> 8203</div> 8204<div class="sect3"> 8205<h4 id="bbv2.reference.class.typed-target"><a class="anchor" href="#bbv2.reference.class.typed-target"></a>5.6.5. Class typed-target</h4> 8206<div class="listingblock"> 8207<div class="content"> 8208<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-k">class</span><span class="tok-w"> </span><span class="tok-nc">typed-target</span><span class="tok-w"> </span><span class="tok-p">:</span><span class="tok-w"> </span><span class="tok-nc">basic-target</span><span class="tok-w"> </span>{<span class="tok-w"></span> 8209<span class="tok-w"> </span><span class="tok-k">rule</span><span class="tok-w"> </span><span class="tok-nf">__init__</span><span class="tok-w"> </span><span class="tok-p">(</span><span class="tok-w"> </span><span class="tok-nv">name</span><span class="tok-w"> </span><span class="tok-p">:</span><span class="tok-w"> </span><span class="tok-nv">project</span><span class="tok-w"> </span><span class="tok-p">:</span><span class="tok-w"> </span><span class="tok-nv">type</span><span class="tok-w"> </span><span class="tok-p">:</span><span class="tok-w"> </span><span class="tok-nv">sources</span><span class="tok-w"> </span><span class="tok-p">*</span><span class="tok-w"> </span><span class="tok-p">:</span><span class="tok-w"> </span><span class="tok-nv">requirements</span><span class="tok-w"> </span><span class="tok-p">*</span><span class="tok-w"> </span><span class="tok-p">:</span><span class="tok-w"> </span><span class="tok-nv">default-build</span><span class="tok-w"> </span><span class="tok-p">*</span><span class="tok-w"> </span><span class="tok-p">:</span><span class="tok-w"> </span><span class="tok-nv">usage-requirements</span><span class="tok-w"> </span><span class="tok-p">*</span><span class="tok-w"> </span><span class="tok-p">)</span><span class="tok-w"></span> 8210<span class="tok-w"> </span><span class="tok-k">rule</span><span class="tok-w"> </span><span class="tok-nf">type</span><span class="tok-w"> </span><span class="tok-p">(</span><span class="tok-w"> </span><span class="tok-p">)</span><span class="tok-w"></span> 8211<span class="tok-w"> </span><span class="tok-k">rule</span><span class="tok-w"> </span><span class="tok-nf">construct</span><span class="tok-w"> </span><span class="tok-p">(</span><span class="tok-w"> </span><span class="tok-nv">name</span><span class="tok-w"> </span><span class="tok-p">:</span><span class="tok-w"> </span><span class="tok-nv">source-targets</span><span class="tok-w"> </span><span class="tok-p">*</span><span class="tok-w"> </span><span class="tok-p">:</span><span class="tok-w"> </span><span class="tok-nv">property-set</span><span class="tok-w"> </span><span class="tok-p">)</span><span class="tok-w"></span> 8212 8213<span class="tok-w"> </span><span class="tok-c1"># Methods inherited from abstract-target</span> 8214<span class="tok-w"> </span><span class="tok-k">rule</span><span class="tok-w"> </span><span class="tok-nf">name</span><span class="tok-w"> </span><span class="tok-p">(</span><span class="tok-w"> </span><span class="tok-p">)</span><span class="tok-w"></span> 8215<span class="tok-w"> </span><span class="tok-k">rule</span><span class="tok-w"> </span><span class="tok-nf">project</span><span class="tok-w"> </span><span class="tok-p">(</span><span class="tok-w"> </span><span class="tok-p">)</span><span class="tok-w"></span> 8216<span class="tok-w"> </span><span class="tok-k">rule</span><span class="tok-w"> </span><span class="tok-nf">location</span><span class="tok-w"> </span><span class="tok-p">(</span><span class="tok-w"> </span><span class="tok-p">)</span><span class="tok-w"></span> 8217<span class="tok-w"> </span><span class="tok-k">rule</span><span class="tok-w"> </span><span class="tok-nf">full-name</span><span class="tok-w"> </span><span class="tok-p">(</span><span class="tok-w"> </span><span class="tok-p">)</span><span class="tok-w"></span> 8218 8219<span class="tok-w"> </span><span class="tok-c1"># Methods inherited from basic-target</span> 8220<span class="tok-w"> </span><span class="tok-k">rule</span><span class="tok-w"> </span><span class="tok-nf">generate</span><span class="tok-w"> </span><span class="tok-p">(</span><span class="tok-w"> </span><span class="tok-nv">property-set</span><span class="tok-w"> </span><span class="tok-p">)</span><span class="tok-w"></span> 8221<span class="tok-w"> </span>}<span class="tok-w"></span></code></pre> 8222</div> 8223</div> 8224<div class="paragraph"> 8225<p><a href="#bbv2.reference.class.typed-target">typed-target</a> is the most common 8226kind of target alternative. Rules for creating typed targets are defined 8227automatically for each type.</p> 8228</div> 8229<div class="openblock"> 8230<div class="content"> 8231<div class="olist arabic"> 8232<ol class="arabic"> 8233<li> 8234<p><code>rule <em>init</em> ( name : project : type : sources * : requirements * : default-build * : usage-requirements * )</code></p> 8235<div class="dlist"> 8236<dl> 8237<dt class="hdlist1"><code>name</code></dt> 8238<dd> 8239<p>The name of the target</p> 8240</dd> 8241<dt class="hdlist1"><code>project</code></dt> 8242<dd> 8243<p>The <a href="#bbv2.reference.class.project-target">project</a> in which the 8244target is declared.</p> 8245</dd> 8246<dt class="hdlist1"><code>type</code></dt> 8247<dd> 8248<p>The <a href="#bbv2.reference.modules.type">type</a> of the target.</p> 8249</dd> 8250</dl> 8251</div> 8252</li> 8253<li> 8254<p><code>rule type ( )</code></p> 8255<div class="paragraph"> 8256<p>Returns the <a href="#bbv2.reference.modules.type">type</a> of the target.</p> 8257</div> 8258</li> 8259<li> 8260<p><code>rule construct ( name : source-targets * : property-set )</code></p> 8261<div class="paragraph"> 8262<p>Implements 8263<a href="#bbv2.reference.class.basic-target.construct">basic-target.construct</a>. 8264Attempts to create a target of the correct type using generators 8265appropriate for the given 8266<a href="#bbv2.reference.class.property-set">property-set</a>. Returns a 8267<a href="#bbv2.reference.class.property-set">property-set</a> containing the 8268usage requirements and a list of virtual targets.</p> 8269</div> 8270<div class="admonitionblock note"> 8271<table> 8272<tr> 8273<td class="icon"> 8274<div class="title">ℹ</div> 8275</td> 8276<td class="content"> 8277This function is invoked automatically by 8278<a href="#bbv2.reference.class.basic-target.generate">basic-target.generate</a> 8279and should not be called directly by users. 8280</td> 8281</tr> 8282</table> 8283</div> 8284</li> 8285</ol> 8286</div> 8287</div> 8288</div> 8289</div> 8290<div class="sect3"> 8291<h4 id="bbv2.reference.class.property-set"><a class="anchor" href="#bbv2.reference.class.property-set"></a>5.6.6. Class property-set</h4> 8292<div class="paragraph"> 8293<p>Class for storing a set of properties.</p> 8294</div> 8295<div class="listingblock"> 8296<div class="content"> 8297<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-k">class</span><span class="tok-w"> </span><span class="tok-nc">property-set</span><span class="tok-w"> </span>{<span class="tok-w"></span> 8298<span class="tok-w"> </span><span class="tok-k">rule</span><span class="tok-w"> </span><span class="tok-nf">raw</span><span class="tok-w"> </span><span class="tok-p">(</span><span class="tok-w"> </span><span class="tok-p">)</span><span class="tok-w"></span> 8299<span class="tok-w"> </span><span class="tok-k">rule</span><span class="tok-w"> </span><span class="tok-nf">str</span><span class="tok-w"> </span><span class="tok-p">(</span><span class="tok-w"> </span><span class="tok-p">)</span><span class="tok-w"></span> 8300<span class="tok-w"> </span><span class="tok-k">rule</span><span class="tok-w"> </span><span class="tok-nf">propagated</span><span class="tok-w"> </span><span class="tok-p">(</span><span class="tok-w"> </span><span class="tok-p">)</span><span class="tok-w"></span> 8301<span class="tok-w"> </span><span class="tok-k">rule</span><span class="tok-w"> </span><span class="tok-nf">add</span><span class="tok-w"> </span><span class="tok-p">(</span><span class="tok-w"> </span><span class="tok-nv">ps</span><span class="tok-w"> </span><span class="tok-p">)</span><span class="tok-w"></span> 8302<span class="tok-w"> </span><span class="tok-k">rule</span><span class="tok-w"> </span><span class="tok-nf">add-raw</span><span class="tok-w"> </span><span class="tok-p">(</span><span class="tok-w"> </span><span class="tok-nv">properties</span><span class="tok-w"> </span><span class="tok-p">*</span><span class="tok-w"> </span><span class="tok-p">)</span><span class="tok-w"></span> 8303<span class="tok-w"> </span><span class="tok-k">rule</span><span class="tok-w"> </span><span class="tok-nf">refine</span><span class="tok-w"> </span><span class="tok-p">(</span><span class="tok-w"> </span><span class="tok-nv">ps</span><span class="tok-w"> </span><span class="tok-p">)</span><span class="tok-w"></span> 8304<span class="tok-w"> </span><span class="tok-k">rule</span><span class="tok-w"> </span><span class="tok-nf">get</span><span class="tok-w"> </span><span class="tok-p">(</span><span class="tok-w"> </span><span class="tok-nv">feature</span><span class="tok-w"> </span><span class="tok-p">)</span><span class="tok-w"></span> 8305}<span class="tok-w"></span></code></pre> 8306</div> 8307</div> 8308<div class="paragraph"> 8309<p>There is 1<→1 correspondence between identity and value. No two 8310instances of the class are equal. To maintain this property, the 8311'property-set.create' rule should be used to create new instances. 8312Instances are immutable.</p> 8313</div> 8314<div class="openblock"> 8315<div class="content"> 8316<div class="olist arabic"> 8317<ol class="arabic"> 8318<li> 8319<p><code>rule raw ( )</code></p> 8320<div class="paragraph"> 8321<p>Returns a Jam list of the stored properties.</p> 8322</div> 8323</li> 8324<li> 8325<p><code>rule str ( )</code></p> 8326<div class="paragraph"> 8327<p>Returns the string representation of the stored properties.</p> 8328</div> 8329</li> 8330<li> 8331<p><code>rule propagated ( )</code></p> 8332<div class="paragraph"> 8333<p>Returns a <a href="#bbv2.reference.class.property-set">property-set</a> 8334containing all the 8335<a href="#bbv2.reference.features.attributes.propagated">propagated</a> 8336properties in this 8337<a href="#bbv2.reference.class.property-set">property-set</a>.</p> 8338</div> 8339</li> 8340<li> 8341<p><a id="bbv2.reference.class.property-set.add"></a> <code>rule add ( ps )</code></p> 8342<div class="paragraph"> 8343<p>Returns a new <a href="#bbv2.reference.class.property-set">property-set</a> 8344containing the union of the properties in this 8345<a href="#bbv2.reference.class.property-set">property-set</a> and in <code>ps</code>.</p> 8346</div> 8347<div class="admonitionblock note"> 8348<table> 8349<tr> 8350<td class="icon"> 8351<div class="title">ℹ</div> 8352</td> 8353<td class="content"> 8354If <code>ps</code> contains non-free properties that should override the values in 8355this object, use <a href="#bbv2.reference.class.property-set.refine">refine</a> 8356instead. 8357</td> 8358</tr> 8359</table> 8360</div> 8361</li> 8362<li> 8363<p><code>rule add-raw ( properties * )</code></p> 8364<div class="paragraph"> 8365<p>Link <a href="#bbv2.reference.class.property-set.add">add</a>, except that it 8366takes a list of properties instead of a 8367<a href="#bbv2.reference.class.property-set">property-set</a>.</p> 8368</div> 8369</li> 8370<li> 8371<p><a id="bbv2.reference.class.property-set.refine"></a> <code>rule refine ( ps )</code></p> 8372<div class="paragraph"> 8373<p>Refines properties by overriding any non-free and non-conditional 8374properties for which a different value is specified in <code>ps</code>. Returns the 8375resulting <a href="#bbv2.reference.class.property-set">property-set</a>.</p> 8376</div> 8377</li> 8378<li> 8379<p><code>rule get ( feature )</code></p> 8380<div class="paragraph"> 8381<p>Returns all the values of <code>feature</code>.</p> 8382</div> 8383</li> 8384</ol> 8385</div> 8386</div> 8387</div> 8388</div> 8389</div> 8390<div class="sect2"> 8391<h3 id="bbv2.reference.buildprocess"><a class="anchor" href="#bbv2.reference.buildprocess"></a>5.7. Build process</h3> 8392<div class="paragraph"> 8393<p>The general overview of the build process was given in the 8394<a href="#bbv2.overview.build_process">user documentation</a>. This section 8395provides additional details, and some specific rules.</p> 8396</div> 8397<div class="paragraph"> 8398<p>To recap, building a target with specific properties includes the 8399following steps:</p> 8400</div> 8401<div class="olist arabic"> 8402<ol class="arabic"> 8403<li> 8404<p>applying the default build,</p> 8405</li> 8406<li> 8407<p>selecting the main target alternative to use,</p> 8408</li> 8409<li> 8410<p>determining the "common" properties,</p> 8411</li> 8412<li> 8413<p>building targets referred by the the sources list and dependency 8414properties,</p> 8415</li> 8416<li> 8417<p>adding the usage requirements produced when building dependencies to 8418the "common" properties,</p> 8419</li> 8420<li> 8421<p>building the target using generators,</p> 8422</li> 8423<li> 8424<p>computing the usage requirements to be returned.</p> 8425</li> 8426</ol> 8427</div> 8428<div class="sect3"> 8429<h4 id="bbv2.reference.buildprocess.alternatives"><a class="anchor" href="#bbv2.reference.buildprocess.alternatives"></a>5.7.1. Alternative selection</h4> 8430<div class="paragraph"> 8431<p>When a target has several alternatives, one of them must be selected. 8432The process is as follows:</p> 8433</div> 8434<div class="olist arabic"> 8435<ol class="arabic"> 8436<li> 8437<p>For each alternative, its <em>condition</em> is defined as the set of 8438<a href="#bbv2.reference.features.attributes.base">base properties</a> in its 8439requirements. <a href="#bbv2.reference.variants.propcond">Conditional 8440properties</a> are excluded.</p> 8441</li> 8442<li> 8443<p>An alternative is viable only if all properties in its condition are 8444present in the build request.</p> 8445</li> 8446<li> 8447<p>If there’s only one viable alternative, it’s chosen. Otherwise, an 8448attempt is made to find the best alternative. An alternative a is better 8449than another alternative b, if the set of properties in b’s condition is 8450a strict subset of the set of properties of a’s condition. If one viable 8451alternative is better than all the others, it’s selected. Otherwise, an 8452error is reported.</p> 8453</li> 8454</ol> 8455</div> 8456</div> 8457<div class="sect3"> 8458<h4 id="bbv2.reference.buildprocess.common"><a class="anchor" href="#bbv2.reference.buildprocess.common"></a>5.7.2. Determining common properties</h4> 8459<div class="paragraph"> 8460<p>"Common" properties is a somewhat artificial term. This is the 8461intermediate property set from which both the build request for 8462dependencies and the properties for building the target are derived.</p> 8463</div> 8464<div class="paragraph"> 8465<p>Since the default build and alternatives are already handled, we have 8466only two inputs: the build request and the requirements. Here are the 8467rules about common properties.</p> 8468</div> 8469<div class="olist arabic"> 8470<ol class="arabic"> 8471<li> 8472<p>Non-free features can have only one value</p> 8473</li> 8474<li> 8475<p>A non-conditional property in the requirements is always present in 8476common properties.</p> 8477</li> 8478<li> 8479<p>A property in the build request is present in common properties, 8480unless it is overridden by a property in the requirements.</p> 8481</li> 8482<li> 8483<p>If either the build request, or the requirements (non-conditional or 8484conditional) include an expandable property (either composite, or with a 8485specified sub-feature value), the behavior is equivalent to explicitly 8486adding all the expanded properties to the build request or the 8487requirements respectively.</p> 8488</li> 8489<li> 8490<p>If the requirements include a 8491<a href="#bbv2.reference.variants.propcond">conditional property</a>, and the 8492condition of this property is true in the context of common properties, 8493then the conditional property should be in common properties as well.</p> 8494</li> 8495<li> 8496<p>If no value for a feature is given by other rules here, it has 8497default value in common properties.</p> 8498</li> 8499</ol> 8500</div> 8501<div class="paragraph"> 8502<p>These rules are declarative. They don’t specify how to compute the 8503common properties. However, they provide enough information for the 8504user. The important point is the handling of conditional requirements. 8505The condition can be satisfied either by a property in the build 8506request, by non-conditional requirements, or even by another conditional 8507property. For example, the following example works as expected:</p> 8508</div> 8509<div class="listingblock"> 8510<div class="content"> 8511<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-nb">exe</span><span class="tok-w"> </span>a<span class="tok-w"> </span>:<span class="tok-w"> </span>a.cpp<span class="tok-w"></span> 8512<span class="tok-w"> </span>:<span class="tok-w"> </span><span class="tok-na"><toolset></span>gcc:<span class="tok-na"><variant></span>release<span class="tok-w"></span> 8513<span class="tok-w"> </span><span class="tok-na"><variant></span>release:<span class="tok-na"><define></span>FOO<span class="tok-w"> </span>;<span class="tok-w"></span></code></pre> 8514</div> 8515</div> 8516</div> 8517<div class="sect3"> 8518<h4 id="bbv2.reference.buildprocess.targetpath"><a class="anchor" href="#bbv2.reference.buildprocess.targetpath"></a>5.7.3. Target Paths</h4> 8519<div class="paragraph"> 8520<p>Several factors determine the location of a concrete file target. All 8521files in a project are built under the directory bin unless this is 8522overridden by the build-dir project attribute. Under bin is a path that 8523depends on the properties used to build each target. This path is 8524uniquely determined by all non-free, non-incidental properties. For 8525example, given a property set containing: <code><toolset>gcc</code> 8526<code><toolset-gcc:version>4.6.1</code> <code><variant>debug</code> <code><warnings>all</code> <code><define>_DEBUG</code> 8527<code><include>/usr/local/include</code> <code><link>static</code>, the path will be 8528<code>gcc-4.6.1/debug/link-static</code>. <code><warnings></code> is an incidental feature and 8529<code><define></code> and <code><include></code> are free features, so they do not affect the path.</p> 8530</div> 8531<div class="paragraph"> 8532<p>Sometimes the paths produced by B2 can become excessively long. 8533There are a couple of command line options that can help with this. 8534<code>--abbreviate-paths</code> reduces each element to no more than five characters. 8535For example, <code>link-static</code> becomes <code>lnk-sttc</code>. The <code>--hash</code> option reduces the 8536path to a single directory using an MD5 hash.</p> 8537</div> 8538<div class="paragraph"> 8539<p>There are two features that affect the build directory. The <code><location></code> 8540feature completely overrides the default build directory. For example,</p> 8541</div> 8542<div class="listingblock"> 8543<div class="content"> 8544<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-nb">exe</span><span class="tok-w"> </span>a<span class="tok-w"> </span>:<span class="tok-w"> </span>a.cpp<span class="tok-w"> </span>:<span class="tok-w"> </span><span class="tok-na"><location></span>.<span class="tok-w"> </span>;<span class="tok-w"></span></code></pre> 8545</div> 8546</div> 8547<div class="paragraph"> 8548<p>builds all the files produced by <code>a</code> in the directory of the Jamfile. 8549This is generally discouraged, as it precludes variant builds.</p> 8550</div> 8551<div class="paragraph"> 8552<p>The <location-prefix> feature adds a prefix to the path, under the 8553project’s build directory. For example,</p> 8554</div> 8555<div class="listingblock"> 8556<div class="content"> 8557<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-nb">exe</span><span class="tok-w"> </span>a<span class="tok-w"> </span>:<span class="tok-w"> </span>a.cpp<span class="tok-w"> </span>:<span class="tok-w"> </span><span class="tok-na"><location-prefix></span>subdir<span class="tok-w"> </span>;<span class="tok-w"></span></code></pre> 8558</div> 8559</div> 8560<div class="paragraph"> 8561<p>will create the files for <code>a</code> in <code>bin/subdir/gcc-4.6.1/debug</code></p> 8562</div> 8563</div> 8564</div> 8565<div class="sect2"> 8566<h3 id="bbv2.reference.definitions"><a class="anchor" href="#bbv2.reference.definitions"></a>5.8. Definitions</h3> 8567<div class="sect3"> 8568<h4 id="bbv2.reference.features"><a class="anchor" href="#bbv2.reference.features"></a>5.8.1. Features and properties</h4> 8569<div class="paragraph"> 8570<p>A <em>feature</em> is a normalized (toolset-independent) aspect of a build 8571configuration, such as whether inlining is enabled. Feature names may 8572not contain the ‘>’ character.</p> 8573</div> 8574<div class="paragraph"> 8575<p>Each feature in a build configuration has one or more associated 8576<em>value</em>s. Feature values for non-free features may not contain the 8577punctuation characters of pointy bracket (‘<code><</code>’), colon (‘<code>:</code>’ ), 8578equal sign (‘<code>=</code>’) and dashes (‘<code>-</code>’). Feature values for free 8579features may not contain the pointy bracket (‘<code><</code>’) character.</p> 8580</div> 8581<div class="paragraph"> 8582<p>A <em>property</em> is a (feature,value) pair, expressed as <feature>value.</p> 8583</div> 8584<div class="paragraph"> 8585<p>A <em>subfeature</em> is a feature that only exists in the presence of its 8586parent feature, and whose identity can be derived (in the context of its 8587parent) from its value. A subfeature’s parent can never be another 8588subfeature. Thus, features and their subfeatures form a two-level 8589hierarchy.</p> 8590</div> 8591<div class="paragraph"> 8592<p>A <em>value-string</em> for a feature <strong>F</strong> is a string of the form 8593<code>value-subvalue1-subvalue2</code>…​<code>-subvalueN</code>, where <code>value</code> is a legal 8594value for <strong>F</strong> and <code>subvalue1</code>…​<code>subvalueN</code> are legal values of some of 8595<strong>F</strong>'s subfeatures separated with dashes (‘<code>-</code>’). 8596For example, the properties <code><toolset>gcc <toolset-version>3.0.1</code> can 8597be expressed more concisely using a value-string, as <code><toolset>gcc-3.0.1</code>.</p> 8598</div> 8599<div class="paragraph"> 8600<p>A <em>property set</em> is a set of properties (i.e. a collection without 8601duplicates), for instance: <code><toolset>gcc <runtime-link>static</code>.</p> 8602</div> 8603<div class="paragraph"> 8604<p>A <em>property path</em> is a property set whose elements have been joined into 8605a single string separated by slashes. A property path representation of 8606the previous example would be <code><toolset>gcc/<runtime-link>static</code>.</p> 8607</div> 8608<div class="paragraph"> 8609<p>A <em>build specification</em> is a property set that fully describes the set 8610of features used to build a target.</p> 8611</div> 8612</div> 8613<div class="sect3"> 8614<h4 id="bbv2.reference.features.validity"><a class="anchor" href="#bbv2.reference.features.validity"></a>5.8.2. Property Validity</h4> 8615<div class="paragraph"> 8616<p>For <a href="#bbv2.reference.features.attributes.free">free</a> features, all 8617values are valid. For all other features, the valid values are 8618explicitly specified, and the build system will report an error for the 8619use of an invalid feature-value. Subproperty validity may be restricted 8620so that certain values are valid only in the presence of certain other 8621subproperties. For example, it is possible to specify that the 8622<code><gcc-target>mingw</code> property is only valid in the presence of 8623<code><gcc-version>2.95.2</code>.</p> 8624</div> 8625</div> 8626<div class="sect3"> 8627<h4 id="bbv2.reference.features.attributes"><a class="anchor" href="#bbv2.reference.features.attributes"></a>5.8.3. Feature Attributes</h4> 8628<div class="paragraph"> 8629<p>Each feature has a collection of zero or more of the following 8630attributes. Feature attributes are low-level descriptions of how the 8631build system should interpret a feature’s values when they appear in a 8632build request. We also refer to the attributes of properties, so that an 8633<em>incidental</em> property, for example, is one whose feature has the 8634<em>incidental</em> attribute.</p> 8635</div> 8636<div class="ulist"> 8637<ul> 8638<li> 8639<p><a id="bbv2.reference.features.attributes.incidental"></a> <em>incidental</em></p> 8640<div class="paragraph"> 8641<p>Incidental features are assumed not to affect build products at all. As 8642a consequence, the build system may use the same file for targets whose 8643build specification differs only in incidental features. A feature that 8644controls a compiler’s warning level is one example of a likely 8645incidental feature.</p> 8646</div> 8647<div class="paragraph"> 8648<p>Non-incidental features are assumed to affect build products, so the 8649files for targets whose build specification differs in non-incidental 8650features are placed in different directories as described in 8651<a href="#bbv2.reference.buildprocess.targetpath">Target Paths</a>.</p> 8652</div> 8653</li> 8654<li> 8655<p><a id="bbv2.reference.features.attributes.propagated"></a> <em>propagated</em></p> 8656<div class="paragraph"> 8657<p>Features of this kind are propagated to dependencies. That is, if a 8658<a href="#bbv2.overview.targets.main">main target</a> is built using a 8659propagated property, the build systems attempts to use the same property 8660when building any of its dependencies as part of that main target. For 8661instance, when an optimized executable is requested, one usually wants 8662it to be linked with optimized libraries. Thus, the <code><optimization></code> 8663feature is propagated.</p> 8664</div> 8665</li> 8666<li> 8667<p><a id="bbv2.reference.features.attributes.free"></a> <em>free</em></p> 8668<div class="paragraph"> 8669<p>Most features have a finite set of allowed values, and can only take on 8670a single value from that set in a given build specification. Free 8671features, on the other hand, can have several values at a time and each 8672value can be an arbitrary string. For example, it is possible to have 8673several preprocessor symbols defined simultaneously:</p> 8674</div> 8675<div class="listingblock"> 8676<div class="content"> 8677<pre><define>NDEBUG=1 <define>HAS_CONFIG_H=1</pre> 8678</div> 8679</div> 8680</li> 8681<li> 8682<p><a id="bbv2.reference.features.attributes.optional"></a> <em>optional</em></p> 8683<div class="paragraph"> 8684<p>An optional feature is a feature that is not required to appear in a 8685build specification. Every non-optional non-free feature has a default 8686value that is used when a value for the feature is not otherwise 8687specified, either in a target’s requirements or in the user’s build 8688request. [A feature’s default value is given by the first value listed 8689in the feature’s declaration. — move this elsewhere - dwa]</p> 8690</div> 8691</li> 8692<li> 8693<p><a id="bbv2.reference.features.attributes.symmetric"></a> <em>symmetric</em></p> 8694<div class="paragraph"> 8695<p>Normally a feature only generates a sub-variant directory when its value 8696differs from its default value, leading to an asymmetric sub-variant 8697directory structure for certain values of the feature. A symmetric 8698feature always generates a corresponding sub-variant directory.</p> 8699</div> 8700</li> 8701<li> 8702<p><a id="bbv2.reference.features.attributes.path"></a> <em>path</em></p> 8703<div class="paragraph"> 8704<p>The value of a path feature specifies a path. The path is treated as 8705relative to the directory of Jamfile where path feature is used and is 8706translated appropriately by the build system when the build is invoked 8707from a different directory</p> 8708</div> 8709</li> 8710<li> 8711<p><a id="bbv2.reference.features.attributes.implicit"></a> <em>implicit</em></p> 8712<div class="paragraph"> 8713<p>Values of implicit features alone identify the feature. For example, a 8714user is not required to write "<toolset>gcc", but can simply write 8715"gcc". Implicit feature names also don’t appear in variant paths, 8716although the values do. Thus: bin/gcc/…​ as opposed to 8717bin/toolset-gcc/…​. There should typically be only a few such features, 8718to avoid possible name clashes.</p> 8719</div> 8720</li> 8721<li> 8722<p><a id="bbv2.reference.features.attributes.composite"></a> <em>composite</em></p> 8723<div class="paragraph"> 8724<p>Composite features actually correspond to groups of properties. For 8725example, a build variant is a composite feature. When generating targets 8726from a set of build properties, composite features are recursively 8727expanded and <em>added</em> to the build property set, so rules can find them 8728if necessary. Non-composite non-free features override components of 8729composite features in a build property set.</p> 8730</div> 8731</li> 8732<li> 8733<p><a id="bbv2.reference.features.attributes.dependency"></a> <em>dependency</em></p> 8734<div class="paragraph"> 8735<p>The value of a dependency feature is a target reference. When used for 8736building of a main target, the value of dependency feature is treated as 8737additional dependency.</p> 8738</div> 8739<div class="paragraph"> 8740<p>For example, dependency features allow to state that library A depends 8741on library B. As the result, whenever an application will link to A, it 8742will also link to B. Specifying B as dependency of A is different from 8743adding B to the sources of A.</p> 8744</div> 8745</li> 8746</ul> 8747</div> 8748<div id="bbv2.reference.features.attributes.base" class="paragraph"> 8749<p>Features that are neither free nor incidental are called <em>base</em> 8750features.</p> 8751</div> 8752</div> 8753<div class="sect3"> 8754<h4 id="bbv2.reference.features.declaration"><a class="anchor" href="#bbv2.reference.features.declaration"></a>5.8.4. Feature Declaration</h4> 8755<div class="paragraph"> 8756<p>The low-level feature declaration interface is the <code>feature</code> rule from 8757the <code>feature</code> module:</p> 8758</div> 8759<div class="listingblock"> 8760<div class="content"> 8761<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-k">rule</span><span class="tok-w"> </span><span class="tok-nf">feature</span><span class="tok-w"> </span><span class="tok-p">(</span><span class="tok-w"> </span><span class="tok-nv">name</span><span class="tok-w"> </span><span class="tok-p">:</span><span class="tok-w"> </span><span class="tok-nv">allowed-values</span><span class="tok-w"> </span><span class="tok-p">*</span><span class="tok-w"> </span><span class="tok-p">:</span><span class="tok-w"> </span><span class="tok-nv">attributes</span><span class="tok-w"> </span><span class="tok-p">*</span><span class="tok-w"> </span><span class="tok-p">)</span><span class="tok-w"></span></code></pre> 8762</div> 8763</div> 8764<div class="paragraph"> 8765<p>A feature’s allowed-values may be extended with the <code>feature.extend</code> 8766rule.</p> 8767</div> 8768</div> 8769<div class="sect3"> 8770<h4 id="bbv2.reference.variants.proprefine"><a class="anchor" href="#bbv2.reference.variants.proprefine"></a>5.8.5. Property refinement</h4> 8771<div class="paragraph"> 8772<p>When a target with certain properties is requested, and that target 8773requires some set of properties, it is needed to find the set of 8774properties to use for building. This process is called <em>property 8775refinement</em> and is performed by these rules</p> 8776</div> 8777<div class="olist arabic"> 8778<ol class="arabic"> 8779<li> 8780<p>Each property in the required set is added to the original property 8781set</p> 8782</li> 8783<li> 8784<p>If the original property set includes property with a different 8785value of non free feature, that property is removed.</p> 8786</li> 8787</ol> 8788</div> 8789</div> 8790<div class="sect3"> 8791<h4 id="bbv2.reference.variants.propcond"><a class="anchor" href="#bbv2.reference.variants.propcond"></a>5.8.6. Conditional properties</h4> 8792<div class="paragraph"> 8793<p>Sometime it’s desirable to apply certain requirements only for a 8794specific combination of other properties. For example, one of compilers 8795that you use issues a pointless warning that you want to suppress by 8796passing a command line option to it. You would not want to pass that 8797option to other compilers. Conditional properties allow you to do just 8798that. Their syntax is:</p> 8799</div> 8800<div class="literalblock"> 8801<div class="content"> 8802<pre>property ( "," property ) * ":" property</pre> 8803</div> 8804</div> 8805<div class="paragraph"> 8806<p>For example, the problem above would be solved by:</p> 8807</div> 8808<div class="listingblock"> 8809<div class="content"> 8810<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-nb">exe</span><span class="tok-w"> </span>hello<span class="tok-w"> </span>:<span class="tok-w"> </span>hello.cpp<span class="tok-w"> </span>:<span class="tok-w"> </span><span class="tok-na"><toolset></span>yfc:<span class="tok-na"><cxxflags></span>-disable-pointless-warning<span class="tok-w"> </span>;<span class="tok-w"></span></code></pre> 8811</div> 8812</div> 8813<div class="paragraph"> 8814<p>The syntax also allows several properties in the condition, for example:</p> 8815</div> 8816<div class="listingblock"> 8817<div class="content"> 8818<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-nb">exe</span><span class="tok-w"> </span>hello<span class="tok-w"> </span>:<span class="tok-w"> </span>hello.cpp<span class="tok-w"> </span>:<span class="tok-w"> </span><span class="tok-na"><os></span>NT,<span class="tok-na"><toolset></span>gcc:<span class="tok-na"><link></span>static<span class="tok-w"> </span>;<span class="tok-w"></span></code></pre> 8819</div> 8820</div> 8821</div> 8822<div class="sect3"> 8823<h4 id="bbv2.reference.ids"><a class="anchor" href="#bbv2.reference.ids"></a>5.8.7. Target identifiers and references</h4> 8824<div class="paragraph"> 8825<p><em>Target identifier</em> is used to denote a target. The syntax is:</p> 8826</div> 8827<div class="literalblock"> 8828<div class="content"> 8829<pre>target-id -> (target-name | file-name | project-id | directory-name) 8830 | (project-id | directory-name) "//" target-name 8831project-id -> path 8832target-name -> path 8833file-name -> path 8834directory-name -> path</pre> 8835</div> 8836</div> 8837<div class="paragraph"> 8838<p>This grammar allows some elements to be recognized as either</p> 8839</div> 8840<div class="ulist"> 8841<ul> 8842<li> 8843<p>name of target declared in current Jamfile (note that target names may 8844include slash).</p> 8845</li> 8846<li> 8847<p>a regular file, denoted by absolute name or name relative to project’s 8848sources location.</p> 8849</li> 8850<li> 8851<p>project id (at this point, all project ids start with slash).</p> 8852</li> 8853<li> 8854<p>the directory of another project, denoted by absolute name or name 8855relative to the current project’s location.</p> 8856</li> 8857</ul> 8858</div> 8859<div class="paragraph"> 8860<p>To determine the real meaning the possible interpretations are checked 8861in this order. For example, valid target ids might be:</p> 8862</div> 8863<table class="tableblock frame-all grid-all stretch"> 8864<colgroup> 8865<col style="width: 50%;"> 8866<col style="width: 50%;"> 8867</colgroup> 8868<tbody> 8869<tr> 8870<td class="tableblock halign-left valign-top"><p class="tableblock"><code>a</code></p></td> 8871<td class="tableblock halign-left valign-top"><p class="tableblock">target in current project</p></td> 8872</tr> 8873<tr> 8874<td class="tableblock halign-left valign-top"><p class="tableblock"><code>lib/b.cpp</code></p></td> 8875<td class="tableblock halign-left valign-top"><p class="tableblock">regular file</p></td> 8876</tr> 8877<tr> 8878<td class="tableblock halign-left valign-top"><p class="tableblock"><code>/boost/thread</code></p></td> 8879<td class="tableblock halign-left valign-top"><p class="tableblock">project "/boost/thread"</p></td> 8880</tr> 8881<tr> 8882<td class="tableblock halign-left valign-top"><p class="tableblock"><code>/home/ghost/build/lr_library//parser</code></p></td> 8883<td class="tableblock halign-left valign-top"><p class="tableblock">target in specific project</p></td> 8884</tr> 8885<tr> 8886<td class="tableblock halign-left valign-top"><p class="tableblock"><code>../boost_1_61_0</code></p></td> 8887<td class="tableblock halign-left valign-top"><p class="tableblock">project in specific directory</p></td> 8888</tr> 8889</tbody> 8890</table> 8891<div class="paragraph"> 8892<p><strong>Rationale:</strong>Target is separated from project by special separator (not 8893just slash), because:</p> 8894</div> 8895<div class="ulist"> 8896<ul> 8897<li> 8898<p>It emphasis that projects and targets are different things.</p> 8899</li> 8900<li> 8901<p>It allows to have main target names with slashes.</p> 8902</li> 8903</ul> 8904</div> 8905<div id="bbv2.reference.targets.references" class="paragraph"> 8906<p><em>Target reference</em> is used to specify a source target, and may 8907additionally specify desired properties for that target. It has this 8908syntax:</p> 8909</div> 8910<div class="literalblock"> 8911<div class="content"> 8912<pre>target-reference -> target-id [ "/" requested-properties ] 8913requested-properties -> property-path</pre> 8914</div> 8915</div> 8916<div class="paragraph"> 8917<p>For example,</p> 8918</div> 8919<div class="listingblock"> 8920<div class="content"> 8921<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-nb">exe</span><span class="tok-w"> </span>compiler<span class="tok-w"> </span>:<span class="tok-w"> </span>compiler.cpp<span class="tok-w"> </span>libs/cmdline/<span class="tok-na"><optimization></span>space<span class="tok-w"> </span>;<span class="tok-w"></span></code></pre> 8922</div> 8923</div> 8924<div class="paragraph"> 8925<p>would cause the version of <code>cmdline</code> library, optimized for space, to be 8926linked in even if the <code>compiler</code> executable is build with optimization 8927for speed.</p> 8928</div> 8929</div> 8930</div> 8931</div> 8932</div> 8933<div class="sect1"> 8934<h2 id="bbv2.util"><a class="anchor" href="#bbv2.util"></a>6. Utilities</h2> 8935<div class="sectionbody"> 8936<div class="sect2"> 8937<h3 id="bbv2.util.debugger"><a class="anchor" href="#bbv2.util.debugger"></a>6.1. Debugger</h3> 8938<div class="sect3"> 8939<h4 id="bbv2.util.debugger.overview"><a class="anchor" href="#bbv2.util.debugger.overview"></a>6.1.1. Overview</h4> 8940<div class="paragraph"> 8941<p>B2 comes with a debugger for Jamfiles. To run the debugger, 8942start B2 with <code>b2 -dconsole</code>.</p> 8943</div> 8944<div class="literalblock"> 8945<div class="content"> 8946<pre>$ b2 -dconsole 8947(b2db) break gcc.init 8948Breakpoint 1 set at gcc.init 8949(b2db) run 8950Starting program: /usr/bin/b2 8951Breakpoint 1, gcc.init ( ) at /usr/share/boost-build/tools/gcc.jam:74 895274 local tool-command = ; 8953(b2db) quit</pre> 8954</div> 8955</div> 8956</div> 8957<div class="sect3"> 8958<h4 id="bbv2.util.debugger.running"><a class="anchor" href="#bbv2.util.debugger.running"></a>6.1.2. Running the Program</h4> 8959<div class="paragraph"> 8960<p>The <code>run</code> command is used to start a new <code>b2</code> subprocess for debugging. 8961The arguments to <code>run</code> are passed on the command line. If a child 8962process is already running, it will be terminated before the new child 8963is launched.</p> 8964</div> 8965<div class="paragraph"> 8966<p>When the program is paused <code>continue</code> will resume execution. The <code>step</code> 8967command will advance the program by a single statement, stopping on 8968entry to another function or return from the current function. <code>next</code> is 8969like <code>step</code> except that it skips over function calls. <code>finish</code> executes 8970until the current function returns.</p> 8971</div> 8972<div class="paragraph"> 8973<p>The <code>kill</code> command terminates the current child immediately.</p> 8974</div> 8975</div> 8976<div class="sect3"> 8977<h4 id="bbv2.util.debugger.break"><a class="anchor" href="#bbv2.util.debugger.break"></a>6.1.3. Breakpoints</h4> 8978<div class="paragraph"> 8979<p>Breakpoints are set using the <code>break</code> command. The location of the 8980breakpoint can be specified as either the name of a function (including 8981the module name) or or a file name and line number of the form 8982<code>file:line</code>. When a breakpoint is created it is given a unique id which 8983is used to identify it for other commands.</p> 8984</div> 8985<div class="literalblock"> 8986<div class="content"> 8987<pre>(b2db) break Jamfile:10 8988Breakpoint 1 set at Jamfile:10 8989(b2db) break msvc.init 8990Breakpoint 2 set at msvc.init</pre> 8991</div> 8992</div> 8993<div class="paragraph"> 8994<p>A breakpoint can be temporarily disabled using the <code>disable</code> command. 8995While a breakpoint is disabled, the child will not stop when it is hit. 8996A disabled breakpoint can be activated again with <code>enable</code>.</p> 8997</div> 8998<div class="literalblock"> 8999<div class="content"> 9000<pre>(b2db) disable 1 9001(b2db) enable 1</pre> 9002</div> 9003</div> 9004<div class="paragraph"> 9005<p>Breakpoints can be removed permanently with <code>delete</code> or <code>clear</code>. The 9006difference between them is that <code>delete</code> takes the breakpoint id while 9007<code>clear</code> takes the location of the breakpoint as originally specified to 9008break.</p> 9009</div> 9010<div class="literalblock"> 9011<div class="content"> 9012<pre>(b2db) clear Jamfile:10 9013Deleted breakpoint 1 9014(b2db) delete 2</pre> 9015</div> 9016</div> 9017</div> 9018<div class="sect3"> 9019<h4 id="bbv2.util.debugger.stack"><a class="anchor" href="#bbv2.util.debugger.stack"></a>6.1.4. Examining the Stack</h4> 9020<div class="paragraph"> 9021<p>The <code>backtrace</code> command will print a summary of every frame on the 9022stack.</p> 9023</div> 9024<div class="paragraph"> 9025<p>The <code>print</code> command can be used to show the value of an expression.</p> 9026</div> 9027<div class="literalblock"> 9028<div class="content"> 9029<pre>(b2db) print [ modules.peek : ARGV ] 9030/usr/bin/b2 toolset=msvc install 9031(b2db) print $(__file__) 9032Jamfile.jam</pre> 9033</div> 9034</div> 9035</div> 9036<div class="sect3"> 9037<h4 id="bbv2.util.debugger.misc"><a class="anchor" href="#bbv2.util.debugger.misc"></a>6.1.5. Miscellaneous Commands</h4> 9038<div class="paragraph"> 9039<p><code>quit</code> exits the debugger. <code>help</code> describes the available commands.</p> 9040</div> 9041</div> 9042</div> 9043</div> 9044</div> 9045<div class="sect1"> 9046<h2 id="bbv2.extender"><a class="anchor" href="#bbv2.extender"></a>7. Extender Manual</h2> 9047<div class="sectionbody"> 9048<div class="sect2"> 9049<h3 id="bbv2.extender.intro"><a class="anchor" href="#bbv2.extender.intro"></a>7.1. Introduction</h3> 9050<div class="paragraph"> 9051<p>This section explains how to extend B2 to accommodate your local 9052requirements — primarily to add support for non-standard tools you 9053have. Before we start, be sure you have read and understood the concept 9054of metatarget, <a href="#bbv2.overview.concepts">Concepts</a>, which is critical to 9055understanding the remaining material.</p> 9056</div> 9057<div class="paragraph"> 9058<p>The current version of B2 has three levels of targets, listed 9059below.</p> 9060</div> 9061<div class="dlist"> 9062<dl> 9063<dt class="hdlist1">metatarget</dt> 9064<dd> 9065<p>Object that is created from declarations in Jamfiles. May be called 9066with a set of properties to produce concrete targets.</p> 9067</dd> 9068<dt class="hdlist1">concrete target</dt> 9069<dd> 9070<p>Object that corresponds to a file or an action.</p> 9071</dd> 9072<dt class="hdlist1">jam target</dt> 9073<dd> 9074<p>Low-level concrete target that is specific to Boost.Jam build engine. 9075Essentially a string — most often a name of file.</p> 9076</dd> 9077</dl> 9078</div> 9079<div class="paragraph"> 9080<p>In most cases, you will only have to deal with concrete targets and the 9081process that creates concrete targets from metatargets. Extending 9082metatarget level is rarely required. The jam targets are typically only 9083used inside the command line patterns.</p> 9084</div> 9085<div class="admonitionblock warning"> 9086<table> 9087<tr> 9088<td class="icon"> 9089<div class="title">⚠</div> 9090</td> 9091<td class="content"> 9092All of the Boost.Jam target-related builtin functions, like 9093<code>DEPENDS</code> or <code>ALWAYS</code> operate on jam targets. Applying them to metatargets or 9094concrete targets has no effect. 9095</td> 9096</tr> 9097</table> 9098</div> 9099<div class="sect3"> 9100<h4 id="bbv2.extender.overview.metatargets"><a class="anchor" href="#bbv2.extender.overview.metatargets"></a>7.1.1. Metatargets</h4> 9101<div class="paragraph"> 9102<p>Metatarget is an object that records information specified in Jamfile, 9103such as metatarget kind, name, sources and properties, and can be called 9104with specific properties to generate concrete targets. At the code level 9105it is represented by an instance of class derived from 9106<a href="#bbv2.reference.class.abstract-target">abstract-target</a>. 9107<sup class="footnote">[<a id="_footnoteref_4" class="footnote" href="#_footnotedef_4" title="View footnote.">4</a>]</sup></p> 9108</div> 9109<div class="paragraph"> 9110<p>The <a href="#bbv2.reference.class.abstract-target.generate">generate</a> method 9111takes the build properties (as an instance of the 9112<a href="#bbv2.reference.class.property-set">property-set</a> class) and returns 9113a list containing:</p> 9114</div> 9115<div class="ulist"> 9116<ul> 9117<li> 9118<p>As front element — Usage-requirements from this invocation (an 9119instance of <a href="#bbv2.reference.class.property-set">property-set</a>)</p> 9120</li> 9121<li> 9122<p>As subsequent elements — created concrete targets ( instances of the 9123<code>virtual-target</code> class.)</p> 9124</li> 9125</ul> 9126</div> 9127<div class="paragraph"> 9128<p>It’s possible to lookup a metatarget by target-id using the 9129<code>targets.resolve-reference</code> function, and the 9130<code>targets.generate-from-reference</code> function can both lookup and generate 9131a metatarget.</p> 9132</div> 9133<div class="paragraph"> 9134<p>The <a href="#bbv2.reference.class.abstract-target">abstract-target</a> class 9135has three immediate derived classes:</p> 9136</div> 9137<div class="ulist"> 9138<ul> 9139<li> 9140<p><a href="#bbv2.reference.class.project-target">project-target</a> that 9141corresponds to a project and is not intended for further subclassing. 9142The <a href="#bbv2.reference.class.project-target.generate">generate</a> method 9143of this class builds all targets in the project that are not marked as 9144explicit.</p> 9145</li> 9146<li> 9147<p><a href="#bbv2.reference.class.main-target">main-target</a> corresponds to a 9148target in a project and contains one or more target alternatives. This 9149class also should not be subclassed. The 9150<a href="#bbv2.reference.class.main-target.generate">generate</a> method of this 9151class selects an alternative to build, and calls the 9152<a href="#bbv2.reference.class.basic-target.generate">generate</a> method of 9153that alternative.</p> 9154</li> 9155<li> 9156<p><a href="#bbv2.reference.class.basic-target">basic-target</a> corresponds to a 9157specific target alternative. This is base class, with a number of 9158derived classes. The 9159<a href="#bbv2.reference.class.basic-target.generate">generate</a> method 9160processes the target requirements and requested build properties to 9161determine final properties for the target, builds all sources, and 9162finally calls the abstract 9163<a href="#bbv2.reference.class.basic-target.construct">construct</a> method with 9164the list of source virtual targets, and the final properties.</p> 9165</li> 9166</ul> 9167</div> 9168<div class="paragraph"> 9169<p>The instances of the 9170<a href="#bbv2.reference.class.project-target">project-target</a> and 9171<a href="#bbv2.reference.class.main-target">main-target</a> classes are created 9172implicitly — when loading a new Jamfiles, or when a new target 9173alternative with as-yet unknown name is created. The instances of the 9174classes derived from 9175<a href="#bbv2.reference.class.basic-target">basic-target</a> are typically 9176created when Jamfile calls a metatarget rule, such as such as <code>exe</code>.</p> 9177</div> 9178<div class="paragraph"> 9179<p>It it permissible to create a custom class derived from 9180<a href="#bbv2.reference.class.basic-target">basic-target</a> and create new 9181metatarget rule that creates instance of such target. However, in the 9182majority of cases, a specific subclass of 9183<a href="#bbv2.reference.class.basic-target">basic-target</a> — <a href="#bbv2.reference.class.typed-target">typed-target</a> is used. That 9184class is associated with a type and relays to generators to construct 9185concrete targets of that type. This process will be explained below. 9186When a new type is declared, a new metatarget rule is automatically 9187defined. That rule creates new instance of type-target, associated with 9188that type.</p> 9189</div> 9190</div> 9191<div class="sect3"> 9192<h4 id="bbv2.extender.overview.targets"><a class="anchor" href="#bbv2.extender.overview.targets"></a>7.1.2. Concrete targets</h4> 9193<div class="paragraph"> 9194<p>Concrete targets are represented by instance of classes derived from 9195<code>virtual-target</code>. The most commonly used subclass is <code>file-target</code>. A 9196file target is associated with an action that creates it —  an 9197instance of the <code>action</code> class. The action, in turn, hold a list of 9198source targets. It also holds the 9199<a href="#bbv2.reference.class.property-set">property-set</a> instance with the 9200build properties that should be used for the action.</p> 9201</div> 9202<div class="paragraph"> 9203<p>Here’s an example of creating a target from another target, <code>source</code></p> 9204</div> 9205<div class="listingblock"> 9206<div class="content"> 9207<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-k">local</span><span class="tok-w"> </span>a<span class="tok-w"> </span>=<span class="tok-w"> </span>[<span class="tok-w"> </span>new<span class="tok-w"> </span>action<span class="tok-w"> </span><span class="tok-si">$(source)</span><span class="tok-w"> </span>:<span class="tok-w"> </span>common.copy<span class="tok-w"> </span>:<span class="tok-w"> </span><span class="tok-si">$(property-set)</span><span class="tok-w"> </span>]<span class="tok-w"> </span>;<span class="tok-w"></span> 9208<span class="tok-k">local</span><span class="tok-w"> </span>t<span class="tok-w"> </span>=<span class="tok-w"> </span>[<span class="tok-w"> </span>new<span class="tok-w"> </span>file-target<span class="tok-w"> </span><span class="tok-si">$(name)</span><span class="tok-w"> </span>:<span class="tok-w"> </span>CPP<span class="tok-w"> </span>:<span class="tok-w"> </span><span class="tok-si">$(project)</span><span class="tok-w"> </span>:<span class="tok-w"> </span><span class="tok-si">$(a)</span><span class="tok-w"> </span>]<span class="tok-w"> </span>;<span class="tok-w"></span></code></pre> 9209</div> 9210</div> 9211<div class="paragraph"> 9212<p>The first line creates an instance of the <code>action</code> class. The first 9213parameter is the list of sources. The second parameter is the name a 9214jam-level <a href="#bbv2.overview.jam_language.actions">action</a>. The third 9215parameter is the property-set applying to this action. The second line 9216creates a target. We specify a name, a type and a project. We also pass 9217the action object created earlier. If the action creates several 9218targets, we can repeat the second line several times.</p> 9219</div> 9220<div class="paragraph"> 9221<p>In some cases, code that creates concrete targets may be invoked more 9222than once with the same properties. Returning two different instances of 9223<code>file-target</code> that correspond to the same file clearly will result in 9224problems. Therefore, whenever returning targets you should pass them via 9225the <code>virtual-target.register</code> function, besides allowing B2 to 9226track which virtual targets got created for each metatarget, this will 9227also replace targets with previously created identical ones, as 9228necessary.<sup class="footnote">[<a id="_footnoteref_5" class="footnote" href="#_footnotedef_5" title="View footnote.">5</a>]</sup> Here are a couple of examples:</p> 9229</div> 9230<div class="listingblock"> 9231<div class="content"> 9232<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-k">return</span><span class="tok-w"> </span>[<span class="tok-w"> </span>virtual-target.register<span class="tok-w"> </span><span class="tok-si">$(t)</span><span class="tok-w"> </span>]<span class="tok-w"> </span>;<span class="tok-w"></span> 9233<span class="tok-k">return</span><span class="tok-w"> </span>[<span class="tok-w"> </span>sequence.transform<span class="tok-w"> </span>virtual-target.register<span class="tok-w"> </span>:<span class="tok-w"> </span><span class="tok-si">$(targets)</span><span class="tok-w"> </span>]<span class="tok-w"> </span>;<span class="tok-w"></span></code></pre> 9234</div> 9235</div> 9236</div> 9237<div class="sect3"> 9238<h4 id="bbv2.extender.overview.generators"><a class="anchor" href="#bbv2.extender.overview.generators"></a>7.1.3. Generators</h4> 9239<div class="paragraph"> 9240<p>In theory, every kind of metatarget in B2 (like <code>exe</code>, <code>lib</code> or 9241<code>obj</code>) could be implemented by writing a new metatarget class that, 9242independently of the other code, figures what files to produce and what 9243commands to use. However, that would be rather inflexible. For example, 9244adding support for a new compiler would require editing several 9245metatargets.</p> 9246</div> 9247<div class="paragraph"> 9248<p>In practice, most files have specific types, and most tools consume and 9249produce files of specific type. To take advantage of this fact, 9250B2 defines concept of target type and generators generators, 9251and has special metatarget class 9252<a href="#bbv2.reference.class.typed-target">typed-target</a>. Target type is 9253merely an identifier. It is associated with a set of file extensions 9254that correspond to that type. Generator is an abstraction of a tool. It 9255advertises the types it produces and, if called with a set of input 9256target, tries to construct output targets of the advertised types. 9257Finally, <a href="#bbv2.reference.class.typed-target">typed-target</a> is 9258associated with specific target type, and relays the generator (or 9259generators) for that type.</p> 9260</div> 9261<div class="paragraph"> 9262<p>A generator is an instance of a class derived from <code>generator</code>. The 9263<code>generator</code> class itself is suitable for common cases. You can define 9264derived classes for custom scenarios.</p> 9265</div> 9266</div> 9267</div> 9268<div class="sect2"> 9269<h3 id="bbv2.extender.example"><a class="anchor" href="#bbv2.extender.example"></a>7.2. Example: 1-to-1 generator</h3> 9270<div class="paragraph"> 9271<p>Say you’re writing an application that generates C++ code. If you ever 9272did this, you know that it’s not nice. Embedding large portions of C++ 9273code in string literals is very awkward. A much better solution is:</p> 9274</div> 9275<div class="olist arabic"> 9276<ol class="arabic"> 9277<li> 9278<p>Write the template of the code to be generated, leaving placeholders 9279at the points that will change</p> 9280</li> 9281<li> 9282<p>Access the template in your application and replace placeholders 9283with appropriate text.</p> 9284</li> 9285<li> 9286<p>Write the result.</p> 9287</li> 9288</ol> 9289</div> 9290<div class="paragraph"> 9291<p>It’s quite easy to achieve. You write special verbatim files that are 9292just C++, except that the very first line of the file contains the name 9293of a variable that should be generated. A simple tool is created that 9294takes a verbatim file and creates a cpp file with a single <code>char*</code> 9295variable whose name is taken from the first line of the verbatim file 9296and whose value is the file’s properly quoted content.</p> 9297</div> 9298<div class="paragraph"> 9299<p>Let’s see what B2 can do.</p> 9300</div> 9301<div class="paragraph"> 9302<p>First off, B2 has no idea about "verbatim files". So, you must 9303register a new target type. The following code does it:</p> 9304</div> 9305<div class="listingblock"> 9306<div class="content"> 9307<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-nb">import</span><span class="tok-w"> </span>type<span class="tok-w"> </span>;<span class="tok-w"></span> 9308type.register<span class="tok-w"> </span>VERBATIM<span class="tok-w"> </span>:<span class="tok-w"> </span>verbatim<span class="tok-w"> </span>;<span class="tok-w"></span></code></pre> 9309</div> 9310</div> 9311<div class="paragraph"> 9312<p>The first parameter to 9313<a href="#bbv2.reference.modules.type.register">type.register</a> gives the name 9314of the declared type. By convention, it’s uppercase. The second 9315parameter is the suffix for files of this type. So, if B2 sees 9316<code>code.verbatim</code> in a list of sources, it knows that it’s of type 9317<code>VERBATIM</code>.</p> 9318</div> 9319<div class="paragraph"> 9320<p>Next, you tell B2 that the verbatim files can be transformed 9321into C++ files in one build step. A generator is a template for a build 9322step that transforms targets of one type (or set of types) into another. 9323Our generator will be called <code>verbatim.inline-file</code>; it transforms 9324<code>VERBATIM</code> files into <code>CPP</code> files:</p> 9325</div> 9326<div class="listingblock"> 9327<div class="content"> 9328<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-nb">import</span><span class="tok-w"> </span>generators<span class="tok-w"> </span>;<span class="tok-w"></span> 9329generators.register-standard<span class="tok-w"> </span>verbatim.inline-file<span class="tok-w"> </span>:<span class="tok-w"> </span>VERBATIM<span class="tok-w"> </span>:<span class="tok-w"> </span>CPP<span class="tok-w"> </span>;<span class="tok-w"></span></code></pre> 9330</div> 9331</div> 9332<div class="paragraph"> 9333<p>Lastly, you have to inform B2 about the shell commands used to 9334make that transformation. That’s done with an <code>actions</code> declaration.</p> 9335</div> 9336<div class="listingblock"> 9337<div class="content"> 9338<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-k">actions</span><span class="tok-w"> </span><span class="tok-nf">inline-file</span><span class="tok-w"></span> 9339{<span class="tok-sh"></span> 9340<span class="tok-sh"> "./inline-file.py" </span><span class="tok-si">$(<)</span><span class="tok-sh"> </span><span class="tok-si">$(>)</span><span class="tok-sh"></span> 9341<span class="tok-p">}</span><span class="tok-w"></span></code></pre> 9342</div> 9343</div> 9344<div class="paragraph"> 9345<p>Now, we’re ready to tie it all together. Put all the code above in file 9346<code>verbatim.jam</code>, add <code>import verbatim ;</code> to <code>Jamroot.jam</code>, and it’s 9347possible to write the following in your Jamfile:</p> 9348</div> 9349<div class="listingblock"> 9350<div class="content"> 9351<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-nb">exe</span><span class="tok-w"> </span>codegen<span class="tok-w"> </span>:<span class="tok-w"> </span>codegen.cpp<span class="tok-w"> </span>class_template.verbatim<span class="tok-w"> </span>usage.verbatim<span class="tok-w"> </span>;<span class="tok-w"></span></code></pre> 9352</div> 9353</div> 9354<div class="paragraph"> 9355<p>The listed verbatim files will be automatically converted into C++ 9356source files, compiled and then linked to the <code>codegen</code> executable.</p> 9357</div> 9358<div class="paragraph"> 9359<p>In subsequent sections, we will extend this example, and review all the 9360mechanisms in detail. The complete code is available in the 9361<code>example/customization</code> directory.</p> 9362</div> 9363</div> 9364<div class="sect2"> 9365<h3 id="bbv2.extending.targets"><a class="anchor" href="#bbv2.extending.targets"></a>7.3. Target types</h3> 9366<div class="paragraph"> 9367<p>The first thing we did in the <a href="#bbv2.extender.intro">introduction</a> 9368was declaring a new target type:</p> 9369</div> 9370<div class="listingblock"> 9371<div class="content"> 9372<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-nb">import</span><span class="tok-w"> </span>type<span class="tok-w"> </span>;<span class="tok-w"></span> 9373type.register<span class="tok-w"> </span>VERBATIM<span class="tok-w"> </span>:<span class="tok-w"> </span>verbatim<span class="tok-w"> </span>;<span class="tok-w"></span></code></pre> 9374</div> 9375</div> 9376<div class="paragraph"> 9377<p>The type is the most important property of a target. B2 can 9378automatically generate necessary build actions only because you specify 9379the desired type (using the different main target rules), and because 9380B2 can guess the type of sources from their extensions.</p> 9381</div> 9382<div class="paragraph"> 9383<p>The first two parameters for the <code>type.register</code> rule are the name of 9384new type and the list of extensions associated with it. A file with an 9385extension from the list will have the given target type. In the case 9386where a target of the declared type is generated from other sources, the 9387first specified extension will be used.</p> 9388</div> 9389<div class="paragraph"> 9390<p>Sometimes you want to change the suffix used for generated targets 9391depending on build properties, such as toolset. For example, some 9392compiler uses extension <code>elf</code> for executable files. You can use the 9393<code>type.set-generated-target-suffix</code> rule:</p> 9394</div> 9395<div class="listingblock"> 9396<div class="content"> 9397<pre class="pygments highlight"><code data-lang="jam"><span></span>type.set-generated-target-suffix<span class="tok-w"> </span>EXE<span class="tok-w"> </span>:<span class="tok-w"> </span><span class="tok-na"><toolset></span>elf<span class="tok-w"> </span>:<span class="tok-w"> </span>elf<span class="tok-w"> </span>;<span class="tok-w"></span></code></pre> 9398</div> 9399</div> 9400<div class="paragraph"> 9401<p>A new target type can be inherited from an existing one.</p> 9402</div> 9403<div class="listingblock"> 9404<div class="content"> 9405<pre class="pygments highlight"><code data-lang="jam"><span></span>type.register<span class="tok-w"> </span>PLUGIN<span class="tok-w"> </span>:<span class="tok-w"> </span>:<span class="tok-w"> </span>SHARED_LIB<span class="tok-w"> </span>;<span class="tok-w"></span></code></pre> 9406</div> 9407</div> 9408<div class="paragraph"> 9409<p>The above code defines a new type derived from <code>SHARED_LIB</code>. Initially, 9410the new type inherits all the properties of the base type - in 9411particular generators and suffix. Typically, you’ll change the new type 9412in some way. For example, using <code>type.set-generated-target-suffix</code> you 9413can set the suffix for the new type. Or you can write a special 9414generator for the new type. For example, it can generate additional 9415meta-information for the plugin. In either way, the <code>PLUGIN</code> type can be 9416used whenever <code>SHARED_LIB</code> can. For example, you can directly link 9417plugins to an application.</p> 9418</div> 9419<div class="paragraph"> 9420<p>A type can be defined as "main", in which case B2 will 9421automatically declare a main target rule for building targets of that 9422type. More details can be found 9423<a href="#bbv2.extending.rules.main-type">later</a>.</p> 9424</div> 9425</div> 9426<div class="sect2"> 9427<h3 id="bbv2.extending.scanners"><a class="anchor" href="#bbv2.extending.scanners"></a>7.4. Scanners</h3> 9428<div class="paragraph"> 9429<p>Sometimes, a file can refer to other files via some include system. To 9430make B2 track dependencies between included files, you need to 9431provide a scanner. The primary limitation is that only one scanner can 9432be assigned to a target type.</p> 9433</div> 9434<div class="paragraph"> 9435<p>First, we need to declare a new class for the scanner:</p> 9436</div> 9437<div class="listingblock"> 9438<div class="content"> 9439<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-k">class</span><span class="tok-w"> </span><span class="tok-nc">verbatim-scanner</span><span class="tok-w"> </span><span class="tok-p">:</span><span class="tok-w"> </span><span class="tok-nc">common-scanner</span><span class="tok-w"></span> 9440{<span class="tok-w"></span> 9441<span class="tok-w"> </span><span class="tok-k">rule</span><span class="tok-w"> </span><span class="tok-nf">pattern</span><span class="tok-w"> </span><span class="tok-p">(</span><span class="tok-w"> </span><span class="tok-p">)</span><span class="tok-w"></span> 9442<span class="tok-w"> </span>{<span class="tok-w"></span> 9443<span class="tok-w"> </span><span class="tok-k">return</span><span class="tok-w"> </span>"//###include[<span class="tok-w"> </span>]*\"([^\"]*)\""<span class="tok-w"> </span>;<span class="tok-w"></span> 9444<span class="tok-w"> </span>}<span class="tok-w"></span> 9445}<span class="tok-w"></span></code></pre> 9446</div> 9447</div> 9448<div class="paragraph"> 9449<p>All the complex logic is in the <code>common-scanner</code> class, and you only 9450need to override the method that returns the regular expression to be 9451used for scanning. The parentheses in the regular expression indicate 9452which part of the string is the name of the included file. Only the 9453first parenthesized group in the regular expression will be recognized; 9454if you can’t express everything you want that way, you can return 9455multiple regular expressions, each of which contains a parenthesized 9456group to be matched.</p> 9457</div> 9458<div class="paragraph"> 9459<p>After that, we need to register our scanner class:</p> 9460</div> 9461<div class="listingblock"> 9462<div class="content"> 9463<pre class="pygments highlight"><code data-lang="jam"><span></span>scanner.register<span class="tok-w"> </span>verbatim-scanner<span class="tok-w"> </span>:<span class="tok-w"> </span><span class="tok-k">include</span><span class="tok-w"> </span>;<span class="tok-w"></span></code></pre> 9464</div> 9465</div> 9466<div class="paragraph"> 9467<p>The value of the second parameter, in this case <code>include</code>, specifies the 9468properties that contain the list of paths that should be searched for 9469the included files.</p> 9470</div> 9471<div class="paragraph"> 9472<p>Finally, we assign the new scanner to the <code>VERBATIM</code> target type:</p> 9473</div> 9474<div class="listingblock"> 9475<div class="content"> 9476<pre class="pygments highlight"><code data-lang="jam"><span></span>type.set-scanner<span class="tok-w"> </span>VERBATIM<span class="tok-w"> </span>:<span class="tok-w"> </span>verbatim-scanner<span class="tok-w"> </span>;<span class="tok-w"></span></code></pre> 9477</div> 9478</div> 9479<div class="paragraph"> 9480<p>That’s enough for scanning include dependencies.</p> 9481</div> 9482</div> 9483<div class="sect2"> 9484<h3 id="bbv2.extending.tools"><a class="anchor" href="#bbv2.extending.tools"></a>7.5. Tools and generators</h3> 9485<div class="paragraph"> 9486<p>This section will describe how B2 can be extended to support 9487new tools.</p> 9488</div> 9489<div class="paragraph"> 9490<p>For each additional tool, a B2 object called generator must be 9491created. That object has specific types of targets that it accepts and 9492produces. Using that information, B2 is able to automatically 9493invoke the generator. For example, if you declare a generator that takes 9494a target of the type <code>D</code> and produces a target of the type <code>OBJ</code>, when 9495placing a file with extension <code>.d</code> in a list of sources will cause 9496B2 to invoke your generator, and then to link the resulting 9497object file into an application. (Of course, this requires that you 9498specify that the <code>.d</code> extension corresponds to the <code>D</code> type.)</p> 9499</div> 9500<div class="paragraph"> 9501<p>Each generator should be an instance of a class derived from the 9502<code>generator</code> class. In the simplest case, you don’t need to create a 9503derived class, but simply create an instance of the <code>generator</code> class. 9504Let’s review the example we’ve seen in the 9505<a href="#bbv2.extender.intro">introduction</a>.</p> 9506</div> 9507<div class="listingblock"> 9508<div class="content"> 9509<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-nb">import</span><span class="tok-w"> </span>generators<span class="tok-w"> </span>;<span class="tok-w"></span> 9510generators.register-standard<span class="tok-w"> </span>verbatim.inline-file<span class="tok-w"> </span>:<span class="tok-w"> </span>VERBATIM<span class="tok-w"> </span>:<span class="tok-w"> </span>CPP<span class="tok-w"> </span>;<span class="tok-w"></span> 9511<span class="tok-k">actions</span><span class="tok-w"> </span><span class="tok-nf">inline-file</span><span class="tok-w"></span> 9512{<span class="tok-sh"></span> 9513<span class="tok-sh"> "./inline-file.py" </span><span class="tok-si">$(<)</span><span class="tok-sh"> </span><span class="tok-si">$(>)</span><span class="tok-sh"></span> 9514<span class="tok-p">}</span><span class="tok-w"></span></code></pre> 9515</div> 9516</div> 9517<div class="paragraph"> 9518<p>We declare a standard generator, specifying its id, the source type and 9519the target type. When invoked, the generator will create a target of 9520type <code>CPP</code> with a source target of type <code>VERBATIM</code> as the only source. 9521But what command will be used to actually generate the file? In 9522B2, actions are specified using named "actions" blocks and the 9523name of the action block should be specified when creating targets. By 9524convention, generators use the same name of the action block as their 9525own id. So, in above example, the "inline-file" actions block will be 9526used to convert the source into the target.</p> 9527</div> 9528<div class="paragraph"> 9529<p>There are two primary kinds of generators: standard and composing, which 9530are registered with the <code>generators.register-standard</code> and the 9531<code>generators.register-composing</code> rules, respectively. For example:</p> 9532</div> 9533<div class="listingblock"> 9534<div class="content"> 9535<pre class="pygments highlight"><code data-lang="jam"><span></span>generators.register-standard<span class="tok-w"> </span>verbatim.inline-file<span class="tok-w"> </span>:<span class="tok-w"> </span>VERBATIM<span class="tok-w"> </span>:<span class="tok-w"> </span>CPP<span class="tok-w"> </span>;<span class="tok-w"></span> 9536generators.register-composing<span class="tok-w"> </span>mex.mex<span class="tok-w"> </span>:<span class="tok-w"> </span>CPP<span class="tok-w"> </span>LIB<span class="tok-w"> </span>:<span class="tok-w"> </span>MEX<span class="tok-w"> </span>;<span class="tok-w"></span></code></pre> 9537</div> 9538</div> 9539<div class="paragraph"> 9540<p>The first (standard) generator takes a <em>single</em> source of type 9541<code>VERBATIM</code> and produces a result. The second (composing) generator takes 9542any number of sources, which can have either the <code>CPP</code> or the <code>LIB</code> 9543type. Composing generators are typically used for generating top-level 9544target type. For example, the first generator invoked when building an 9545<code>exe</code> target is a composing generator corresponding to the proper 9546linker.</p> 9547</div> 9548<div class="paragraph"> 9549<p>You should also know about two specific functions for registering 9550generators: <code>generators.register-c-compiler</code> and 9551<code>generators.register-linker</code>. The first sets up header dependency 9552scanning for C files, and the seconds handles various complexities like 9553searched libraries. For that reason, you should always use those 9554functions when adding support for compilers and linkers.</p> 9555</div> 9556<div class="paragraph"> 9557<p>(Need a note about UNIX)</p> 9558</div> 9559<div class="paragraph"> 9560<p><strong>Custom generator classes</strong></p> 9561</div> 9562<div class="paragraph"> 9563<p>The standard generators allows you to specify source and target types, 9564an action, and a set of flags. If you need anything more complex, you 9565need to create a new generator class with your own logic. Then, you have 9566to create an instance of that class and register it. Here’s an example 9567how you can create your own generator class:</p> 9568</div> 9569<div class="listingblock"> 9570<div class="content"> 9571<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-k">class</span><span class="tok-w"> </span><span class="tok-nc">custom-generator</span><span class="tok-w"> </span><span class="tok-p">:</span><span class="tok-w"> </span><span class="tok-nc">generator</span><span class="tok-w"></span> 9572{<span class="tok-w"></span> 9573<span class="tok-w"> </span><span class="tok-k">rule</span><span class="tok-w"> </span><span class="tok-nf">__init__</span><span class="tok-w"> </span><span class="tok-p">(</span><span class="tok-w"> </span><span class="tok-p">*</span><span class="tok-w"> </span><span class="tok-p">:</span><span class="tok-w"> </span><span class="tok-p">*</span><span class="tok-w"> </span><span class="tok-p">)</span><span class="tok-w"></span> 9574<span class="tok-w"> </span>{<span class="tok-w"></span> 9575<span class="tok-w"> </span>generator.__init__<span class="tok-w"> </span><span class="tok-si">$(1)</span><span class="tok-w"> </span>:<span class="tok-w"> </span><span class="tok-si">$(2)</span><span class="tok-w"> </span>:<span class="tok-w"> </span><span class="tok-si">$(3)</span><span class="tok-w"> </span>:<span class="tok-w"> </span><span class="tok-si">$(4)</span><span class="tok-w"> </span>:<span class="tok-w"> </span><span class="tok-si">$(5)</span><span class="tok-w"> </span>:<span class="tok-w"> </span><span class="tok-si">$(6)</span><span class="tok-w"> </span>:<span class="tok-w"> </span><span class="tok-si">$(7)</span><span class="tok-w"> </span>:<span class="tok-w"> </span><span class="tok-si">$(8)</span><span class="tok-w"> </span>:<span class="tok-w"> </span><span class="tok-si">$(9)</span><span class="tok-w"> </span>;<span class="tok-w"></span> 9576<span class="tok-w"> </span>}<span class="tok-w"></span> 9577 9578}<span class="tok-w"></span> 9579 9580generators.register<span class="tok-w"></span> 9581<span class="tok-w"> </span>[<span class="tok-w"> </span>new<span class="tok-w"> </span>custom-generator<span class="tok-w"> </span>verbatim.inline-file<span class="tok-w"> </span>:<span class="tok-w"> </span>VERBATIM<span class="tok-w"> </span>:<span class="tok-w"> </span>CPP<span class="tok-w"> </span>]<span class="tok-w"> </span>;<span class="tok-w"></span></code></pre> 9582</div> 9583</div> 9584<div class="paragraph"> 9585<p>This generator will work exactly like the <code>verbatim.inline-file</code> 9586generator we’ve defined above, but it’s possible to customize the 9587behavior by overriding methods of the <code>generator</code> class.</p> 9588</div> 9589<div class="paragraph"> 9590<p>There are two methods of interest. The <code>run</code> method is responsible for 9591the overall process - it takes a number of source targets, converts them 9592to the right types, and creates the result. The <code>generated-targets</code> 9593method is called when all sources are converted to the right types to 9594actually create the result.</p> 9595</div> 9596<div class="paragraph"> 9597<p>The <code>generated-targets</code> method can be overridden when you want to add 9598additional properties to the generated targets or use additional 9599sources. For a real-life example, suppose you have a program analysis 9600tool that should be given a name of executable and the list of all 9601sources. Naturally, you don’t want to list all source files manually. 9602Here’s how the <code>generated-targets</code> method can find the list of sources 9603automatically:</p> 9604</div> 9605<div class="listingblock"> 9606<div class="content"> 9607<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-k">class</span><span class="tok-w"> </span><span class="tok-nc">itrace-generator</span><span class="tok-w"> </span><span class="tok-p">:</span><span class="tok-w"> </span><span class="tok-nc">generator</span><span class="tok-w"> </span>{<span class="tok-w"></span> 9608...<span class="tok-w"></span> 9609<span class="tok-w"> </span><span class="tok-k">rule</span><span class="tok-w"> </span><span class="tok-nf">generated-targets</span><span class="tok-w"> </span><span class="tok-p">(</span><span class="tok-w"> </span><span class="tok-nv">sources</span><span class="tok-w"> </span><span class="tok-p">+</span><span class="tok-w"> </span><span class="tok-p">:</span><span class="tok-w"> </span><span class="tok-nv">property-set</span><span class="tok-w"> </span><span class="tok-p">:</span><span class="tok-w"> </span><span class="tok-nv">project</span><span class="tok-w"> </span><span class="tok-nv">name</span><span class="tok-w"> </span><span class="tok-p">?</span><span class="tok-w"> </span><span class="tok-p">)</span><span class="tok-w"></span> 9610<span class="tok-w"> </span>{<span class="tok-w"></span> 9611<span class="tok-w"> </span><span class="tok-k">local</span><span class="tok-w"> </span>leaves<span class="tok-w"> </span>;<span class="tok-w"></span> 9612<span class="tok-w"> </span><span class="tok-k">local</span><span class="tok-w"> </span>temp<span class="tok-w"> </span>=<span class="tok-w"> </span>[<span class="tok-w"> </span>virtual-target.traverse<span class="tok-w"> </span><span class="tok-si">$(sources[1])</span><span class="tok-w"> </span>:<span class="tok-w"> </span>:<span class="tok-w"> </span><span class="tok-k">include</span>-sources<span class="tok-w"> </span>]<span class="tok-w"> </span>;<span class="tok-w"></span> 9613<span class="tok-w"> </span><span class="tok-k">for</span><span class="tok-w"> </span><span class="tok-k">local</span><span class="tok-w"> </span>t<span class="tok-w"> </span><span class="tok-k">in</span><span class="tok-w"> </span><span class="tok-si">$(temp)</span><span class="tok-w"></span> 9614<span class="tok-w"> </span>{<span class="tok-w"></span> 9615<span class="tok-w"> </span><span class="tok-k">if</span><span class="tok-w"> </span>!<span class="tok-w"> </span>[<span class="tok-w"> </span><span class="tok-si">$(t)</span>.action<span class="tok-w"> </span>]<span class="tok-w"></span> 9616<span class="tok-w"> </span>{<span class="tok-w"></span> 9617<span class="tok-w"> </span>leaves<span class="tok-w"> </span>+=<span class="tok-w"> </span><span class="tok-si">$(t)</span><span class="tok-w"> </span>;<span class="tok-w"></span> 9618<span class="tok-w"> </span>}<span class="tok-w"></span> 9619<span class="tok-w"> </span>}<span class="tok-w"></span> 9620<span class="tok-w"> </span><span class="tok-k">return</span><span class="tok-w"> </span>[<span class="tok-w"> </span>generator.generated-targets<span class="tok-w"> </span><span class="tok-si">$(sources)</span><span class="tok-w"> </span><span class="tok-si">$(leafs)</span><span class="tok-w"></span> 9621<span class="tok-w"> </span>:<span class="tok-w"> </span><span class="tok-si">$(property-set)</span><span class="tok-w"> </span>:<span class="tok-w"> </span><span class="tok-si">$(project)</span><span class="tok-w"> </span><span class="tok-si">$(name)</span><span class="tok-w"> </span>]<span class="tok-w"> </span>;<span class="tok-w"></span> 9622<span class="tok-w"> </span>}<span class="tok-w"></span> 9623}<span class="tok-w"></span> 9624generators.register<span class="tok-w"> </span>[<span class="tok-w"> </span>new<span class="tok-w"> </span>itrace-generator<span class="tok-w"> </span>nm.itrace<span class="tok-w"> </span>:<span class="tok-w"> </span>EXE<span class="tok-w"> </span>:<span class="tok-w"> </span>ITRACE<span class="tok-w"> </span>]<span class="tok-w"> </span>;<span class="tok-w"></span></code></pre> 9625</div> 9626</div> 9627<div class="paragraph"> 9628<p>The <code>generated-targets</code> method will be called with a single source 9629target of type <code>EXE</code>. The call to <code>virtual-target.traverse</code> will return 9630all targets the executable depends on, and we further find files that 9631are not produced from anything. The found targets are added to the 9632sources.</p> 9633</div> 9634<div class="paragraph"> 9635<p>The <code>run</code> method can be overridden to completely customize the way the 9636generator works. In particular, the conversion of sources to the desired 9637types can be completely customized. Here’s another real example. Tests 9638for the Boost Python library usually consist of two parts: a Python 9639program and a C++ file. The C++ file is compiled to Python extension 9640that is loaded by the Python program. But in the likely case that both 9641files have the same name, the created Python extension must be renamed. 9642Otherwise, the Python program will import itself, not the extension. 9643Here’s how it can be done:</p> 9644</div> 9645<div class="listingblock"> 9646<div class="content"> 9647<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-k">rule</span><span class="tok-w"> </span><span class="tok-nf">run</span><span class="tok-w"> </span><span class="tok-p">(</span><span class="tok-w"> </span><span class="tok-nv">project</span><span class="tok-w"> </span><span class="tok-nv">name</span><span class="tok-w"> </span><span class="tok-p">?</span><span class="tok-w"> </span><span class="tok-p">:</span><span class="tok-w"> </span><span class="tok-nv">property-set</span><span class="tok-w"> </span><span class="tok-p">:</span><span class="tok-w"> </span><span class="tok-nv">sources</span><span class="tok-w"> </span><span class="tok-p">*</span><span class="tok-w"> </span><span class="tok-p">)</span><span class="tok-w"></span> 9648{<span class="tok-w"></span> 9649<span class="tok-w"> </span><span class="tok-k">local</span><span class="tok-w"> </span>python<span class="tok-w"> </span>;<span class="tok-w"></span> 9650<span class="tok-w"> </span><span class="tok-k">for</span><span class="tok-w"> </span><span class="tok-k">local</span><span class="tok-w"> </span>s<span class="tok-w"> </span><span class="tok-k">in</span><span class="tok-w"> </span><span class="tok-si">$(sources)</span><span class="tok-w"></span> 9651<span class="tok-w"> </span>{<span class="tok-w"></span> 9652<span class="tok-w"> </span><span class="tok-k">if</span><span class="tok-w"> </span>[<span class="tok-w"> </span><span class="tok-si">$(s)</span>.type<span class="tok-w"> </span>]<span class="tok-w"> </span>=<span class="tok-w"> </span>PY<span class="tok-w"></span> 9653<span class="tok-w"> </span>{<span class="tok-w"></span> 9654<span class="tok-w"> </span>python<span class="tok-w"> </span>=<span class="tok-w"> </span><span class="tok-si">$(s)</span><span class="tok-w"> </span>;<span class="tok-w"></span> 9655<span class="tok-w"> </span>}<span class="tok-w"></span> 9656<span class="tok-w"> </span>}<span class="tok-w"></span> 9657 9658<span class="tok-w"> </span><span class="tok-k">local</span><span class="tok-w"> </span>libs<span class="tok-w"> </span>;<span class="tok-w"></span> 9659<span class="tok-w"> </span><span class="tok-k">for</span><span class="tok-w"> </span><span class="tok-k">local</span><span class="tok-w"> </span>s<span class="tok-w"> </span><span class="tok-k">in</span><span class="tok-w"> </span><span class="tok-si">$(sources)</span><span class="tok-w"></span> 9660<span class="tok-w"> </span>{<span class="tok-w"></span> 9661<span class="tok-w"> </span><span class="tok-k">if</span><span class="tok-w"> </span>[<span class="tok-w"> </span>type.is-derived<span class="tok-w"> </span>[<span class="tok-w"> </span><span class="tok-si">$(s)</span>.type<span class="tok-w"> </span>]<span class="tok-w"> </span>LIB<span class="tok-w"> </span>]<span class="tok-w"></span> 9662<span class="tok-w"> </span>{<span class="tok-w"></span> 9663<span class="tok-w"> </span>libs<span class="tok-w"> </span>+=<span class="tok-w"> </span><span class="tok-si">$(s)</span><span class="tok-w"> </span>;<span class="tok-w"></span> 9664<span class="tok-w"> </span>}<span class="tok-w"></span> 9665<span class="tok-w"> </span>}<span class="tok-w"></span> 9666 9667<span class="tok-w"> </span><span class="tok-k">local</span><span class="tok-w"> </span>new-sources<span class="tok-w"> </span>;<span class="tok-w"></span> 9668<span class="tok-w"> </span><span class="tok-k">for</span><span class="tok-w"> </span><span class="tok-k">local</span><span class="tok-w"> </span>s<span class="tok-w"> </span><span class="tok-k">in</span><span class="tok-w"> </span><span class="tok-si">$(sources)</span><span class="tok-w"></span> 9669<span class="tok-w"> </span>{<span class="tok-w"></span> 9670<span class="tok-w"> </span><span class="tok-k">if</span><span class="tok-w"> </span>[<span class="tok-w"> </span>type.is-derived<span class="tok-w"> </span>[<span class="tok-w"> </span><span class="tok-si">$(s)</span>.type<span class="tok-w"> </span>]<span class="tok-w"> </span>CPP<span class="tok-w"> </span>]<span class="tok-w"></span> 9671<span class="tok-w"> </span>{<span class="tok-w"></span> 9672<span class="tok-w"> </span><span class="tok-k">local</span><span class="tok-w"> </span>name<span class="tok-w"> </span>=<span class="tok-w"> </span>[<span class="tok-w"> </span><span class="tok-si">$(s)</span>.name<span class="tok-w"> </span>]<span class="tok-w"> </span>;<span class="tok-w"> </span><span class="tok-c1"># get the target's basename</span> 9673<span class="tok-w"> </span><span class="tok-k">if</span><span class="tok-w"> </span><span class="tok-si">$(name)</span><span class="tok-w"> </span>=<span class="tok-w"> </span>[<span class="tok-w"> </span><span class="tok-si">$(python)</span>.name<span class="tok-w"> </span>]<span class="tok-w"></span> 9674<span class="tok-w"> </span>{<span class="tok-w"></span> 9675<span class="tok-w"> </span>name<span class="tok-w"> </span>=<span class="tok-w"> </span><span class="tok-si">$(name)</span>_ext<span class="tok-w"> </span>;<span class="tok-w"> </span><span class="tok-c1"># rename the target</span> 9676<span class="tok-w"> </span>}<span class="tok-w"></span> 9677<span class="tok-w"> </span>new-sources<span class="tok-w"> </span>+=<span class="tok-w"> </span>[<span class="tok-w"> </span>generators.construct<span class="tok-w"> </span><span class="tok-si">$(project)</span><span class="tok-w"> </span><span class="tok-si">$(name)</span><span class="tok-w"> </span>:<span class="tok-w"></span> 9678<span class="tok-w"> </span>PYTHON_EXTENSION<span class="tok-w"> </span>:<span class="tok-w"> </span><span class="tok-si">$(property-set)</span><span class="tok-w"> </span>:<span class="tok-w"> </span><span class="tok-si">$(s)</span><span class="tok-w"> </span><span class="tok-si">$(libs)</span><span class="tok-w"> </span>]<span class="tok-w"> </span>;<span class="tok-w"></span> 9679<span class="tok-w"> </span>}<span class="tok-w"></span> 9680<span class="tok-w"> </span>}<span class="tok-w"></span> 9681 9682<span class="tok-w"> </span>result<span class="tok-w"> </span>=<span class="tok-w"> </span>[<span class="tok-w"> </span>construct-result<span class="tok-w"> </span><span class="tok-si">$(python)</span><span class="tok-w"> </span><span class="tok-si">$(new-sources)</span><span class="tok-w"> </span>:<span class="tok-w"> </span><span class="tok-si">$(project)</span><span class="tok-w"> </span><span class="tok-si">$(name)</span><span class="tok-w"></span> 9683<span class="tok-w"> </span>:<span class="tok-w"> </span><span class="tok-si">$(property-set)</span><span class="tok-w"> </span>]<span class="tok-w"> </span>;<span class="tok-w"></span> 9684}<span class="tok-w"></span></code></pre> 9685</div> 9686</div> 9687<div class="paragraph"> 9688<p>First, we separate all source into python files, libraries and C++ 9689sources. For each C++ source we create a separate Python extension by 9690calling <code>generators.construct</code> and passing the C++ source and the 9691libraries. At this point, we also change the extension’s name, if 9692necessary.</p> 9693</div> 9694</div> 9695<div class="sect2"> 9696<h3 id="bbv2.extending.features"><a class="anchor" href="#bbv2.extending.features"></a>7.6. Features</h3> 9697<div class="paragraph"> 9698<p>Often, we need to control the options passed the invoked tools. This is 9699done with features. Consider an example:</p> 9700</div> 9701<div class="listingblock"> 9702<div class="content"> 9703<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-c1"># Declare a new free feature</span> 9704<span class="tok-nb">import</span><span class="tok-w"> </span>feature<span class="tok-w"> </span>:<span class="tok-w"> </span>feature<span class="tok-w"> </span>;<span class="tok-w"></span> 9705feature<span class="tok-w"> </span>verbatim-options<span class="tok-w"> </span>:<span class="tok-w"> </span>:<span class="tok-w"> </span>free<span class="tok-w"> </span>;<span class="tok-w"></span> 9706 9707<span class="tok-c1"># Cause the value of the 'verbatim-options' feature to be</span> 9708<span class="tok-c1"># available as 'OPTIONS' variable inside verbatim.inline-file</span> 9709<span class="tok-nb">import</span><span class="tok-w"> </span>toolset<span class="tok-w"> </span>:<span class="tok-w"> </span>flags<span class="tok-w"> </span>;<span class="tok-w"></span> 9710flags<span class="tok-w"> </span>verbatim.inline-file<span class="tok-w"> </span>OPTIONS<span class="tok-w"> </span><span class="tok-na"><verbatim-options></span><span class="tok-w"> </span>;<span class="tok-w"></span> 9711 9712<span class="tok-c1"># Use the "OPTIONS" variable</span> 9713<span class="tok-k">actions</span><span class="tok-w"> </span><span class="tok-nf">inline-file</span><span class="tok-w"></span> 9714{<span class="tok-sh"></span> 9715<span class="tok-sh"> "./inline-file.py" </span><span class="tok-si">$(OPTIONS)</span><span class="tok-sh"> </span><span class="tok-si">$(<)</span><span class="tok-sh"> </span><span class="tok-si">$(>)</span><span class="tok-sh"></span> 9716<span class="tok-p">}</span><span class="tok-w"></span></code></pre> 9717</div> 9718</div> 9719<div class="paragraph"> 9720<p>We first define a new feature. Then, the <code>flags</code> invocation says that 9721whenever verbatim.inline-file action is run, the value of the 9722<code>verbatim-options</code> feature will be added to the <code>OPTIONS</code> variable, and 9723can be used inside the action body. You’d need to consult online help 9724(--help) to find all the features of the <code>toolset.flags</code> rule.</p> 9725</div> 9726<div class="paragraph"> 9727<p>Although you can define any set of features and interpret their values 9728in any way, B2 suggests the following coding standard for 9729designing features.</p> 9730</div> 9731<div class="paragraph"> 9732<p>Most features should have a fixed set of values that is portable (tool 9733neutral) across the class of tools they are designed to work with. The 9734user does not have to adjust the values for a exact tool. For example, 9735<code><optimization>speed</code> has the same meaning for all C++ compilers and the 9736user does not have to worry about the exact options passed to the 9737compiler’s command line.</p> 9738</div> 9739<div class="paragraph"> 9740<p>Besides such portable features there are special 'raw' features that 9741allow the user to pass any value to the command line parameters for a 9742particular tool, if so desired. For example, the <code><cxxflags></code> feature 9743allows you to pass any command line options to a C++ compiler. The 9744<code><include></code> feature allows you to pass any string preceded by <code>-I</code> and 9745the interpretation is tool-specific. (See <a href="#bbv2.faq.external">Can I get capture external program output using a Boost.Jam variable?</a> 9746for an example of very smart usage of that feature). Of course one 9747should always strive to use portable features, but these are still be 9748provided as a backdoor just to make sure B2 does not take away 9749any control from the user.</p> 9750</div> 9751<div class="paragraph"> 9752<p>Using portable features is a good idea because:</p> 9753</div> 9754<div class="ulist"> 9755<ul> 9756<li> 9757<p>When a portable feature is given a fixed set of values, you can build 9758your project with two different settings of the feature and B2 9759will automatically use two different directories for generated files. 9760B2 does not try to separate targets built with different raw 9761options.</p> 9762</li> 9763<li> 9764<p>Unlike with “raw” features, you don’t need to use specific 9765command-line flags in your Jamfile, and it will be more likely to work 9766with other tools.</p> 9767</li> 9768</ul> 9769</div> 9770<div class="paragraph"> 9771<p><strong>Steps for adding a feature</strong></p> 9772</div> 9773<div class="paragraph"> 9774<p>Adding a feature requires three steps:</p> 9775</div> 9776<div class="olist arabic"> 9777<ol class="arabic"> 9778<li> 9779<p>Declaring a feature. For that, the "feature.feature" rule is used. 9780You have to decide on the set of 9781<a href="#bbv2.reference.features.attributes">feature attributes</a>:</p> 9782<div class="ulist"> 9783<ul> 9784<li> 9785<p>if you want a feature value set for one target to automatically 9786propagate to its dependent targets then make it “propagated”.</p> 9787</li> 9788<li> 9789<p>if a feature does not have a fixed list of values, it must be “free.” 9790For example, the <code>include</code> feature is a free feature.</p> 9791</li> 9792<li> 9793<p>if a feature is used to refer to a path relative to the Jamfile, it 9794must be a “path” feature. Such features will also get their values 9795automatically converted to B2’s internal path representation. 9796For example, <code>include</code> is a path feature.</p> 9797</li> 9798<li> 9799<p>if feature is used to refer to some target, it must be a “dependency” 9800feature.</p> 9801</li> 9802</ul> 9803</div> 9804</li> 9805<li> 9806<p>Representing the feature value in a target-specific variable. Build 9807actions are command templates modified by Boost.Jam variable expansions. 9808The <code>toolset.flags</code> rule sets a target-specific variable to the value of 9809a feature.</p> 9810</li> 9811<li> 9812<p>Using the variable. The variable set in step 2 can be used in a 9813build action to form command parameters or files.</p> 9814</li> 9815</ol> 9816</div> 9817<div class="paragraph"> 9818<p><strong>Another example</strong></p> 9819</div> 9820<div class="paragraph"> 9821<p>Here’s another example. Let’s see how we can make a feature that refers 9822to a target. For example, when linking dynamic libraries on Windows, one 9823sometimes needs to specify a "DEF file", telling what functions should 9824be exported. It would be nice to use this file like this:</p> 9825</div> 9826<div class="listingblock"> 9827<div class="content"> 9828<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-nb">lib</span><span class="tok-w"> </span>a<span class="tok-w"> </span>:<span class="tok-w"> </span>a.cpp<span class="tok-w"> </span>:<span class="tok-w"> </span><span class="tok-na"><def-file></span>a.def<span class="tok-w"> </span>;<span class="tok-w"></span></code></pre> 9829</div> 9830</div> 9831<div class="paragraph"> 9832<p>Actually, this feature is already supported, but anyway…​</p> 9833</div> 9834<div class="olist arabic"> 9835<ol class="arabic"> 9836<li> 9837<p>Since the feature refers to a target, it must be "dependency".</p> 9838<div class="listingblock"> 9839<div class="content"> 9840<pre>feature def-file : : free dependency ;</pre> 9841</div> 9842</div> 9843</li> 9844<li> 9845<p>One of the toolsets that cares about DEF files is msvc. The 9846following line should be added to it.</p> 9847<div class="listingblock"> 9848<div class="content"> 9849<pre>flags msvc.link DEF_FILE <def-file> ;</pre> 9850</div> 9851</div> 9852</li> 9853<li> 9854<p>Since the DEF_FILE variable is not used by the msvc.link action, we 9855need to modify it to be:</p> 9856<div class="listingblock"> 9857<div class="content"> 9858<pre>actions link bind DEF_FILE 9859{ 9860 $(.LD) .... /DEF:$(DEF_FILE) .... 9861}</pre> 9862</div> 9863</div> 9864<div class="paragraph"> 9865<p>Note the <code>bind DEF_FILE</code> part. It tells B2 to translate the 9866internal target name in <code>DEF_FILE</code> to a corresponding filename in the 9867<code>link</code> action. Without it the expansion of <code>$(DEF_FILE)</code> would be a 9868strange symbol that is not likely to make sense for the linker.</p> 9869</div> 9870<div class="paragraph"> 9871<p>We are almost done, except for adding the following code to <code>msvc.jam</code>:</p> 9872</div> 9873<div class="listingblock"> 9874<div class="content"> 9875<pre>rule link 9876{ 9877 DEPENDS $(<) : [ on $(<) return $(DEF_FILE) ] ; 9878}</pre> 9879</div> 9880</div> 9881<div class="paragraph"> 9882<p>This is a workaround for a bug in B2 engine, which will 9883hopefully be fixed one day.</p> 9884</div> 9885</li> 9886</ol> 9887</div> 9888<div class="paragraph"> 9889<p><strong>Variants and composite features.</strong></p> 9890</div> 9891<div class="paragraph"> 9892<p>Sometimes you want to create a shortcut for some set of features. For 9893example, <code>release</code> is a value of <code><variant></code> and is a shortcut for a set 9894of features.</p> 9895</div> 9896<div class="paragraph"> 9897<p>It is possible to define your own build variants. For example:</p> 9898</div> 9899<div class="listingblock"> 9900<div class="content"> 9901<pre class="pygments highlight"><code data-lang="jam"><span></span>variant<span class="tok-w"> </span>crazy<span class="tok-w"> </span>:<span class="tok-w"> </span><span class="tok-na"><optimization></span>speed<span class="tok-w"> </span><span class="tok-na"><inlining></span>off<span class="tok-w"></span> 9902<span class="tok-w"> </span><span class="tok-na"><debug-symbols></span>on<span class="tok-w"> </span><span class="tok-na"><profiling></span>on<span class="tok-w"> </span>;<span class="tok-w"></span></code></pre> 9903</div> 9904</div> 9905<div class="paragraph"> 9906<p>will define a new variant with the specified set of properties. You can 9907also extend an existing variant:</p> 9908</div> 9909<div class="listingblock"> 9910<div class="content"> 9911<pre class="pygments highlight"><code data-lang="jam"><span></span>variant<span class="tok-w"> </span>super_release<span class="tok-w"> </span>:<span class="tok-w"> </span>release<span class="tok-w"> </span>:<span class="tok-w"> </span><span class="tok-na"><define></span>USE_ASM<span class="tok-w"> </span>;<span class="tok-w"></span></code></pre> 9912</div> 9913</div> 9914<div class="paragraph"> 9915<p>In this case, <code>super_release</code> will expand to all properties specified by 9916<code>release</code>, and the additional one you’ve specified.</p> 9917</div> 9918<div class="paragraph"> 9919<p>You are not restricted to using the <code>variant</code> feature only. Here’s 9920example that defines a brand new feature:</p> 9921</div> 9922<div class="listingblock"> 9923<div class="content"> 9924<pre class="pygments highlight"><code data-lang="jam"><span></span>feature<span class="tok-w"> </span>parallelism<span class="tok-w"> </span>:<span class="tok-w"> </span>mpi<span class="tok-w"> </span>fake<span class="tok-w"> </span>none<span class="tok-w"> </span>:<span class="tok-w"> </span>composite<span class="tok-w"> </span><span class="tok-nb">link</span>-incompatible<span class="tok-w"> </span>;<span class="tok-w"></span> 9925feature.compose<span class="tok-w"> </span><span class="tok-na"><parallelism></span>mpi<span class="tok-w"> </span>:<span class="tok-w"> </span><span class="tok-na"><library></span>/mpi//mpi/<span class="tok-na"><parallelism></span>none<span class="tok-w"> </span>;<span class="tok-w"></span> 9926feature.compose<span class="tok-w"> </span><span class="tok-na"><parallelism></span>fake<span class="tok-w"> </span>:<span class="tok-w"> </span><span class="tok-na"><library></span>/mpi//fake/<span class="tok-na"><parallelism></span>none<span class="tok-w"> </span>;<span class="tok-w"></span></code></pre> 9927</div> 9928</div> 9929<div class="paragraph"> 9930<p>This will allow you to specify the value of feature <code>parallelism</code>, which 9931will expand to link to the necessary library.</p> 9932</div> 9933</div> 9934<div class="sect2"> 9935<h3 id="bbv2.extending.rules"><a class="anchor" href="#bbv2.extending.rules"></a>7.7. Main target rules</h3> 9936<div class="paragraph"> 9937<p>A main target rule (e.g “<a href="#bbv2.tasks.programs">exe</a>” Or 9938“<a href="#bbv2.tasks.libraries">lib</a>”) creates a top-level target. It’s 9939quite likely that you’ll want to declare your own and there are two ways 9940to do that.</p> 9941</div> 9942<div class="paragraph"> 9943<p><a id="bbv2.extending.rules.main-type"></a>The first way applies when your target rule 9944should just produce a target 9945of specific type. In that case, a rule is already defined for you! When 9946you define a new type, B2 automatically defines a corresponding 9947rule. The name of the rule is obtained from the name of the type, by 9948down-casing all letters and replacing underscores with dashes. For 9949example, if you create a module <code>obfuscate.jam</code> containing:</p> 9950</div> 9951<div class="listingblock"> 9952<div class="content"> 9953<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-nb">import</span><span class="tok-w"> </span>type<span class="tok-w"> </span>;<span class="tok-w"></span> 9954type.register<span class="tok-w"> </span>OBFUSCATED_CPP<span class="tok-w"> </span>:<span class="tok-w"> </span>ocpp<span class="tok-w"> </span>;<span class="tok-w"></span> 9955 9956<span class="tok-nb">import</span><span class="tok-w"> </span>generators<span class="tok-w"> </span>;<span class="tok-w"></span> 9957generators.register-standard<span class="tok-w"> </span>obfuscate.file<span class="tok-w"> </span>:<span class="tok-w"> </span>CPP<span class="tok-w"> </span>:<span class="tok-w"> </span>OBFUSCATED_CPP<span class="tok-w"> </span>;<span class="tok-w"></span></code></pre> 9958</div> 9959</div> 9960<div class="paragraph"> 9961<p>and import that module, you’ll be able to use the rule "obfuscated-cpp" 9962in Jamfiles, which will convert source to the OBFUSCATED_CPP type.</p> 9963</div> 9964<div class="paragraph"> 9965<p>The second way is to write a wrapper rule that calls any of the existing 9966rules. For example, suppose you have only one library per directory and 9967want all cpp files in the directory to be compiled into that library. 9968You can achieve this effect using:</p> 9969</div> 9970<div class="listingblock"> 9971<div class="content"> 9972<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-nb">lib</span><span class="tok-w"> </span>codegen<span class="tok-w"> </span>:<span class="tok-w"> </span>[<span class="tok-w"> </span><span class="tok-nb">glob</span><span class="tok-w"> </span>*.cpp<span class="tok-w"> </span>]<span class="tok-w"> </span>;<span class="tok-w"></span></code></pre> 9973</div> 9974</div> 9975<div class="paragraph"> 9976<p>If you want to make it even simpler, you could add the following 9977definition to the <code>Jamroot.jam</code> file:</p> 9978</div> 9979<div class="listingblock"> 9980<div class="content"> 9981<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-k">rule</span><span class="tok-w"> </span><span class="tok-nf">glib</span><span class="tok-w"> </span><span class="tok-p">(</span><span class="tok-w"> </span><span class="tok-nv">name</span><span class="tok-w"> </span><span class="tok-p">:</span><span class="tok-w"> </span><span class="tok-nv">extra-sources</span><span class="tok-w"> </span><span class="tok-p">*</span><span class="tok-w"> </span><span class="tok-p">:</span><span class="tok-w"> </span><span class="tok-nv">requirements</span><span class="tok-w"> </span><span class="tok-p">*</span><span class="tok-w"> </span><span class="tok-p">)</span><span class="tok-w"></span> 9982{<span class="tok-w"></span> 9983<span class="tok-w"> </span><span class="tok-nb">lib</span><span class="tok-w"> </span><span class="tok-si">$(name)</span><span class="tok-w"> </span>:<span class="tok-w"> </span>[<span class="tok-w"> </span><span class="tok-nb">glob</span><span class="tok-w"> </span>*.cpp<span class="tok-w"> </span>]<span class="tok-w"> </span><span class="tok-si">$(extra-sources)</span><span class="tok-w"> </span>:<span class="tok-w"> </span><span class="tok-si">$(requirements)</span><span class="tok-w"> </span>;<span class="tok-w"></span> 9984}<span class="tok-w"></span></code></pre> 9985</div> 9986</div> 9987<div class="paragraph"> 9988<p>allowing you to reduce the Jamfile to just</p> 9989</div> 9990<div class="listingblock"> 9991<div class="content"> 9992<pre class="pygments highlight"><code data-lang="jam"><span></span>glib<span class="tok-w"> </span>codegen<span class="tok-w"> </span>;<span class="tok-w"></span></code></pre> 9993</div> 9994</div> 9995<div class="paragraph"> 9996<p>Note that because you can associate a custom generator with a target 9997type, the logic of building can be rather complicated. For example, the 9998<code>boostbook</code> module declares a target type <code>BOOSTBOOK_MAIN</code> and a custom 9999generator for that type. You can use that as example if your main target 10000rule is non-trivial.</p> 10001</div> 10002</div> 10003<div class="sect2"> 10004<h3 id="bbv2.extending.toolset_modules"><a class="anchor" href="#bbv2.extending.toolset_modules"></a>7.8. Toolset modules</h3> 10005<div class="paragraph"> 10006<p>If your extensions will be used only on one project, they can be placed 10007in a separate <code>.jam</code> file and imported by your <code>Jamroot.jam</code>. If the 10008extensions will be used on many projects, users will thank you for a 10009finishing touch.</p> 10010</div> 10011<div class="paragraph"> 10012<p>The <code>using</code> rule provides a standard mechanism for loading and 10013configuring extensions. To make it work, your module should provide an 10014<code>init</code> rule. The rule will be called with the same parameters that were 10015passed to the <code>using</code> rule. The set of allowed parameters is determined 10016by you. For example, you can allow the user to specify paths, tool 10017versions, and other options.</p> 10018</div> 10019<div class="paragraph"> 10020<p>Here are some guidelines that help to make B2 more consistent:</p> 10021</div> 10022<div class="ulist"> 10023<ul> 10024<li> 10025<p>The <code>init</code> rule should never fail. Even if the user provided an 10026incorrect path, you should emit a warning and go on. Configuration may 10027be shared between different machines, and wrong values on one machine 10028can be OK on another.</p> 10029</li> 10030<li> 10031<p>Prefer specifying the command to be executed to specifying the tool’s 10032installation path. First of all, this gives more control: it’s possible 10033to specify</p> 10034<div class="listingblock"> 10035<div class="content"> 10036<pre>/usr/bin/g++-snapshot 10037time g++</pre> 10038</div> 10039</div> 10040<div class="paragraph"> 10041<p>as the command. Second, while some tools have a logical "installation 10042root", it’s better if the user doesn’t have to remember whether a 10043specific tool requires a full command or a path.</p> 10044</div> 10045</li> 10046<li> 10047<p>Check for multiple initialization. A user can try to initialize the 10048module several times. You need to check for this and decide what to do. 10049Typically, unless you support several versions of a tool, duplicate 10050initialization is a user error. If the tool’s version can be specified 10051during initialization, make sure the version is either always specified, 10052or never specified (in which case the tool is initialized only once). For 10053example, if you allow:</p> 10054<div class="listingblock"> 10055<div class="content"> 10056<pre>using yfc ; 10057using yfc : 3.3 ; 10058using yfc : 3.4 ;</pre> 10059</div> 10060</div> 10061<div class="paragraph"> 10062<p>Then it’s not clear if the first initialization corresponds to version 100633.3 of the tool, version 3.4 of the tool, or some other version. This 10064can lead to building twice with the same version.</p> 10065</div> 10066</li> 10067<li> 10068<p>If possible, <code>init</code> must be callable with no parameters. In which 10069case, it should try to autodetect all the necessary information, for 10070example, by looking for a tool in PATH or in common installation 10071locations. Often this is possible and allows the user to simply write:</p> 10072<div class="listingblock"> 10073<div class="content"> 10074<pre>using yfc ;</pre> 10075</div> 10076</div> 10077</li> 10078<li> 10079<p>Consider using facilities in the <code>tools/common</code> module. You can take a 10080look at how <code>tools/gcc.jam</code> uses that module in the <code>init</code> rule.</p> 10081</li> 10082</ul> 10083</div> 10084</div> 10085</div> 10086</div> 10087<div class="sect1"> 10088<h2 id="bbv2.faq"><a class="anchor" href="#bbv2.faq"></a>8. Frequently Asked Questions</h2> 10089<div class="sectionbody"> 10090<div class="sect2"> 10091<h3 id="bbv2.faq.featurevalue"><a class="anchor" href="#bbv2.faq.featurevalue"></a>8.1. How do I get the current value of feature in Jamfile?</h3> 10092<div class="paragraph"> 10093<p>This is not possible, since Jamfile does not have "current" value of any 10094feature, be it toolset, build variant or anything else. For a single run 10095of B2, any given main target can be built with several property 10096sets. For example, user can request two build variants on the command 10097line. Or one library is built as shared when used from one application, 10098and as static when used from another. Each Jamfile is read only once so 10099generally there is no single value of a feature you can access in 10100Jamfile.</p> 10101</div> 10102<div class="paragraph"> 10103<p>A feature has a specific value only when building a target, and there 10104are two ways you can use that value:</p> 10105</div> 10106<div class="ulist"> 10107<ul> 10108<li> 10109<p>Use conditional requirements or indirect conditional requirements. See 10110<a href="#bbv2.overview.targets.requirements.conditional">the section called “Requirements”</a>.</p> 10111</li> 10112<li> 10113<p>Define a custom generator and a custom main target type. The custom 10114generator can do arbitrary processing or properties. See the 10115<a href="#bbv2.extender">extender manual</a></p> 10116</li> 10117</ul> 10118</div> 10119</div> 10120<div class="sect2"> 10121<h3 id="bbv2.faq.duplicate"><a class="anchor" href="#bbv2.faq.duplicate"></a>8.2. I am getting a "Duplicate name of actual target" error. What does that mean?</h3> 10122<div class="paragraph"> 10123<p>The most likely case is that you are trying to compile the same file 10124twice, with almost the same, but differing properties. For example:</p> 10125</div> 10126<div class="listingblock"> 10127<div class="content"> 10128<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-nb">exe</span><span class="tok-w"> </span>a<span class="tok-w"> </span>:<span class="tok-w"> </span>a.cpp<span class="tok-w"> </span>:<span class="tok-w"> </span><span class="tok-na"><include></span>/usr/local/include<span class="tok-w"> </span>;<span class="tok-w"></span> 10129<span class="tok-nb">exe</span><span class="tok-w"> </span>b<span class="tok-w"> </span>:<span class="tok-w"> </span>a.cpp<span class="tok-w"> </span>;<span class="tok-w"></span></code></pre> 10130</div> 10131</div> 10132<div class="paragraph"> 10133<p>The above snippet requires two different compilations of <code>a.cpp</code>, which 10134differ only in their <code>include</code> property. Since the <code>include</code> feature is 10135declared as <code>free</code> B2 does not create a separate build 10136directory for each of its values and those two builds would both produce 10137object files generated in the same build directory. Ignoring this and 10138compiling the file only once would be dangerous as different includes 10139could potentially cause completely different code to be compiled.</p> 10140</div> 10141<div class="paragraph"> 10142<p>To solve this issue, you need to decide if the file should be compiled 10143once or twice.</p> 10144</div> 10145<div class="olist arabic"> 10146<ol class="arabic"> 10147<li> 10148<p>To compile the file only once, make sure that properties are the 10149same for both target requests:</p> 10150<div class="listingblock"> 10151<div class="content"> 10152<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-nb">exe</span><span class="tok-w"> </span>a<span class="tok-w"> </span>:<span class="tok-w"> </span>a.cpp<span class="tok-w"> </span>:<span class="tok-w"> </span><span class="tok-na"><include></span>/usr/local/include<span class="tok-w"> </span>;<span class="tok-w"></span> 10153<span class="tok-nb">exe</span><span class="tok-w"> </span>b<span class="tok-w"> </span>:<span class="tok-w"> </span>a.cpp<span class="tok-w"> </span>:<span class="tok-w"> </span><span class="tok-na"><include></span>/usr/local/include<span class="tok-w"> </span>;<span class="tok-w"></span></code></pre> 10154</div> 10155</div> 10156<div class="paragraph"> 10157<p>or:</p> 10158</div> 10159<div class="listingblock"> 10160<div class="content"> 10161<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-nb">alias</span><span class="tok-w"> </span>a-with-include<span class="tok-w"> </span>:<span class="tok-w"> </span>a.cpp<span class="tok-w"> </span>:<span class="tok-w"> </span><span class="tok-na"><include></span>/usr/local/include<span class="tok-w"> </span>;<span class="tok-w"></span> 10162<span class="tok-nb">exe</span><span class="tok-w"> </span>a<span class="tok-w"> </span>:<span class="tok-w"> </span>a-with-include<span class="tok-w"> </span>;<span class="tok-w"></span> 10163<span class="tok-nb">exe</span><span class="tok-w"> </span>b<span class="tok-w"> </span>:<span class="tok-w"> </span>a-with-include<span class="tok-w"> </span>;<span class="tok-w"></span></code></pre> 10164</div> 10165</div> 10166<div class="paragraph"> 10167<p>or if you want the <code>includes</code> property not to affect how any other 10168sources added for the built <code>a</code> and <code>b</code> executables would be compiled:</p> 10169</div> 10170<div class="listingblock"> 10171<div class="content"> 10172<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-nb">obj</span><span class="tok-w"> </span>a-obj<span class="tok-w"> </span>:<span class="tok-w"> </span>a.cpp<span class="tok-w"> </span>:<span class="tok-w"> </span><span class="tok-na"><include></span>/usr/local/include<span class="tok-w"> </span>;<span class="tok-w"></span> 10173<span class="tok-nb">exe</span><span class="tok-w"> </span>a<span class="tok-w"> </span>:<span class="tok-w"> </span>a-obj<span class="tok-w"> </span>;<span class="tok-w"></span> 10174<span class="tok-nb">exe</span><span class="tok-w"> </span>b<span class="tok-w"> </span>:<span class="tok-w"> </span>a-obj<span class="tok-w"> </span>;<span class="tok-w"></span></code></pre> 10175</div> 10176</div> 10177<div class="paragraph"> 10178<p>Note that in both of these cases the <code>include</code> property will be applied 10179only for building these object files and not any other sources that 10180might be added for targets <code>a</code> and <code>b</code>.</p> 10181</div> 10182</li> 10183<li> 10184<p>To compile the file twice, you can tell B2 to compile it to 10185two separate object files like so:</p> 10186<div class="listingblock"> 10187<div class="content"> 10188<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-nb">obj</span><span class="tok-w"> </span>a_obj<span class="tok-w"> </span>:<span class="tok-w"> </span>a.cpp<span class="tok-w"> </span>:<span class="tok-w"> </span><span class="tok-na"><include></span>/usr/local/include<span class="tok-w"> </span>;<span class="tok-w"></span> 10189<span class="tok-nb">obj</span><span class="tok-w"> </span>b_obj<span class="tok-w"> </span>:<span class="tok-w"> </span>a.cpp<span class="tok-w"> </span>;<span class="tok-w"></span> 10190<span class="tok-nb">exe</span><span class="tok-w"> </span>a<span class="tok-w"> </span>:<span class="tok-w"> </span>a_obj<span class="tok-w"> </span>;<span class="tok-w"></span> 10191<span class="tok-nb">exe</span><span class="tok-w"> </span>b<span class="tok-w"> </span>:<span class="tok-w"> </span>b_obj<span class="tok-w"> </span>;<span class="tok-w"></span></code></pre> 10192</div> 10193</div> 10194<div class="paragraph"> 10195<p>or you can make the object file targets local to the main target:</p> 10196</div> 10197<div class="listingblock"> 10198<div class="content"> 10199<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-nb">exe</span><span class="tok-w"> </span>a<span class="tok-w"> </span>:<span class="tok-w"> </span>[<span class="tok-w"> </span><span class="tok-nb">obj</span><span class="tok-w"> </span>a_obj<span class="tok-w"> </span>:<span class="tok-w"> </span>a.cpp<span class="tok-w"> </span>:<span class="tok-w"> </span><span class="tok-na"><include></span>/usr/local/include<span class="tok-w"> </span>]<span class="tok-w"> </span>;<span class="tok-w"></span> 10200<span class="tok-nb">exe</span><span class="tok-w"> </span>b<span class="tok-w"> </span>:<span class="tok-w"> </span>[<span class="tok-w"> </span><span class="tok-nb">obj</span><span class="tok-w"> </span>a_obj<span class="tok-w"> </span>:<span class="tok-w"> </span>a.cpp<span class="tok-w"> </span>]<span class="tok-w"> </span>;<span class="tok-w"></span></code></pre> 10201</div> 10202</div> 10203<div class="paragraph"> 10204<p>which will cause B2 to actually change the generated object 10205file names a bit for you and thus avoid any conflicts.</p> 10206</div> 10207<div class="paragraph"> 10208<p>Note that in both of these cases the <code>include</code> property will be applied 10209only for building these object files and not any other sources that 10210might be added for targets <code>a</code> and <code>b</code>.</p> 10211</div> 10212</li> 10213</ol> 10214</div> 10215<div class="paragraph"> 10216<p>A good question is why B2 can not use some of the above 10217approaches automatically. The problem is that such magic would only help 10218in half of the cases, while in the other half it would be silently doing 10219the wrong thing. It is simpler and safer to ask the user to clarify his 10220intention in such cases.</p> 10221</div> 10222</div> 10223<div class="sect2"> 10224<h3 id="bbv2.faq.envar"><a class="anchor" href="#bbv2.faq.envar"></a>8.3. Accessing environment variables</h3> 10225<div class="paragraph"> 10226<p>Many users would like to use environment variables in Jamfiles, for 10227example, to control the location of external libraries. In many cases it 10228is better to declare those external libraries in the site-config.jam 10229file, as documented in the <a href="#bbv2.recipes.site-config">recipes 10230section</a>. However, if the users already have the environment variables 10231set up, it may not be convenient for them to set up their 10232site-config.jam files as well and using the environment variables might 10233be reasonable.</p> 10234</div> 10235<div class="paragraph"> 10236<p>Boost.Jam automatically imports all environment variables into its 10237built-in .ENVIRON module so user can read them from there directly or by 10238using the helper os.environ rule. For example:</p> 10239</div> 10240<div class="listingblock"> 10241<div class="content"> 10242<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-nb">import</span><span class="tok-w"> </span>os<span class="tok-w"> </span>;<span class="tok-w"></span> 10243<span class="tok-k">local</span><span class="tok-w"> </span>unga-unga<span class="tok-w"> </span>=<span class="tok-w"> </span>[<span class="tok-w"> </span>os.environ<span class="tok-w"> </span>UNGA_UNGA<span class="tok-w"> </span>]<span class="tok-w"> </span>;<span class="tok-w"></span> 10244<span class="tok-nb">ECHO</span><span class="tok-w"> </span><span class="tok-si">$(unga-unga)</span><span class="tok-w"> </span>;<span class="tok-w"></span></code></pre> 10245</div> 10246</div> 10247<div class="paragraph"> 10248<p>or a bit more realistic:</p> 10249</div> 10250<div class="listingblock"> 10251<div class="content"> 10252<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-nb">import</span><span class="tok-w"> </span>os<span class="tok-w"> </span>;<span class="tok-w"></span> 10253<span class="tok-k">local</span><span class="tok-w"> </span>SOME_LIBRARY_PATH<span class="tok-w"> </span>=<span class="tok-w"> </span>[<span class="tok-w"> </span>os.environ<span class="tok-w"> </span>SOME_LIBRARY_PATH<span class="tok-w"> </span>]<span class="tok-w"> </span>;<span class="tok-w"></span> 10254<span class="tok-nb">exe</span><span class="tok-w"> </span>a<span class="tok-w"> </span>:<span class="tok-w"> </span>a.cpp<span class="tok-w"> </span>:<span class="tok-w"> </span><span class="tok-na"><include></span><span class="tok-si">$(SOME_LIBRARY_PATH)</span><span class="tok-w"> </span>;<span class="tok-w"></span></code></pre> 10255</div> 10256</div> 10257</div> 10258<div class="sect2"> 10259<h3 id="bbv2.faq.proporder"><a class="anchor" href="#bbv2.faq.proporder"></a>8.4. How to control properties order?</h3> 10260<div class="paragraph"> 10261<p>For internal reasons, B2 sorts all the properties 10262alphabetically. This means that if you write:</p> 10263</div> 10264<div class="listingblock"> 10265<div class="content"> 10266<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-nb">exe</span><span class="tok-w"> </span>a<span class="tok-w"> </span>:<span class="tok-w"> </span>a.cpp<span class="tok-w"> </span>:<span class="tok-w"> </span><span class="tok-na"><include></span>b<span class="tok-w"> </span><span class="tok-na"><include></span>a<span class="tok-w"> </span>;<span class="tok-w"></span></code></pre> 10267</div> 10268</div> 10269<div class="paragraph"> 10270<p>then the command line with first mention the <code>a</code> include directory, and 10271then <code>b</code>, even though they are specified in the opposite order. In most 10272cases, the user does not care. But sometimes the order of includes, or 10273other properties, is important. For such cases, a special syntax is 10274provided:</p> 10275</div> 10276<div class="listingblock"> 10277<div class="content"> 10278<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-nb">exe</span><span class="tok-w"> </span>a<span class="tok-w"> </span>:<span class="tok-w"> </span>a.cpp<span class="tok-w"> </span>:<span class="tok-w"> </span><span class="tok-na"><include></span>a&&b<span class="tok-w"> </span>;<span class="tok-w"></span></code></pre> 10279</div> 10280</div> 10281<div class="paragraph"> 10282<p>The <code>&&</code> symbols separate property values and specify that their order 10283should be preserved. You are advised to use this feature only when the 10284order of properties really matters and not as a convenient shortcut. 10285Using it everywhere might negatively affect performance.</p> 10286</div> 10287</div> 10288<div class="sect2"> 10289<h3 id="bbv2.faq.liborder"><a class="anchor" href="#bbv2.faq.liborder"></a>8.5. How to control the library linking order on Unix?</h3> 10290<div class="paragraph"> 10291<p>On Unix-like operating systems, the order in which static libraries are 10292specified when invoking the linker is important, because by default, the 10293linker uses one pass though the libraries list. Passing the libraries in 10294the incorrect order will lead to a link error. Further, this behavior 10295is often used to make one library override symbols from another. So, 10296sometimes it is necessary to force specific library linking order.</p> 10297</div> 10298<div class="paragraph"> 10299<p>B2 tries to automatically compute the right order. The primary 10300rule is that if library <code>a</code> "uses" library <code>b</code>, then library <code>a</code> will 10301appear on the command line before library <code>b</code>. Library <code>a</code> is considered 10302to use <code>b</code> if <code>b</code> is present either in the <code>a</code> library’s sources or its 10303usage is listed in its requirements. To explicitly specify the <code>use</code> 10304relationship one can use the <code><use></code> feature. For example, both of the 10305following lines will cause <code>a</code> to appear before <code>b</code> on the command line:</p> 10306</div> 10307<div class="listingblock"> 10308<div class="content"> 10309<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-nb">lib</span><span class="tok-w"> </span>a<span class="tok-w"> </span>:<span class="tok-w"> </span>a.cpp<span class="tok-w"> </span>b<span class="tok-w"> </span>;<span class="tok-w"></span> 10310<span class="tok-nb">lib</span><span class="tok-w"> </span>a<span class="tok-w"> </span>:<span class="tok-w"> </span>a.cpp<span class="tok-w"> </span>:<span class="tok-w"> </span><span class="tok-na"><use></span>b<span class="tok-w"> </span>;<span class="tok-w"></span></code></pre> 10311</div> 10312</div> 10313<div class="paragraph"> 10314<p>The same approach works for searched libraries as well:</p> 10315</div> 10316<div class="listingblock"> 10317<div class="content"> 10318<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-nb">lib</span><span class="tok-w"> </span>z<span class="tok-w"> </span>;<span class="tok-w"></span> 10319<span class="tok-nb">lib</span><span class="tok-w"> </span>png<span class="tok-w"> </span>:<span class="tok-w"> </span>:<span class="tok-w"> </span><span class="tok-na"><use></span>z<span class="tok-w"> </span>;<span class="tok-w"></span> 10320<span class="tok-nb">exe</span><span class="tok-w"> </span>viewer<span class="tok-w"> </span>:<span class="tok-w"> </span>viewer<span class="tok-w"> </span>png<span class="tok-w"> </span>z<span class="tok-w"> </span>;<span class="tok-w"></span></code></pre> 10321</div> 10322</div> 10323</div> 10324<div class="sect2"> 10325<h3 id="bbv2.faq.external"><a class="anchor" href="#bbv2.faq.external"></a>8.6. Can I get capture external program output using a Boost.Jam variable?</h3> 10326<div class="paragraph"> 10327<p>The <code>SHELL</code> builtin rule may be used for this purpose:</p> 10328</div> 10329<div class="listingblock"> 10330<div class="content"> 10331<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-k">local</span><span class="tok-w"> </span>gtk_includes<span class="tok-w"> </span>=<span class="tok-w"> </span>[<span class="tok-w"> </span><span class="tok-nb">SHELL</span><span class="tok-w"> </span>"gtk-config<span class="tok-w"> </span>--cflags"<span class="tok-w"> </span>]<span class="tok-w"> </span>;<span class="tok-w"></span></code></pre> 10332</div> 10333</div> 10334</div> 10335<div class="sect2"> 10336<h3 id="bbv2.faq.projectroot"><a class="anchor" href="#bbv2.faq.projectroot"></a>8.7. How to get the project root (a.k.a. Jamroot) location?</h3> 10337<div class="paragraph"> 10338<p>You might want to use your project’s root location in your Jamfiles. To 10339access it just declare a path constant in your <code>Jamroot.jam</code> file using:</p> 10340</div> 10341<div class="listingblock"> 10342<div class="content"> 10343<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-nb">path-constant</span><span class="tok-w"> </span>TOP<span class="tok-w"> </span>:<span class="tok-w"> </span>.<span class="tok-w"> </span>;<span class="tok-w"></span></code></pre> 10344</div> 10345</div> 10346<div class="paragraph"> 10347<p>After that, the <code>TOP</code> variable can be used in every Jamfile.</p> 10348</div> 10349</div> 10350<div class="sect2"> 10351<h3 id="bbv2.faq.flags"><a class="anchor" href="#bbv2.faq.flags"></a>8.8. How to change compilation flags for one file?</h3> 10352<div class="paragraph"> 10353<p>If one file must be compiled with special options, you need to 10354explicitly declare an <code>obj</code> target for that file and then use that 10355target in your <code>exe</code> or <code>lib</code> target:</p> 10356</div> 10357<div class="listingblock"> 10358<div class="content"> 10359<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-nb">exe</span><span class="tok-w"> </span>a<span class="tok-w"> </span>:<span class="tok-w"> </span>a.cpp<span class="tok-w"> </span>b<span class="tok-w"> </span>;<span class="tok-w"></span> 10360<span class="tok-nb">obj</span><span class="tok-w"> </span>b<span class="tok-w"> </span>:<span class="tok-w"> </span>b.cpp<span class="tok-w"> </span>:<span class="tok-w"> </span><span class="tok-na"><optimization></span>off<span class="tok-w"> </span>;<span class="tok-w"></span></code></pre> 10361</div> 10362</div> 10363<div class="paragraph"> 10364<p>Of course you can use other properties, for example to specify specific 10365C/C++ compiler options:</p> 10366</div> 10367<div class="listingblock"> 10368<div class="content"> 10369<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-nb">exe</span><span class="tok-w"> </span>a<span class="tok-w"> </span>:<span class="tok-w"> </span>a.cpp<span class="tok-w"> </span>b<span class="tok-w"> </span>;<span class="tok-w"></span> 10370<span class="tok-nb">obj</span><span class="tok-w"> </span>b<span class="tok-w"> </span>:<span class="tok-w"> </span>b.cpp<span class="tok-w"> </span>:<span class="tok-w"> </span><span class="tok-na"><cflags></span>-g<span class="tok-w"> </span>;<span class="tok-w"></span></code></pre> 10371</div> 10372</div> 10373<div class="paragraph"> 10374<p>You can also use <a href="#bbv2.tutorial.conditions">conditional properties</a> 10375for finer control:</p> 10376</div> 10377<div class="listingblock"> 10378<div class="content"> 10379<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-nb">exe</span><span class="tok-w"> </span>a<span class="tok-w"> </span>:<span class="tok-w"> </span>a.cpp<span class="tok-w"> </span>b<span class="tok-w"> </span>;<span class="tok-w"></span> 10380<span class="tok-nb">obj</span><span class="tok-w"> </span>b<span class="tok-w"> </span>:<span class="tok-w"> </span>b.cpp<span class="tok-w"> </span>:<span class="tok-w"> </span><span class="tok-na"><variant></span>release:<span class="tok-na"><optimization></span>off<span class="tok-w"> </span>;<span class="tok-w"></span></code></pre> 10381</div> 10382</div> 10383</div> 10384<div class="sect2"> 10385<h3 id="bbv2.faq.dll-path"><a class="anchor" href="#bbv2.faq.dll-path"></a>8.9. Why are the <code>dll-path</code> and <code>hardcode-dll-paths</code> properties useful?</h3> 10386<div class="admonitionblock note"> 10387<table> 10388<tr> 10389<td class="icon"> 10390<div class="title">ℹ</div> 10391</td> 10392<td class="content"> 10393This entry is specific to Unix systems. 10394</td> 10395</tr> 10396</table> 10397</div> 10398<div class="paragraph"> 10399<p>Before answering the questions, let us recall a few points about shared 10400libraries. Shared libraries can be used by several applications, or 10401other libraries, without physically including the library in the 10402application which can greatly decrease the total application size. It is 10403also possible to upgrade a shared library when the application is 10404already installed.</p> 10405</div> 10406<div class="paragraph"> 10407<p>However, in order for application depending on shared libraries to be 10408started the OS may need to find the shared library when the application 10409is started. The dynamic linker will search in a system-defined list of 10410paths, load the library and resolve the symbols. Which means that you 10411should either change the system-defined list, given by the 10412<code>LD_LIBRARY_PATH</code> environment variable, or install the libraries to a 10413system location. This can be inconvenient when developing, since the 10414libraries are not yet ready to be installed, and cluttering system paths 10415may be undesirable. Luckily, on Unix there is another way.</p> 10416</div> 10417<div class="paragraph"> 10418<p>An executable can include a list of additional library paths, which will 10419be searched before system paths. This is excellent for development 10420because the build system knows the paths to all libraries and can 10421include them in the executables. That is done when the 10422<code>hardcode-dll-paths</code> feature has the <code>true</code> value, which is the default. 10423When the executables should be installed, the story is different.</p> 10424</div> 10425<div class="paragraph"> 10426<p>Obviously, installed executable should not contain hardcoded paths to 10427your development tree. (The <code>install</code> rule explicitly disables the 10428<code>hardcode-dll-paths</code> feature for that reason.) However, you can use the 10429<code>dll-path</code> feature to add explicit paths manually. For example:</p> 10430</div> 10431<div class="listingblock"> 10432<div class="content"> 10433<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-nb">install</span><span class="tok-w"> </span>installed<span class="tok-w"> </span>:<span class="tok-w"> </span>application<span class="tok-w"> </span>:<span class="tok-w"> </span><span class="tok-na"><dll-path></span>/usr/lib/snake<span class="tok-w"></span> 10434<span class="tok-w"> </span><span class="tok-na"><location></span>/usr/bin<span class="tok-w"> </span>;<span class="tok-w"></span></code></pre> 10435</div> 10436</div> 10437<div class="paragraph"> 10438<p>will allow the application to find libraries placed in the 10439<code>/usr/lib/snake</code> directory.</p> 10440</div> 10441<div class="paragraph"> 10442<p>If you install libraries to a nonstandard location and add an explicit 10443path, you get more control over libraries which will be used. A library 10444of the same name in a system location will not be inadvertently used. If 10445you install libraries to a system location and do not add any paths, the 10446system administrator will have more control. Each library can be 10447individually upgraded, and all applications will use the new library.</p> 10448</div> 10449<div class="paragraph"> 10450<p>Which approach is best depends on your situation. If the libraries are 10451relatively standalone and can be used by third party applications, they 10452should be installed in the system location. If you have lots of 10453libraries which can be used only by your application, it makes sense to 10454install them to a nonstandard directory and add an explicit path, like 10455the example above shows. Please also note that guidelines for different 10456systems differ in this respect. For example, the Debian GNU guidelines 10457prohibit any additional search paths while Solaris guidelines suggest 10458that they should always be used.</p> 10459</div> 10460</div> 10461<div class="sect2"> 10462<h3 id="bbv2.recipes.site-config"><a class="anchor" href="#bbv2.recipes.site-config"></a>8.10. Targets in site-config.jam</h3> 10463<div class="paragraph"> 10464<p>It is desirable to declare standard libraries available on a given 10465system. Putting target declaration in a specific project’s Jamfile is 10466not really good, since locations of the libraries can vary between 10467different development machines and then such declarations would need to 10468be duplicated in different projects. The solution is to declare the 10469targets in B2’s <code>site-config.jam</code> configuration file:</p> 10470</div> 10471<div class="listingblock"> 10472<div class="content"> 10473<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-nb">project</span><span class="tok-w"> </span>site-config<span class="tok-w"> </span>;<span class="tok-w"></span> 10474<span class="tok-nb">lib</span><span class="tok-w"> </span>zlib<span class="tok-w"> </span>:<span class="tok-w"> </span>:<span class="tok-w"> </span><span class="tok-na"><name></span>z<span class="tok-w"> </span>;<span class="tok-w"></span></code></pre> 10475</div> 10476</div> 10477<div class="paragraph"> 10478<p>Recall that both <code>site-config.jam</code> and <code>user-config.jam</code> are projects, 10479and everything you can do in a Jamfile you can do in those files as 10480well. So, you declare a project id and a target. Now, one can write:</p> 10481</div> 10482<div class="listingblock"> 10483<div class="content"> 10484<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-nb">exe</span><span class="tok-w"> </span>hello<span class="tok-w"> </span>:<span class="tok-w"> </span>hello.cpp<span class="tok-w"> </span>/site-config//zlib<span class="tok-w"> </span>;<span class="tok-w"></span></code></pre> 10485</div> 10486</div> 10487<div class="paragraph"> 10488<p>in any Jamfile.</p> 10489</div> 10490</div> 10491<div class="sect2"> 10492<h3 id="bbv2.faq.header-only-libraries"><a class="anchor" href="#bbv2.faq.header-only-libraries"></a>8.11. Header-only libraries</h3> 10493<div class="paragraph"> 10494<p>In modern C++, libraries often consist of just header files, without any 10495source files to compile. To use such libraries, you need to add proper 10496includes and possibly defines to your project. But with a large number 10497of external libraries it becomes problematic to remember which libraries 10498are header only, and which ones you have to link to. However, with 10499B2 a header-only library can be declared as B2 target 10500and all dependents can use such library without having to remember 10501whether it is a header-only library or not.</p> 10502</div> 10503<div class="paragraph"> 10504<p>Header-only libraries may be declared using the <code>alias</code> rule, specifying 10505their include path as a part of its usage requirements, for example:</p> 10506</div> 10507<div class="listingblock"> 10508<div class="content"> 10509<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-nb">alias</span><span class="tok-w"> </span>my-lib<span class="tok-w"></span> 10510<span class="tok-w"> </span>:<span class="tok-w"> </span><span class="tok-c1"># no sources</span> 10511<span class="tok-w"> </span>:<span class="tok-w"> </span><span class="tok-c1"># no build requirements</span> 10512<span class="tok-w"> </span>:<span class="tok-w"> </span><span class="tok-c1"># no default build</span> 10513<span class="tok-w"> </span>:<span class="tok-w"> </span><span class="tok-na"><include></span>whatever<span class="tok-w"> </span>;<span class="tok-w"></span></code></pre> 10514</div> 10515</div> 10516<div class="paragraph"> 10517<p>The includes specified in usage requirements of <code>my-lib</code> are 10518automatically added to all of its dependents build properties. The 10519dependents need not care if <code>my-lib</code> is a header-only or not, and it is 10520possible to later make <code>my-lib</code> into a regular compiled library without 10521having to add the includes to its dependents declarations.</p> 10522</div> 10523<div class="paragraph"> 10524<p>If you already have proper usage requirements declared for a project 10525where a header-only library is defined, you do not need to duplicate 10526them for the <code>alias</code> target:</p> 10527</div> 10528<div class="listingblock"> 10529<div class="content"> 10530<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-nb">project</span><span class="tok-w"> </span>my<span class="tok-w"> </span>:<span class="tok-w"> </span>usage-requirements<span class="tok-w"> </span><span class="tok-na"><include></span>whatever<span class="tok-w"> </span>;<span class="tok-w"></span> 10531<span class="tok-nb">alias</span><span class="tok-w"> </span>mylib<span class="tok-w"> </span>;<span class="tok-w"></span></code></pre> 10532</div> 10533</div> 10534</div> 10535<div class="sect2"> 10536<h3 id="bbv2.faq.names"><a class="anchor" href="#bbv2.faq.names"></a>8.12. What is the difference between B2, <code>b2</code>, <code>bjam</code> and Perforce Jam?</h3> 10537<div class="paragraph"> 10538<p>B2 is the name of the complete build system. The executable 10539that runs it is <code>b2</code>. That executable is written in C and implements 10540performance-critical algorithms, like traversal of dependency graph and 10541executing commands. It also implements an interpreted language used to 10542implement the rest of B2. This executable is formally called 10543"B2 engine".</p> 10544</div> 10545<div class="paragraph"> 10546<p>The B2 engine is derived from an earlier build tool called 10547Perforce Jam. Originally, there were just minor changes, and the 10548filename was <code>bjam</code>. Later on, with more and more changes, the 10549similarity of names became a disservice to users, and as of Boost 105501.47.0, the official name of the executable was changed to <code>b2</code>. A copy 10551named <code>bjam</code> is still created for compatibility, but you are encouraged 10552to use the new name in all cases.</p> 10553</div> 10554<div class="paragraph"> 10555<p>Perforce Jam was an important foundation, and we gratefully acknowledge 10556its influence, but for users today, these tools share only some basics 10557of the interpreted language.</p> 10558</div> 10559</div> 10560</div> 10561</div> 10562<div class="sect1"> 10563<h2 id="_extra_tools"><a class="anchor" href="#_extra_tools"></a>9. Extra Tools</h2> 10564<div class="sectionbody"> 10565<div class="sect2"> 10566<h3 id="_documentation_tools_2"><a class="anchor" href="#_documentation_tools_2"></a>9.1. Documentation Tools</h3> 10567<div class="sect3"> 10568<h4 id="_asciidoctor"><a class="anchor" href="#_asciidoctor"></a>9.1.1. Asciidoctor</h4> 10569<div class="paragraph"> 10570<p>The asciidoctor tool converts the ascidoc documentation format to various 10571backend formats for either viewing or further processing by documentation 10572tools. This tool supports the baseline asciidoctor distribution (i.e. the 10573Ruby based tool).</p> 10574</div> 10575<div class="sect4"> 10576<h5 id="_feature_asciidoctor_attribute"><a class="anchor" href="#_feature_asciidoctor_attribute"></a>Feature: <code>asciidoctor-attribute</code></h5> 10577<div class="paragraph"> 10578<p>Defines arbitrary asciidoctor attributes. The value of the feature should be 10579specified with the CLI syntax for attributes. 10580For example to use as a target requirement:</p> 10581</div> 10582<div class="listingblock"> 10583<div class="content"> 10584<pre class="pygments highlight"><code data-lang="jam"><span></span>html<span class="tok-w"> </span>example<span class="tok-w"> </span>:<span class="tok-w"> </span>example.adoc<span class="tok-w"> </span>:<span class="tok-w"></span> 10585<span class="tok-w"> </span><span class="tok-na"><asciidoctor-attribute></span>idprefix=ex<span class="tok-w"> </span>;<span class="tok-w"></span></code></pre> 10586</div> 10587</div> 10588<div class="paragraph"> 10589<p>This is a <code>free</code> feature and is not <code>propagated</code>. I.e. it applies only to the 10590target it’s specified on.</p> 10591</div> 10592</div> 10593<div class="sect4"> 10594<h5 id="_feature_asciidoctor_doctype"><a class="anchor" href="#_feature_asciidoctor_doctype"></a>Feature: <code>asciidoctor-doctype</code></h5> 10595<div class="paragraph"> 10596<p>Specifies the <code>doctype</code> to use for generating the output format. Allowed 10597<code>doctype</code> values are: <code>article</code>, <code>book</code>, <code>manpage</code>, and <code>inline</code>.</p> 10598</div> 10599</div> 10600<div class="sect4"> 10601<h5 id="_feature_asciidoctor_backend"><a class="anchor" href="#_feature_asciidoctor_backend"></a>Feature: <code>asciidoctor-backend</code></h5> 10602<div class="paragraph"> 10603<p>Specifies the <code>backend</code> to use to produce output from the source asciidoc. 10604This feature is automatically applied to fit the build target type. For 10605example, when specifying an <code>html</code> target for an <code>asciidoc</code> source:</p> 10606</div> 10607<div class="listingblock"> 10608<div class="content"> 10609<pre class="pygments highlight"><code data-lang="jam"><span></span>html<span class="tok-w"> </span>example<span class="tok-w"> </span>:<span class="tok-w"> </span>example.adoc<span class="tok-w"> </span>;<span class="tok-w"></span></code></pre> 10610</div> 10611</div> 10612<div class="paragraph"> 10613<p>The target will by default acquire the <code><asciidoctor-backend>html5</code> 10614requirement. The default for each target type are:</p> 10615</div> 10616<div class="ulist"> 10617<ul> 10618<li> 10619<p><code>html</code>: <code><asciidoctor-backend>html5</code></p> 10620</li> 10621<li> 10622<p><code>docbook</code>: <code><asciidoctor-backend>docbook45</code></p> 10623</li> 10624<li> 10625<p><code>man</code>: <code><asciidoctor-backend>manpage</code></p> 10626</li> 10627<li> 10628<p><code>pdf</code>: <code><asciidoctor-backend>pdf</code></p> 10629</li> 10630</ul> 10631</div> 10632<div class="paragraph"> 10633<p>To override the defaults you specify it as a requirement on the target:</p> 10634</div> 10635<div class="listingblock"> 10636<div class="content"> 10637<pre class="pygments highlight"><code data-lang="jam"><span></span>docbook<span class="tok-w"> </span>example<span class="tok-w"> </span>:<span class="tok-w"> </span>example.adoc<span class="tok-w"> </span>:<span class="tok-w"></span> 10638<span class="tok-w"> </span><span class="tok-na"><asciidoctor-backend></span>docbook5<span class="tok-w"> </span>;<span class="tok-w"></span></code></pre> 10639</div> 10640</div> 10641<div class="paragraph"> 10642<p>Allowed <code>backend</code> values are: <code>html5</code>, <code>docbook45</code>, <code>docbook5</code>, <code>pdf</code>.</p> 10643</div> 10644</div> 10645<div class="sect4"> 10646<h5 id="_initialization"><a class="anchor" href="#_initialization"></a>Initialization</h5> 10647<div class="paragraph"> 10648<p>To use the <code>asciidoctor</code> tool you need to declare it in a configuration file 10649with the <code>using</code> rule. The initialization takes the following arguments:</p> 10650</div> 10651<div class="ulist"> 10652<ul> 10653<li> 10654<p><code>command</code>: The command, with any extra arguments, to execute.</p> 10655</li> 10656</ul> 10657</div> 10658<div class="paragraph"> 10659<p>For example you could insert the following in your <code>user-config.jam</code>:</p> 10660</div> 10661<div class="listingblock"> 10662<div class="content"> 10663<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-nb">using</span><span class="tok-w"> </span>asciidoctor<span class="tok-w"> </span>:<span class="tok-w"> </span>"/usr/local/bin/asciidoctor"<span class="tok-w"> </span>;<span class="tok-w"></span></code></pre> 10664</div> 10665</div> 10666<div class="paragraph"> 10667<p>If no <code>command</code> is given it defaults to just <code>asciidoctor</code> with assumption 10668that the <code>asciidoctor</code> is available in the search <code>PATH</code>.</p> 10669</div> 10670</div> 10671</div> 10672</div> 10673<div class="sect2"> 10674<h3 id="_miscellaneous_tools"><a class="anchor" href="#_miscellaneous_tools"></a>9.2. Miscellaneous Tools</h3> 10675<div class="sect3"> 10676<h4 id="_pkg_config"><a class="anchor" href="#_pkg_config"></a>9.2.1. pkg-config</h4> 10677<div class="paragraph"> 10678<p>The <strong>pkg-config</strong> program is used to retrieve information about installed 10679libraries in the system. It retrieves information about packages from special 10680metadata files. These files are named after the package, and have a <code>.pc</code> 10681extension. The package name specified to <strong>pkg-config</strong> is defined to be the name 10682of the metadata file, minus the <code>.pc</code> extension.</p> 10683</div> 10684<div class="sect4"> 10685<h5 id="_feature_pkg_config"><a class="anchor" href="#_feature_pkg_config"></a>Feature: <code>pkg-config</code></h5> 10686<div class="paragraph"> 10687<p>Selects one of the initialized <code>pkg-config</code> configurations. This feature is 10688<code>propagated</code> to dependencies. Its use is dicussed in 10689section <a href="#pkg-config-init">[pkg-config-init]</a>.</p> 10690</div> 10691</div> 10692<div class="sect4"> 10693<h5 id="_feature_pkg_config_define"><a class="anchor" href="#_feature_pkg_config_define"></a>Feature: <code>pkg-config-define</code></h5> 10694<div class="paragraph"> 10695<p>This <code>free</code> feature adds a variable assignment to pkg-config invocation. For 10696example,</p> 10697</div> 10698<div class="listingblock"> 10699<div class="content"> 10700<pre class="pygments highlight"><code data-lang="jam"><span></span>pkg-config.import<span class="tok-w"> </span>mypackage<span class="tok-w"> </span>:<span class="tok-w"> </span>requirements<span class="tok-w"> </span><span class="tok-na"><pkg-config-define></span>key=value<span class="tok-w"> </span>;<span class="tok-w"></span></code></pre> 10701</div> 10702</div> 10703<div class="paragraph"> 10704<p>is equivalent to invoking on the comand line</p> 10705</div> 10706<div class="listingblock"> 10707<div class="content"> 10708<pre class="pygments highlight"><code data-lang="shell"><span></span>pkg-config --define-variable<span class="tok-o">=</span><span class="tok-nv">key</span><span class="tok-o">=</span>value mypackage <span class="tok-p">;</span></code></pre> 10709</div> 10710</div> 10711</div> 10712<div class="sect4"> 10713<h5 id="_rule_import"><a class="anchor" href="#_rule_import"></a>Rule: <code>import</code></h5> 10714<div class="paragraph"> 10715<p>Main target rule that imports a <strong>pkg-config</strong> package. When its consumer targets 10716are built, <strong>pkg-config</strong> command will be invoked with arguments that depend on 10717current property set. The features that have an effect are:</p> 10718</div> 10719<div class="ulist"> 10720<ul> 10721<li> 10722<p><code><pkg-config-define></code>: adds a <code>--define-variable</code> argument;</p> 10723</li> 10724<li> 10725<p><code><link></code>: adds <code>--static</code> argument when <code><link>static</code>;</p> 10726</li> 10727<li> 10728<p><code><link></code>: adds <code>--static</code> argument when <code><link>static</code>;</p> 10729</li> 10730<li> 10731<p><code><name></code>: specifies package name (target name is used instead if the property 10732is not present);</p> 10733</li> 10734<li> 10735<p><code><version></code>: specifies package version range, can be used multiple times and 10736should be a dot-separated sequence of numbers optionally prefixed with <code>=</code>, 10737<code><</code>, <code>></code>, <code>⇐</code> or <code>>=</code>.</p> 10738</li> 10739</ul> 10740</div> 10741<div class="paragraph"> 10742<p>Example:</p> 10743</div> 10744<div class="listingblock"> 10745<div class="content"> 10746<pre class="pygments highlight"><code data-lang="jam"><span></span>pkg-config.import<span class="tok-w"> </span>my-package<span class="tok-w"></span> 10747<span class="tok-w"> </span>:<span class="tok-w"> </span>requirements<span class="tok-w"> </span><span class="tok-na"><name></span>my_package<span class="tok-w"> </span><span class="tok-na"><version><4</span><span class="tok-err"> </span><span class="tok-na"><version>></span>=3.1<span class="tok-w"> </span>;<span class="tok-w"></span></code></pre> 10748</div> 10749</div> 10750</div> 10751<div class="sect4"> 10752<h5 id="_initialization_pkg_config_init"><a class="anchor" href="#_initialization_pkg_config_init"></a>Initialization [[ pkg-config-init ]]</h5> 10753<div class="paragraph"> 10754<p>To use the <code>pkg-config</code> tool you need to declare it in a configuration file 10755with the <code>using</code> rule:</p> 10756</div> 10757<div class="listingblock"> 10758<div class="content"> 10759<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-nb">using</span><span class="tok-w"> </span>pkg-config<span class="tok-w"> </span>:<span class="tok-w"> </span>[config]<span class="tok-w"> </span>:<span class="tok-w"> </span>[command]<span class="tok-w"> </span>...<span class="tok-w"> </span>:<span class="tok-w"> </span>[<span class="tok-w"> </span>options<span class="tok-w"> </span>]<span class="tok-w"> </span>...<span class="tok-w"> </span>;<span class="tok-w"></span></code></pre> 10760</div> 10761</div> 10762<div class="ulist"> 10763<ul> 10764<li> 10765<p><code>config</code>: the name of initialized configuration. The name can be omitted, in 10766which case the configuration will become the default one.</p> 10767</li> 10768<li> 10769<p><code>command</code>: the command, with any extra arguments, to execute. If no command 10770is given, first <code>PKG_CONFIG</code> environment variable is checked, and if its 10771empty the string <code>pkg-config</code> is used.</p> 10772</li> 10773<li> 10774<p><code>options</code>: options that modify <code>pkg-config</code> behavior. Allowed options are:</p> 10775</li> 10776<li> 10777<p><code><path></code>: sets <code>PKG_CONFIG_PATH</code> environment variable; 10778multiple occurences are allowed.</p> 10779</li> 10780<li> 10781<p><code><libdir></code>: sets <code>PKG_CONFIG_LIBDIR</code> environment variable; 10782multiple occurences are allowed.</p> 10783</li> 10784<li> 10785<p><code><allow-system-cflags></code>: sets <code>PKG_CONFIG_ALLOW_SYSTEM_CFLAGS</code> 10786environment variable; multiple occurences are allowed.</p> 10787</li> 10788<li> 10789<p><code><allow-system-libs></code>: sets <code>PKG_CONFIG_ALLOW_SYSTEM_LIBS</code> 10790environment variable; multiple occurences are allowed.</p> 10791</li> 10792<li> 10793<p><code><sysroot></code>: sets <code>PKG_CONFIG_SYSROOT_DIR</code> environment variable; 10794multiple occurences are allowed.</p> 10795</li> 10796<li> 10797<p><code><variable></code>: adds a variable definition argument to command invocation; 10798multiple occurences are allowed.</p> 10799</li> 10800</ul> 10801</div> 10802</div> 10803<div class="sect4"> 10804<h5 id="_class_pkg_config_target"><a class="anchor" href="#_class_pkg_config_target"></a>Class <code>pkg-config-target</code></h5> 10805<div class="listingblock"> 10806<div class="content"> 10807<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-k">class</span><span class="tok-w"> </span><span class="tok-nc">pkg-config-target</span><span class="tok-w"> </span><span class="tok-p">:</span><span class="tok-w"> </span><span class="tok-nc">alias-target-class</span><span class="tok-w"> </span>{<span class="tok-w"></span> 10808<span class="tok-w"> </span><span class="tok-k">rule</span><span class="tok-w"> </span><span class="tok-nf">construct</span><span class="tok-w"> </span><span class="tok-p">(</span><span class="tok-w"> </span><span class="tok-nv">name</span><span class="tok-w"> </span><span class="tok-p">:</span><span class="tok-w"> </span><span class="tok-nv">sources</span><span class="tok-w"> </span><span class="tok-p">*</span><span class="tok-w"> </span><span class="tok-p">:</span><span class="tok-w"> </span><span class="tok-nv">property-set</span><span class="tok-w"> </span><span class="tok-p">)</span><span class="tok-w"></span> 10809<span class="tok-w"> </span><span class="tok-k">rule</span><span class="tok-w"> </span><span class="tok-nf">version</span><span class="tok-w"> </span><span class="tok-p">(</span><span class="tok-w"> </span><span class="tok-nv">property-set</span><span class="tok-w"> </span><span class="tok-p">)</span><span class="tok-w"></span> 10810<span class="tok-w"> </span><span class="tok-k">rule</span><span class="tok-w"> </span><span class="tok-nf">variable</span><span class="tok-w"> </span><span class="tok-p">(</span><span class="tok-w"> </span><span class="tok-nv">name</span><span class="tok-w"> </span><span class="tok-p">:</span><span class="tok-w"> </span><span class="tok-nv">property-set</span><span class="tok-w"> </span><span class="tok-p">)</span><span class="tok-w"></span> 10811}<span class="tok-w"></span></code></pre> 10812</div> 10813</div> 10814<div class="paragraph"> 10815<p>The class of objects returned by <code>import</code> rule. The objects themselves could be 10816useful in situations that require more complicated logic for consuming a 10817package. See <a href="#pkg-config-tips">Tips</a> for examples.</p> 10818</div> 10819<div class="olist arabic"> 10820<ol class="arabic"> 10821<li> 10822<p><code>rule construct ( name : sources * : property-set )</code> 10823Overrides <code>alias-target.construct</code>.</p> 10824</li> 10825<li> 10826<p><code>rule version ( property-set )</code> 10827Returns the package’s version, in the context of <code>property-set</code>.</p> 10828</li> 10829<li> 10830<p><code>rule variable ( name : property-set )</code> 10831Returns the value of variable <code>name</code> in the package, in the context of 10832<code>property-set</code>.</p> 10833</li> 10834</ol> 10835</div> 10836</div> 10837<div class="sect4"> 10838<h5 id="pkg-config-tips"><a class="anchor" href="#pkg-config-tips"></a>Tips</h5> 10839<div class="sect5"> 10840<h6 id="_using_several_configurations"><a class="anchor" href="#_using_several_configurations"></a>Using several configurations</h6> 10841<div class="paragraph"> 10842<p>Suppose, you have 2 collections of <code>.pc</code> files: one for platform A, and another 10843for platform B. You can initialize 2 configurations of <code>pkg-config</code> tool each 10844corresponding to specific collection:</p> 10845</div> 10846<div class="listingblock"> 10847<div class="content"> 10848<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-nb">using</span><span class="tok-w"> </span>pkg-config<span class="tok-w"> </span>:<span class="tok-w"> </span>A<span class="tok-w"> </span>:<span class="tok-w"> </span>:<span class="tok-w"> </span><span class="tok-na"><libdir></span>path/to/collection/A<span class="tok-w"> </span>;<span class="tok-w"></span> 10849<span class="tok-nb">using</span><span class="tok-w"> </span>pkg-config<span class="tok-w"> </span>:<span class="tok-w"> </span>B<span class="tok-w"> </span>:<span class="tok-w"> </span>:<span class="tok-w"> </span><span class="tok-na"><libdir></span>path/to/collection/B<span class="tok-w"> </span>;<span class="tok-w"></span></code></pre> 10850</div> 10851</div> 10852<div class="paragraph"> 10853<p>Then, you can specify that builds for platform A should use configuration A, 10854while builds for B should use configuration B:</p> 10855</div> 10856<div class="listingblock"> 10857<div class="content"> 10858<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-nb">project</span><span class="tok-w"></span> 10859<span class="tok-w"> </span>:<span class="tok-w"> </span>requirements<span class="tok-w"></span> 10860<span class="tok-w"> </span><span class="tok-na"><target-os></span>A-os,<span class="tok-na"><architecture></span>A-arch:<span class="tok-na"><pkg-config></span>A<span class="tok-w"></span> 10861<span class="tok-w"> </span><span class="tok-na"><target-os></span>B-os,<span class="tok-na"><architecture></span>B-arch:<span class="tok-na"><pkg-config></span>B<span class="tok-w"></span> 10862<span class="tok-w"> </span>;<span class="tok-w"></span></code></pre> 10863</div> 10864</div> 10865<div class="paragraph"> 10866<p>Thanks to the fact, that <code>project-config</code>, <code>user-config</code> and <code>site-config</code> 10867modules are parents of jamroot module, you can put it in any of those files.o</p> 10868</div> 10869</div> 10870<div class="sect5"> 10871<h6 id="_choosing_the_package_name_based_on_the_property_set"><a class="anchor" href="#_choosing_the_package_name_based_on_the_property_set"></a>Choosing the package name based on the property set</h6> 10872<div class="paragraph"> 10873<p>Since a file for a package should be named after the package suffixed with 10874<code>.pc</code>, some projects came up with naming schemes in order to allow simultaneous 10875installation of several major versions or build variants. In order to pick the 10876specific name corresponding to the build request you can use <code><conditional></code> 10877property in requirements:</p> 10878</div> 10879<div class="listingblock"> 10880<div class="content"> 10881<pre class="pygments highlight"><code data-lang="jam"><span></span>pkg-config.import<span class="tok-w"> </span>mypackage<span class="tok-w"> </span>:<span class="tok-w"> </span>requirements<span class="tok-w"> </span><span class="tok-na"><conditional></span>@infer-name<span class="tok-w"> </span>;<span class="tok-w"></span> 10882 10883<span class="tok-k">rule</span><span class="tok-w"> </span><span class="tok-nf">infer-name</span><span class="tok-w"> </span><span class="tok-p">(</span><span class="tok-w"> </span><span class="tok-nv">properties</span><span class="tok-w"> </span><span class="tok-p">*</span><span class="tok-w"> </span><span class="tok-p">)</span><span class="tok-w"></span> 10884{<span class="tok-w"></span> 10885<span class="tok-w"> </span><span class="tok-k">local</span><span class="tok-w"> </span>name<span class="tok-w"> </span>=<span class="tok-w"> </span>mypackage<span class="tok-w"> </span>;<span class="tok-w"></span> 10886<span class="tok-w"> </span><span class="tok-k">local</span><span class="tok-w"> </span>variant<span class="tok-w"> </span>=<span class="tok-w"> </span>[<span class="tok-w"> </span>property.select<span class="tok-w"> </span><span class="tok-na"><variant></span><span class="tok-w"> </span>:<span class="tok-w"> </span><span class="tok-si">$(properties)</span><span class="tok-w"> </span>]<span class="tok-w"> </span>;<span class="tok-w"></span> 10887<span class="tok-w"> </span><span class="tok-k">if</span><span class="tok-w"> </span><span class="tok-si">$(variant)</span><span class="tok-w"> </span>=<span class="tok-w"> </span>debug<span class="tok-w"></span> 10888<span class="tok-w"> </span>{<span class="tok-w"></span> 10889<span class="tok-w"> </span>name<span class="tok-w"> </span>+=<span class="tok-w"> </span>-d<span class="tok-w"> </span>;<span class="tok-w"></span> 10890<span class="tok-w"> </span>}<span class="tok-w"></span> 10891<span class="tok-w"> </span><span class="tok-k">return</span><span class="tok-w"> </span><span class="tok-na"><name></span><span class="tok-si">$(name)</span><span class="tok-w"> </span>;<span class="tok-w"></span> 10892}<span class="tok-w"></span></code></pre> 10893</div> 10894</div> 10895<div class="paragraph"> 10896<p>The <code>common.format-name</code> rule can be very useful in this situation.</p> 10897</div> 10898</div> 10899<div class="sect5"> 10900<h6 id="_modify_usage_requirements_based_on_package_version_or_variable"><a class="anchor" href="#_modify_usage_requirements_based_on_package_version_or_variable"></a>Modify usage requirements based on package version or variable</h6> 10901<div class="paragraph"> 10902<p>Sometimes you need to apply some logic based on package’s version or a 10903variable that it defines. For that you can use <code><conditional></code> property in 10904usage requirements:</p> 10905</div> 10906<div class="listingblock"> 10907<div class="content"> 10908<pre>mypackage = 10909 [ pkg-config.import mypackage : usage-requirements <conditional>@define_ns 10910 ] ; 10911 10912rule extra-props ( properties * ) 10913{ 10914 local ps = [ property-set.create $(properties) ] ; 10915 local prefix = [ $(mypackage).variable name_prefix : $(ps) ] ; 10916 prefix += [ $(mypackage).version $(ps) ] ; 10917 return <define>$(prefix:J=_) ; 10918}</pre> 10919</div> 10920</div> 10921</div> 10922</div> 10923</div> 10924<div class="sect3"> 10925<h4 id="_sass"><a class="anchor" href="#_sass"></a>9.2.2. Sass</h4> 10926<div class="paragraph"> 10927<p>This tool converts SASS and SCSS files into CSS. This tool explicitly supports 10928both the version written in C (sassc) and the original Ruby implementation 10929(scss) but other variants might also work. In addition to tool-specific 10930features, described in this section, the tool recognizes features <code><flags></code> 10931and <code><include></code>.</p> 10932</div> 10933<div class="sect4"> 10934<h5 id="_feature_sass_style"><a class="anchor" href="#_feature_sass_style"></a>Feature: <code>sass-style</code></h5> 10935<div class="paragraph"> 10936<p>Sets the output style. Available values are</p> 10937</div> 10938<div class="ulist"> 10939<ul> 10940<li> 10941<p><code>nested</code>: each property is put on its own line, rules are indented based on 10942how deeply they are nested;</p> 10943</li> 10944<li> 10945<p><code>expanded</code>: each property is put on its own line, rules are not indented;</p> 10946</li> 10947<li> 10948<p><code>compact</code>: each rule is put on a single line, nested rules occupy adjacent 10949lines, while groups of unrelated rules are separated by newlines;</p> 10950</li> 10951<li> 10952<p><code>compressed</code>: takes minimum amount of space: all unnecessary whitespace is 10953removed, property values are compressed to have minimal representation.</p> 10954</li> 10955</ul> 10956</div> 10957<div class="paragraph"> 10958<p>The feature is <code>optional</code> and is not <code>propagated</code> to dependent targets. If no 10959style is specified, then, if property set contains property <code><optimization>on</code>, 10960<code>compressed</code> style is selected. Otherwise, <code>nested</code> style is selected.</p> 10961</div> 10962</div> 10963<div class="sect4"> 10964<h5 id="_feature_sass_line_numbers"><a class="anchor" href="#_feature_sass_line_numbers"></a>Feature: <code>sass-line-numbers</code></h5> 10965<div class="paragraph"> 10966<p>Enables emitting comments showing original line numbers for rules. This can be 10967useful for debugging a stylesheet. Available values are <code>on</code> and <code>off</code>. The 10968feature is <code>optional</code> and is not <code>propagated</code> to dependent targets. If no value 10969for this feature is specified, then one is copied from the feature 10970<code>debug-symbols</code>.</p> 10971</div> 10972</div> 10973<div class="sect4"> 10974<h5 id="_initialization_2"><a class="anchor" href="#_initialization_2"></a>Initialization</h5> 10975<div class="paragraph"> 10976<p>To use the <code>sass</code> tool you need to declare it in a configuration file with the 10977<code>using</code> rule. The initialization takes the following arguments:</p> 10978</div> 10979<div class="ulist"> 10980<ul> 10981<li> 10982<p><code>command</code>: the command, with any extra arguments, to execute.</p> 10983</li> 10984</ul> 10985</div> 10986<div class="paragraph"> 10987<p>For example you could insert the following in your <code>user-config.jam</code>:</p> 10988</div> 10989<div class="listingblock"> 10990<div class="content"> 10991<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-nb">using</span><span class="tok-w"> </span>sass<span class="tok-w"> </span>:<span class="tok-w"> </span>/usr/local/bin/psass<span class="tok-w"> </span>-p2<span class="tok-w"> </span>;<span class="tok-w"> </span><span class="tok-c1"># Perl libsass-based version</span></code></pre> 10992</div> 10993</div> 10994<div class="paragraph"> 10995<p>If no <code>command</code> is given, <code>sassc</code> is tried, after which <code>scss</code> is tried.</p> 10996</div> 10997</div> 10998</div> 10999</div> 11000</div> 11001</div> 11002<div class="sect1"> 11003<h2 id="_examples"><a class="anchor" href="#_examples"></a>10. Examples</h2> 11004<div class="sectionbody"> 11005<div class="sect2"> 11006<h3 id="_introduction"><a class="anchor" href="#_introduction"></a>10.1. Introduction</h3> 11007<div class="paragraph"> 11008<p>Here we include a collection of simple to complex fully working examples of 11009using Boost Build v2 for various tasks. They show the gamut from simple 11010to advanced features. If you find yourself looking at the examples and not 11011finding something you want to see working please post to our support list 11012and we’ll try and come up with a solution and add it here for others to learn 11013from.</p> 11014</div> 11015</div> 11016<div class="sect2"> 11017<h3 id="_hello"><a class="anchor" href="#_hello"></a>10.2. Hello</h3> 11018<div class="paragraph"> 11019<p>This example shows a very basic Boost Build project set up so it compiles a 11020single executable from a single source file:</p> 11021</div> 11022<div class="listingblock"> 11023<div class="title"><code>hello.cpp</code></div> 11024<div class="content"> 11025<pre class="pygments highlight"><code data-lang="cpp"><span></span><span class="tok-cp">#include</span> <span class="tok-cpf"><iostream></span><span class="tok-cp"></span> 11026 11027<span class="tok-kt">int</span> <span class="tok-nf">main</span><span class="tok-p">()</span> 11028<span class="tok-p">{</span> 11029 <span class="tok-n">std</span><span class="tok-o">::</span><span class="tok-n">cout</span> <span class="tok-o"><<</span> <span class="tok-s">"Hello!</span><span class="tok-se">\n</span><span class="tok-s">"</span><span class="tok-p">;</span> 11030 <span class="tok-k">return</span> <span class="tok-mi">1</span><span class="tok-p">;</span> 11031<span class="tok-p">}</span></code></pre> 11032</div> 11033</div> 11034<div class="paragraph"> 11035<p>Our <code>jamroot.jam</code> is minimal and only specifies one <code>exe</code> target for the 11036program:</p> 11037</div> 11038<div class="listingblock"> 11039<div class="title"><code>jamroot.jam</code></div> 11040<div class="content"> 11041<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-nb">exe</span><span class="tok-w"> </span>hello<span class="tok-w"> </span>:<span class="tok-w"> </span>hello.cpp<span class="tok-w"> </span>;<span class="tok-w"></span></code></pre> 11042</div> 11043</div> 11044<div class="paragraph"> 11045<p>Building the example yields:</p> 11046</div> 11047<div class="listingblock"> 11048<div class="content"> 11049<pre class="pygments highlight"><code data-lang="bash"><span></span>> <span class="tok-nb">cd</span> /example/hello 11050> b2 11051...found <span class="tok-m">8</span> targets... 11052...updating <span class="tok-m">4</span> targets... 11053common.mkdir bin/clang-darwin-4.2.1 11054common.mkdir bin/clang-darwin-4.2.1/debug 11055clang-darwin.compile.c++ bin/clang-darwin-4.2.1/debug/hello.o 11056clang-darwin.link bin/clang-darwin-4.2.1/debug/hello 11057...updated <span class="tok-m">4</span> targets... 11058> bin/clang-darwin-4.2.1/debug/hello 11059Hello!</code></pre> 11060</div> 11061</div> 11062<div class="admonitionblock note"> 11063<table> 11064<tr> 11065<td class="icon"> 11066<div class="title">ℹ</div> 11067</td> 11068<td class="content"> 11069The actual paths in the <code>bin</code> sub-directory will depend on your 11070toolset. 11071</td> 11072</tr> 11073</table> 11074</div> 11075</div> 11076<div class="sect2"> 11077<h3 id="_sanitizers"><a class="anchor" href="#_sanitizers"></a>10.3. Sanitizers</h3> 11078<div class="paragraph"> 11079<p>This example shows how to enable sanitizers when using a clang or gcc toolset</p> 11080</div> 11081<div class="listingblock"> 11082<div class="title"><code>main.cpp</code></div> 11083<div class="content"> 11084<pre class="pygments highlight"><code data-lang="cpp"><span></span><span class="tok-kt">int</span> <span class="tok-nf">main</span><span class="tok-p">()</span> 11085<span class="tok-p">{</span> 11086 <span class="tok-kt">char</span><span class="tok-o">*</span> <span class="tok-n">c</span> <span class="tok-o">=</span> <span class="tok-k">nullptr</span><span class="tok-p">;</span> 11087 <span class="tok-n">std</span><span class="tok-o">::</span><span class="tok-n">cout</span> <span class="tok-o"><<</span> <span class="tok-s">"Hello sanitizers</span><span class="tok-se">\n</span><span class="tok-s"> "</span> <span class="tok-o"><<</span> <span class="tok-o">*</span><span class="tok-n">c</span><span class="tok-p">;</span> 11088<span class="tok-p">}</span></code></pre> 11089</div> 11090</div> 11091<div class="paragraph"> 11092<p>Our <code>jamroot.jam</code> is minimal and only specifies one <code>exe</code> target for the 11093program:</p> 11094</div> 11095<div class="listingblock"> 11096<div class="title"><code>jamroot.jam</code></div> 11097<div class="content"> 11098<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-nb">exe</span><span class="tok-w"> </span>main<span class="tok-w"> </span>:<span class="tok-w"> </span>main.cpp<span class="tok-w"> </span>;<span class="tok-w"></span></code></pre> 11099</div> 11100</div> 11101<div class="paragraph"> 11102<p>Sanitizers can be enabled by passing <code>on</code> or <code>norecover</code> to the appropriate sanitizer feature 11103(e.g. <code>thread-sanitizer=on</code>). The <code>norecover</code> option causes the program to terminate after 11104the first sanitizer issue is detected. The following example shows how to enable <code>address</code> and <code>undefined</code> 11105sanitizers in a simple program:</p> 11106</div> 11107<div class="listingblock"> 11108<div class="content"> 11109<pre class="pygments highlight"><code data-lang="bash"><span></span>> <span class="tok-nb">cd</span> /example/sanitizers 11110> b2 <span class="tok-nv">toolset</span><span class="tok-o">=</span>gcc address-sanitizer<span class="tok-o">=</span>norecover undefined-sanitizer<span class="tok-o">=</span>on 11111...found <span class="tok-m">10</span> targets... 11112...updating <span class="tok-m">7</span> targets... 11113gcc.compile.c++ bin/gcc-7.3.0/debug/address-sanitizer-norecover/undefined-sanitizer-on/main.o 11114gcc.link bin/gcc-7.3.0/debug/address-sanitizer-norecover/undefined-sanitizer-on/main 11115...updated <span class="tok-m">7</span> targets...</code></pre> 11116</div> 11117</div> 11118<div class="paragraph"> 11119<p>Running the produced program may produce an output simillar to the following:</p> 11120</div> 11121<div class="listingblock"> 11122<div class="content"> 11123<pre class="pygments highlight"><code data-lang="bash"><span></span>> ./bin/gcc-7.3.0/debug/address-sanitizer-norecover/undefined-sanitizer-on/main 11124Hello sanitizers 11125main.cpp:6:43: runtime error: load of null pointer of <span class="tok-nb">type</span> <span class="tok-s1">'char'</span> 11126ASAN:DEADLYSIGNAL 11127<span class="tok-o">=================================================================</span> 11128<span class="tok-o">==</span><span class="tok-nv">29767</span><span class="tok-o">==</span>ERROR: AddressSanitizer: SEGV on unknown address 0x000000000000 <span class="tok-o">(</span>pc 0x55ba7988af1b bp 0x7ffdf3d76560 sp 0x7ffdf3d76530 T0<span class="tok-o">)</span> 11129<span class="tok-o">==</span><span class="tok-nv">29767</span><span class="tok-o">==</span>The signal is caused by a READ memory access. 11130<span class="tok-o">==</span><span class="tok-nv">29767</span><span class="tok-o">==</span>Hint: address points to the zero page. 11131 <span class="tok-c1">#0 0x55ba7988af1a in main /home/damian/projects/boost/tools/build/example/sanitizers/main.cpp:6</span> 11132 <span class="tok-c1">#1 0x7f42f2ba1b96 in __libc_start_main (/lib/x86_64-linux-gnu/libc.so.6+0x21b96)</span> 11133 <span class="tok-c1">#2 0x55ba7988adb9 in _start (/home/damian/projects/boost/tools/build/example/sanitizers/bin/gcc-7.3.0/debug/address-sanitizer-norecover/undefined-sanitizer-on/main+0xdb9)</span> 11134 11135AddressSanitizer can not provide additional info. 11136SUMMARY: AddressSanitizer: SEGV /home/damian/projects/boost/tools/build/example/sanitizers/main.cpp:6 in <span class="tok-nv">main</span> 11137<span class="tok-o">==</span><span class="tok-nv">29767</span><span class="tok-o">==</span>ABORTING</code></pre> 11138</div> 11139</div> 11140<div class="admonitionblock note"> 11141<table> 11142<tr> 11143<td class="icon"> 11144<div class="title">ℹ</div> 11145</td> 11146<td class="content"> 11147The actual paths in the <code>bin</code> sub-directory will depend on your 11148toolset and configuration. The presented output may vary depending on your compiler version. 11149</td> 11150</tr> 11151</table> 11152</div> 11153</div> 11154</div> 11155</div> 11156<div class="sect1"> 11157<h2 id="bbv2.jam"><a class="anchor" href="#bbv2.jam"></a>11. Boost.Jam Documentation</h2> 11158<div class="sectionbody"> 11159<div class="quoteblock"> 11160<blockquote> 11161<div class="paragraph"> 11162<p>Jam is a make(1) replacement that makes building simple things simple and building 11163complicated things manageable.</p> 11164</div> 11165</blockquote> 11166</div> 11167<div class="sect2"> 11168<h3 id="jam.building"><a class="anchor" href="#jam.building"></a>11.1. Building B2</h3> 11169<div class="paragraph"> 11170<p>Installing <code>B2</code> after building it is simply a matter of copying the 11171generated executables someplace in your <code>PATH</code>. For building the 11172executables there are a set of <code>build</code> bootstrap scripts to accommodate 11173particular environments. The scripts take one optional argument, the 11174name of the toolset to build with. When the toolset is not given an 11175attempt is made to detect an available toolset and use that. The build 11176scripts accept these arguments:</p> 11177</div> 11178<div class="listingblock"> 11179<div class="content"> 11180<pre class="pygments highlight"><code data-lang="shell"><span></span>build <span class="tok-o">[</span>toolset<span class="tok-o">]</span></code></pre> 11181</div> 11182</div> 11183<div class="paragraph"> 11184<p>Running the scripts without arguments will give you the best chance of 11185success. On Windows platforms from a command console do:</p> 11186</div> 11187<div class="listingblock"> 11188<div class="content"> 11189<pre class="pygments highlight"><code data-lang="bat"><span></span><span class="tok-k">cd</span> jam source location 11190.\build.bat</code></pre> 11191</div> 11192</div> 11193<div class="paragraph"> 11194<p>On Unix type platforms do:</p> 11195</div> 11196<div class="listingblock"> 11197<div class="content"> 11198<pre class="pygments highlight"><code data-lang="shell"><span></span><span class="tok-nb">cd</span> jam <span class="tok-nb">source</span> location 11199sh ./build.sh</code></pre> 11200</div> 11201</div> 11202<div class="paragraph"> 11203<p>For the Boost.Jam source included with the Boost distribution the <em>jam 11204source location</em> is <code>BOOST_ROOT/tools/build/src/engine</code>.</p> 11205</div> 11206<div class="paragraph"> 11207<p>If the scripts fail to detect an appropriate toolset to build with your 11208particular toolset may not be auto-detectable. In that case, you can 11209specify the toolset as the first argument, this assumes that the toolset 11210is readily available in the <code>PATH</code>.</p> 11211</div> 11212<div class="admonitionblock note"> 11213<table> 11214<tr> 11215<td class="icon"> 11216<div class="title">ℹ</div> 11217</td> 11218<td class="content"> 11219The toolset used to build Boost.Jam is independent of the toolsets used 11220for B2. Only one version of Boost.Jam is needed to use 11221B2. 11222</td> 11223</tr> 11224</table> 11225</div> 11226<div class="paragraph"> 11227<p>The supported toolsets, and whether they are auto-detected, are:</p> 11228</div> 11229<table class="tableblock frame-all grid-all fit-content"> 11230<caption class="title">Table 2. Supported Toolsets</caption> 11231<colgroup> 11232<col> 11233<col> 11234<col> 11235<col> 11236</colgroup> 11237<thead> 11238<tr> 11239<th class="tableblock halign-left valign-top">Script</th> 11240<th class="tableblock halign-left valign-top">Platform</th> 11241<th class="tableblock halign-left valign-top">Toolset</th> 11242<th class="tableblock halign-left valign-top">Detection and Notes</th> 11243</tr> 11244</thead> 11245<tbody> 11246<tr> 11247<td class="tableblock halign-left valign-top"><p class="tableblock"><code>build.bat</code></p></td> 11248<td class="tableblock halign-left valign-top"><p class="tableblock">Windows NT, 2000, and XP</p></td> 11249<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="http://www.codegear.com/downloads/free/cppbuilder"><code>borland</code></a>, 11250<a href="http://www.borland.com/">Borland</a> C++Builder (BCC 5.5)</p></td> 11251<td class="tableblock halign-left valign-top"><div class="content"><div class="ulist"> 11252<ul> 11253<li> 11254<p>Common install location: <code>C:\Borland\BCC55</code></p> 11255</li> 11256<li> 11257<p><code>BCC32.EXE</code> in <code>PATH</code></p> 11258</li> 11259</ul> 11260</div></div></td> 11261</tr> 11262<tr> 11263<td class="tableblock halign-left valign-top"></td> 11264<td class="tableblock halign-left valign-top"></td> 11265<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="http://www.comeaucomputing.com/"><code>como</code></a>, Comeau Computing C/C++</p></td> 11266<td class="tableblock halign-left valign-top"></td> 11267</tr> 11268<tr> 11269<td class="tableblock halign-left valign-top"></td> 11270<td class="tableblock halign-left valign-top"></td> 11271<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="http://gcc.gnu.org/"><code>gcc</code></a>, GNU GCC</p></td> 11272<td class="tableblock halign-left valign-top"></td> 11273</tr> 11274<tr> 11275<td class="tableblock halign-left valign-top"></td> 11276<td class="tableblock halign-left valign-top"></td> 11277<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="http://gcc.gnu.org/"><code>gcc-nocygwin</code></a>, GNU GCC</p></td> 11278<td class="tableblock halign-left valign-top"></td> 11279</tr> 11280<tr> 11281<td class="tableblock halign-left valign-top"></td> 11282<td class="tableblock halign-left valign-top"></td> 11283<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="http://www.intel.com/software/products/compilers/c60"><code>intel-win32</code></a>, 11284Intel C++ Compiler for Windows</p></td> 11285<td class="tableblock halign-left valign-top"><div class="content"><div class="ulist"> 11286<ul> 11287<li> 11288<p><code>ICL.EXE</code> in <code>PATH</code></p> 11289</li> 11290</ul> 11291</div></div></td> 11292</tr> 11293<tr> 11294<td class="tableblock halign-left valign-top"></td> 11295<td class="tableblock halign-left valign-top"></td> 11296<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="http://www.metrowerks.com/"><code>metrowerks</code></a>, MetroWerks CodeWarrior 11297C/C++ 7.x, 8.x, 9.x</p></td> 11298<td class="tableblock halign-left valign-top"><div class="content"><div class="ulist"> 11299<ul> 11300<li> 11301<p><code>CWFolder</code> variable configured</p> 11302</li> 11303<li> 11304<p><code>MWCC.EXE</code> in PATH</p> 11305</li> 11306</ul> 11307</div></div></td> 11308</tr> 11309<tr> 11310<td class="tableblock halign-left valign-top"></td> 11311<td class="tableblock halign-left valign-top"></td> 11312<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="http://www.mingw.org/"><code>mingw</code></a>, GNU <a href="http://gcc.gnu.org/">GCC</a> as the 11313<a href="http://www.mingw.org/">MinGW</a> configuration</p></td> 11314<td class="tableblock halign-left valign-top"><div class="content"><div class="ulist"> 11315<ul> 11316<li> 11317<p>Common install location: <code>C:\MinGW</code></p> 11318</li> 11319</ul> 11320</div></div></td> 11321</tr> 11322<tr> 11323<td class="tableblock halign-left valign-top"></td> 11324<td class="tableblock halign-left valign-top"></td> 11325<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="http://msdn.microsoft.com/visualc/"><code>msvc</code></a>, Microsoft Visual C++ 113266.x</p></td> 11327<td class="tableblock halign-left valign-top"><div class="content"><div class="ulist"> 11328<ul> 11329<li> 11330<p><code>VCVARS32.BAT</code> already configured</p> 11331</li> 11332<li> 11333<p><code>%MSVCDir%</code> is present in environment</p> 11334</li> 11335<li> 11336<p>Common install locations: <code>%ProgramFiles%\Microsoft Visual Studio</code>, 11337<code>%ProgramFiles%\Microsoft Visual C++</code></p> 11338</li> 11339<li> 11340<p><code>CL.EXE</code> in <code>PATH</code></p> 11341</li> 11342</ul> 11343</div></div></td> 11344</tr> 11345<tr> 11346<td class="tableblock halign-left valign-top"></td> 11347<td class="tableblock halign-left valign-top"></td> 11348<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="http://msdn.microsoft.com/visualc/"><code>vc7</code></a>, Microsoft Visual C++ 7.x</p></td> 11349<td class="tableblock halign-left valign-top"><div class="content"><div class="ulist"> 11350<ul> 11351<li> 11352<p><code>VCVARS32.BAT</code> or <code>VSVARS32.BAT</code> already configured</p> 11353</li> 11354<li> 11355<p><code>%VS71COMNTOOLS%</code> is present in environment</p> 11356</li> 11357<li> 11358<p><code>%VCINSTALLDIR%</code> is present in environment</p> 11359</li> 11360<li> 11361<p>Common install locations: <code>%ProgramFiles%\Microsoft Visual Studio .NET</code>, 11362<code>%ProgramFiles%\Microsoft Visual Studio .NET 2003</code></p> 11363</li> 11364<li> 11365<p><code>CL.EXE</code> in <code>PATH</code></p> 11366</li> 11367</ul> 11368</div></div></td> 11369</tr> 11370<tr> 11371<td class="tableblock halign-left valign-top"></td> 11372<td class="tableblock halign-left valign-top"></td> 11373<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="http://msdn.microsoft.com/visualc/"><code>vc8</code> and <code>vc9</code></a>, Microsoft 11374Visual C++ 8.x and 9.x</p></td> 11375<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph"> 11376<p>Detection:</p> 11377</div> 11378<div class="ulist"> 11379<ul> 11380<li> 11381<p><code>VCVARSALL.BAT</code> already configured</p> 11382</li> 11383<li> 11384<p><code>%VS90COMNTOOLS%</code> is present in environment</p> 11385</li> 11386<li> 11387<p>Common install location: <code>%ProgramFiles%\Microsoft Visual Studio 9</code></p> 11388</li> 11389<li> 11390<p><code>%VS80COMNTOOLS%</code> is present in environment</p> 11391</li> 11392<li> 11393<p>Common install location: <code>%ProgramFiles%\Microsoft Visual Studio 8</code></p> 11394</li> 11395<li> 11396<p><code>CL.EXE</code> in <code>PATH</code></p> 11397</li> 11398</ul> 11399</div> 11400<div class="paragraph"> 11401<p>Notes:</p> 11402</div> 11403<div class="ulist"> 11404<ul> 11405<li> 11406<p>If <code>VCVARSALL.BAT</code> 11407is called to set up the toolset, it is passed all the extra arguments, 11408see below for what those arguments are. This can be used to build, for 11409example, a Win64 specific version of <code>b2</code>. Consult the VisualStudio 11410documentation for what the possible argument values to the <code>VCVARSALL.BAT</code> 11411are.</p> 11412</li> 11413</ul> 11414</div></div></td> 11415</tr> 11416<tr> 11417<td class="tableblock halign-left valign-top"><p class="tableblock"><code>build.sh</code></p></td> 11418<td class="tableblock halign-left valign-top"><p class="tableblock">Unix, Linux, Cygwin, etc.</p></td> 11419<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="http://www.hp.com/go/c++"><code>acc</code></a>, 11420HP-UX aCC</p></td> 11421<td class="tableblock halign-left valign-top"><div class="content"><div class="ulist"> 11422<ul> 11423<li> 11424<p><code>aCC</code> in <code>PATH</code></p> 11425</li> 11426<li> 11427<p><code>uname</code> is "HP-UX"</p> 11428</li> 11429</ul> 11430</div></div></td> 11431</tr> 11432<tr> 11433<td class="tableblock halign-left valign-top"></td> 11434<td class="tableblock halign-left valign-top"></td> 11435<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="http://www.comeaucomputing.com/"><code>como</code></a>, Comeau Computing C/C++</p></td> 11436<td class="tableblock halign-left valign-top"><div class="content"><div class="ulist"> 11437<ul> 11438<li> 11439<p><code>como</code> in <code>PATH</code></p> 11440</li> 11441</ul> 11442</div></div></td> 11443</tr> 11444<tr> 11445<td class="tableblock halign-left valign-top"></td> 11446<td class="tableblock halign-left valign-top"></td> 11447<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="http://gcc.gnu.org/"><code>gcc</code></a>, GNU GCC</p></td> 11448<td class="tableblock halign-left valign-top"><div class="content"><div class="ulist"> 11449<ul> 11450<li> 11451<p><code>gcc</code> in <code>PATH</code></p> 11452</li> 11453</ul> 11454</div></div></td> 11455</tr> 11456<tr> 11457<td class="tableblock halign-left valign-top"></td> 11458<td class="tableblock halign-left valign-top"></td> 11459<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="http://www.intel.com/software/products/compilers/c60l/"><code>intel-linux</code></a>, 11460Intel C++ for Linux</p></td> 11461<td class="tableblock halign-left valign-top"><div class="content"><div class="ulist"> 11462<ul> 11463<li> 11464<p><code>icc</code> in <code>PATH</code></p> 11465</li> 11466<li> 11467<p>Common install locations: <code>/opt/intel/cc/9.0</code>, <code>/opt/intel_cc_80</code>, 11468<code>/opt/intel/compiler70</code>, <code>/opt/intel/compiler60</code>, <code>/opt/intel/compiler50</code></p> 11469</li> 11470</ul> 11471</div></div></td> 11472</tr> 11473<tr> 11474<td class="tableblock halign-left valign-top"></td> 11475<td class="tableblock halign-left valign-top"></td> 11476<td class="tableblock halign-left valign-top"><p class="tableblock"><code>kcc</code>, Intel KAI C++</p></td> 11477<td class="tableblock halign-left valign-top"><div class="content"><div class="ulist"> 11478<ul> 11479<li> 11480<p><code>KCC</code> in <code>PATH</code></p> 11481</li> 11482</ul> 11483</div></div></td> 11484</tr> 11485<tr> 11486<td class="tableblock halign-left valign-top"></td> 11487<td class="tableblock halign-left valign-top"></td> 11488<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="http://www.codegear.com/downloads/free/cppbuilder"><code>kylix</code></a>, 11489<a href="http://www.borland.com/">Borland</a> C++Builder</p></td> 11490<td class="tableblock halign-left valign-top"><div class="content"><div class="ulist"> 11491<ul> 11492<li> 11493<p><code>bc++</code> in <code>PATH</code></p> 11494</li> 11495</ul> 11496</div></div></td> 11497</tr> 11498<tr> 11499<td class="tableblock halign-left valign-top"></td> 11500<td class="tableblock halign-left valign-top"></td> 11501<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="http://www.sgi.com/developers/devtools/languages/mipspro.html"><code>mipspro</code></a>, 11502SGI MIPSpro C</p></td> 11503<td class="tableblock halign-left valign-top"><div class="content"><div class="ulist"> 11504<ul> 11505<li> 11506<p><code>uname</code> is "IRIX" or "IRIX64"</p> 11507</li> 11508</ul> 11509</div></div></td> 11510</tr> 11511<tr> 11512<td class="tableblock halign-left valign-top"></td> 11513<td class="tableblock halign-left valign-top"></td> 11514<td class="tableblock halign-left valign-top"><p class="tableblock"><code>sunpro</code>, Sun Workshop 6 C++</p></td> 11515<td class="tableblock halign-left valign-top"><div class="content"><div class="ulist"> 11516<ul> 11517<li> 11518<p>Standard install location: <code>/opt/SUNWspro</code></p> 11519</li> 11520</ul> 11521</div></div></td> 11522</tr> 11523<tr> 11524<td class="tableblock halign-left valign-top"></td> 11525<td class="tableblock halign-left valign-top"></td> 11526<td class="tableblock halign-left valign-top"><p class="tableblock"><code>qcc</code>, <a href="http://www.qnx.com/">QNX Neutrino</a></p></td> 11527<td class="tableblock halign-left valign-top"><div class="content"><div class="ulist"> 11528<ul> 11529<li> 11530<p><code>uname</code> is "QNX" and <code>qcc</code> in <code>PATH</code></p> 11531</li> 11532</ul> 11533</div></div></td> 11534</tr> 11535<tr> 11536<td class="tableblock halign-left valign-top"></td> 11537<td class="tableblock halign-left valign-top"></td> 11538<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="http://www.tru64unix.compaq.com/cplus/"><code>true64cxx</code></a>, Compaq C++ 11539Compiler for True64 UNIX</p></td> 11540<td class="tableblock halign-left valign-top"><div class="content"><div class="ulist"> 11541<ul> 11542<li> 11543<p><code>uname</code> is "OSF1"</p> 11544</li> 11545</ul> 11546</div></div></td> 11547</tr> 11548<tr> 11549<td class="tableblock halign-left valign-top"></td> 11550<td class="tableblock halign-left valign-top"></td> 11551<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="http://www.ibm.com/software/awdtools/vacpp/"><code>vacpp</code></a>, IBM VisualAge 11552C++</p></td> 11553<td class="tableblock halign-left valign-top"><div class="content"><div class="ulist"> 11554<ul> 11555<li> 11556<p><code>xlc</code> in <code>PATH</code></p> 11557</li> 11558</ul> 11559</div></div></td> 11560</tr> 11561<tr> 11562<td class="tableblock halign-left valign-top"></td> 11563<td class="tableblock halign-left valign-top"><p class="tableblock">MacOS X</p></td> 11564<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="http://developer.apple.com/tools/compilers.html"><code>darwin</code></a>, 11565Apple MacOS X GCC</p></td> 11566<td class="tableblock halign-left valign-top"><div class="content"><div class="ulist"> 11567<ul> 11568<li> 11569<p><code>uname</code> is "Darwin"</p> 11570</li> 11571</ul> 11572</div></div></td> 11573</tr> 11574<tr> 11575<td class="tableblock halign-left valign-top"></td> 11576<td class="tableblock halign-left valign-top"><p class="tableblock">Windows NT, 2000, and XP</p></td> 11577<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="http://www.mingw.org/"><code>mingw</code></a>, GNU 11578<a href="http://gcc.gnu.org/">GCC</a> as the <a href="http://www.mingw.org/">MinGW</a> 11579configuration with the MSYS shell</p></td> 11580<td class="tableblock halign-left valign-top"><div class="content"><div class="ulist"> 11581<ul> 11582<li> 11583<p>Common install location: <code>/mingw</code></p> 11584</li> 11585</ul> 11586</div></div></td> 11587</tr> 11588</tbody> 11589</table> 11590<div class="paragraph"> 11591<p>The built executables are placed in a subdirectory specific to your 11592platform. For example, in Linux running on an Intel x86 compatible chip, 11593the executables are placed in: <code>bin.linuxx86</code>. The <code>b2[.exe]</code> 11594executable can be used to invoke B2.</p> 11595</div> 11596<div class="paragraph"> 11597<p>The build scripts support additional invocation arguments for use by 11598developers of Boost.Jam and for additional setup of the toolset. The 11599extra arguments come after the toolset:</p> 11600</div> 11601<div class="ulist"> 11602<ul> 11603<li> 11604<p>Arguments not in the form of an option, before option arguments, are 11605used for extra setup to toolset configuration scripts.</p> 11606</li> 11607<li> 11608<p>Arguments of the form <code>--option</code>, which are passed to the 11609<code>build.jam</code> build script.</p> 11610</li> 11611<li> 11612<p>Arguments not in the form of an option, after the options, which are 11613targets for the <code>build.jam</code> script.</p> 11614</li> 11615</ul> 11616</div> 11617<div class="listingblock"> 11618<div class="content"> 11619<pre>build [toolset] [setup*] [--option+ target*]</pre> 11620</div> 11621</div> 11622<div class="paragraph"> 11623<p>The arguments immediately after the toolset are passed directly to the 11624setup script of the toolset, if available and if it needs to be invoked. 11625This allows one to configure the toolset ass needed to do non-default 11626builds of <code>b2</code>. For example to build a Win64 version with <code>vc8</code>. See the 11627toolset description above for when particular toolsets support this.</p> 11628</div> 11629<div class="paragraph"> 11630<p>The arguments starting with the <code>--option</code> forms are passed to the 11631<code>build.jam</code> script and are used to further customize what gets built. 11632Options and targets supported by the <code>build.jam</code> script:</p> 11633</div> 11634<div class="dlist"> 11635<dl> 11636<dt class="hdlist1"><code>---</code></dt> 11637<dd> 11638<p>Empty option when one wants to only specify a target.</p> 11639</dd> 11640<dt class="hdlist1"><code>--release</code></dt> 11641<dd> 11642<p>The default, builds the optimized executable.</p> 11643</dd> 11644<dt class="hdlist1"><code>--debug</code></dt> 11645<dd> 11646<p>Builds debugging versions of the executable. When built they are 11647placed in their own directory <code>bin./platform/.debug</code>.</p> 11648</dd> 11649<dt class="hdlist1"><code>--grammar</code></dt> 11650<dd> 11651<p>Normally the Jam language grammar parsing files are not regenerated. 11652This forces building of the grammar, although it may not force the 11653regeneration of the grammar parser. If the parser is out of date it 11654will be regenerated and subsequently built.</p> 11655</dd> 11656<dt class="hdlist1"><code>--with-python=path</code></dt> 11657<dd> 11658<p>Enables Python integration, given a path to the Python libraries.</p> 11659</dd> 11660<dt class="hdlist1"><code>--gc</code></dt> 11661<dd> 11662<p>Enables use of the Boehm Garbage Collector. The build will look for 11663the Boehm-GC source in a "boehm_gc" subdirectory from the <code>b2</code> 11664sources.</p> 11665</dd> 11666<dt class="hdlist1"><code>--duma</code></dt> 11667<dd> 11668<p>Enables use of the DUMA (Detect Unintended Memory Access) debugging 11669memory allocator. The build expects to find the DUMA source files in a 11670"duma" subdirectory from the <code>b2</code> sources.</p> 11671</dd> 11672<dt class="hdlist1"><code>--toolset-root=path</code></dt> 11673<dd> 11674<p>Indicates where the toolset used to build is located. This option is 11675passed in by the bootstrap (<code>build.bat</code> or <code>build.sh</code>) script.</p> 11676</dd> 11677<dt class="hdlist1"><code>--show-locate-target</code></dt> 11678<dd> 11679<p>For information, prints out where it will put the built executable.</p> 11680</dd> 11681<dt class="hdlist1"><code>--noassert</code></dt> 11682<dd> 11683<p>Disable debug assertions, even if building the debug version of the 11684executable.</p> 11685</dd> 11686<dt class="hdlist1"><code>dist</code></dt> 11687<dd> 11688<p>Generate packages (compressed archives) as appropriate for 11689distribution in the platform, if possible.</p> 11690</dd> 11691<dt class="hdlist1"><code>clean</code></dt> 11692<dd> 11693<p>Remove all the built executables and objects.</p> 11694</dd> 11695</dl> 11696</div> 11697</div> 11698<div class="sect2"> 11699<h3 id="jam.language"><a class="anchor" href="#jam.language"></a>11.2. Language</h3> 11700<div class="paragraph"> 11701<p><code>B2</code> has an interpreted, procedural language. Statements in <code>b2</code> are 11702rule (procedure) definitions, rule invocations, flow-of-control 11703structures, variable assignments, and sundry language support.</p> 11704</div> 11705<div class="sect3"> 11706<h4 id="jam.language.lexical"><a class="anchor" href="#jam.language.lexical"></a>11.2.1. Lexical Features</h4> 11707<div class="paragraph"> 11708<p><code>B2</code> treats its input files as whitespace-separated tokens, with two 11709exceptions: double quotes (") can enclose whitespace to embed it into a 11710token, and everything between the matching curly braces (\{}) in the 11711definition of a rule action is treated as a single string. A backslash 11712(\) can escape a double quote, or any single whitespace character.</p> 11713</div> 11714<div class="paragraph"> 11715<p><code>B2</code> requires whitespace (blanks, tabs, or newlines) to surround all 11716tokens, including the colon (:) and semicolon (;) tokens.</p> 11717</div> 11718<div class="paragraph"> 11719<p><code>B2</code> keywords (an mentioned in this document) are reserved and generally 11720must be quoted with double quotes (") to be used as arbitrary tokens, 11721such as variable or target names.</p> 11722</div> 11723<div class="paragraph"> 11724<p>Comments start with the <code>#</code> character and extend until the end of line. 11725And block comments start with <code>#|</code> and extend until the next <code>|#</code>.</p> 11726</div> 11727</div> 11728<div class="sect3"> 11729<h4 id="jam.language.target"><a class="anchor" href="#jam.language.target"></a>11.2.2. Targets</h4> 11730<div class="paragraph"> 11731<p>The essential <code>b2</code> data entity is a target. Build targets are files to 11732be updated. Source targets are the files used in updating built targets. 11733Built targets and source targets are collectively referred to as file 11734targets, and frequently built targets are source targets for other built 11735targets. Pseudo-targets are symbols representing dependencies on other 11736targets, but which are not themselves associated with any real file.</p> 11737</div> 11738<div class="paragraph"> 11739<p>A file target’s identifier is generally the file’s name, which can be 11740absolutely rooted, relative to the directory of <code>b2`s invocation, or 11741simply local (no directory). Most often it is the last case, and the 11742actual file path is bound using the `$(SEARCH)</code> and <code>$(LOCATE)</code> special 11743variables. See <a href="#jam.language.variables.builtins.search">SEARCH and 11744LOCATE Variables</a> below. A local filename is optionally qualified with 11745grist, a string value used to assure uniqueness. A file target with an 11746identifier of the form <em>file(member)</em> is a library member (usually an 11747<code>ar</code>(1) archive on Unix).</p> 11748</div> 11749<div class="sect4"> 11750<h5 id="jam.language.target.binding_detection"><a class="anchor" href="#jam.language.target.binding_detection"></a>Binding Detection</h5> 11751<div class="paragraph"> 11752<p>Whenever a target is bound to a location in the filesystem, Boost Jam 11753will look for a variable called <code>BINDRULE</code> (first "on" the target being 11754bound, then in the global module). If non-empty, <code>$(BINDRULE[1])</code> names 11755a rule which is called with the name of the target and the path it is 11756being bound to. The signature of the rule named by <code>$(BINDRULE[1])</code> 11757should match the following:</p> 11758</div> 11759<div class="listingblock"> 11760<div class="content"> 11761<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-k">rule</span><span class="tok-w"> </span><span class="tok-nf">bind-rule</span><span class="tok-w"> </span><span class="tok-p">(</span><span class="tok-w"> </span><span class="tok-nv">target</span><span class="tok-w"> </span><span class="tok-p">:</span><span class="tok-w"> </span><span class="tok-nv">path</span><span class="tok-w"> </span><span class="tok-p">)</span><span class="tok-w"></span></code></pre> 11762</div> 11763</div> 11764<div class="paragraph"> 11765<p>This facility is useful for correct header file scanning, since many 11766compilers will search for <code>#include</code> files first in the directory 11767containing the file doing the <code>#include</code> directive. <code>$(BINDRULE)</code> can be 11768used to make a record of that directory.</p> 11769</div> 11770</div> 11771</div> 11772<div class="sect3"> 11773<h4 id="jam.language.rules"><a class="anchor" href="#jam.language.rules"></a>11.2.3. Rules</h4> 11774<div class="paragraph"> 11775<p>The basic <code>b2</code> language entity is called a rule. A rule is defined in 11776two parts: the procedure and the actions. The procedure is a body of jam 11777statements to be run when the rule is invoked; the actions are the OS 11778shell commands to execute when updating the built targets of the rule.</p> 11779</div> 11780<div class="paragraph"> 11781<p>Rules can return values, which can be expanded into a list with "[ 11782<em>rule</em> <em>args</em> …​ ]". A rule’s value is the value of its last statement, 11783though only the following statements have values: 'if' (value of the leg 11784chosen), 'switch' (value of the case chosen), set (value of the 11785resulting variable), and 'return' (value of its arguments).</p> 11786</div> 11787<div class="paragraph"> 11788<p>The <code>b2</code> statements for defining and invoking rules are as follows:</p> 11789</div> 11790<div class="paragraph"> 11791<p>Define a rule’s procedure, replacing any previous definition.</p> 11792</div> 11793<div class="listingblock"> 11794<div class="content"> 11795<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-k">rule</span><span class="tok-w"> </span><span class="tok-nf">rulename</span><span class="tok-w"> </span><span class="tok-nv">{</span><span class="tok-w"> </span><span class="tok-nv">statements</span><span class="tok-w"> </span><span class="tok-nv">}</span><span class="tok-w"></span></code></pre> 11796</div> 11797</div> 11798<div class="paragraph"> 11799<p>Define a rule’s updating actions, replacing any previous definition.</p> 11800</div> 11801<div class="listingblock"> 11802<div class="content"> 11803<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-k">actions</span><span class="tok-w"> </span><span class="tok-nf">[</span><span class="tok-w"> </span><span class="tok-nv">modifiers</span><span class="tok-w"> </span><span class="tok-nv">]</span><span class="tok-w"> </span><span class="tok-nv">rulename</span><span class="tok-w"> </span>{<span class="tok-sh"> commands </span><span class="tok-p">}</span><span class="tok-w"></span></code></pre> 11804</div> 11805</div> 11806<div class="paragraph"> 11807<p>Invoke a rule.</p> 11808</div> 11809<div class="listingblock"> 11810<div class="content"> 11811<pre class="pygments highlight"><code data-lang="jam"><span></span>rulename<span class="tok-w"> </span>field1<span class="tok-w"> </span>:<span class="tok-w"> </span>field2<span class="tok-w"> </span>:<span class="tok-w"> </span>...<span class="tok-w"> </span>:<span class="tok-w"> </span>fieldN<span class="tok-w"> </span>;<span class="tok-w"></span></code></pre> 11812</div> 11813</div> 11814<div class="paragraph"> 11815<p>Invoke a rule under the influence of target’s specific variables..</p> 11816</div> 11817<div class="listingblock"> 11818<div class="content"> 11819<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-k">on</span><span class="tok-w"> </span>target<span class="tok-w"> </span>rulename<span class="tok-w"> </span>field1<span class="tok-w"> </span>:<span class="tok-w"> </span>field2<span class="tok-w"> </span>:<span class="tok-w"> </span>...<span class="tok-w"> </span>:<span class="tok-w"> </span>fieldN<span class="tok-w"> </span>;<span class="tok-w"></span></code></pre> 11820</div> 11821</div> 11822<div class="paragraph"> 11823<p>Used as an argument, expands to the return value of the rule invoked.</p> 11824</div> 11825<div class="listingblock"> 11826<div class="content"> 11827<pre class="pygments highlight"><code data-lang="jam"><span></span>[<span class="tok-w"> </span>rulename<span class="tok-w"> </span>field1<span class="tok-w"> </span>:<span class="tok-w"> </span>field2<span class="tok-w"> </span>:<span class="tok-w"> </span>...<span class="tok-w"> </span>:<span class="tok-w"> </span>fieldN<span class="tok-w"> </span>]<span class="tok-w"></span> 11828[<span class="tok-w"> </span><span class="tok-k">on</span><span class="tok-w"> </span>target<span class="tok-w"> </span>rulename<span class="tok-w"> </span>field1<span class="tok-w"> </span>:<span class="tok-w"> </span>field2<span class="tok-w"> </span>:<span class="tok-w"> </span>...<span class="tok-w"> </span>:<span class="tok-w"> </span>fieldN<span class="tok-w"> </span>]<span class="tok-w"></span></code></pre> 11829</div> 11830</div> 11831<div class="paragraph"> 11832<p>A rule is invoked with values in <em>field1</em> through <em>fieldN</em>. They may be 11833referenced in the procedure’s statements as <code>$(1)</code> through <code>$(N)</code> (9 11834max), and the first two only may be referenced in the action’s 11835<em>commands</em> as <code>$(1)</code> and <code>$(2)</code>. <code>$(<)</code> and <code>$(>)</code> are synonymous with 11836<code>$(1)</code> and <code>$(2)</code>.</p> 11837</div> 11838<div class="paragraph"> 11839<p>Rules fall into two categories: updating rules (with actions), and pure 11840procedure rules (without actions). Updating rules treat arguments <code>$(1)</code> 11841and <code>$(2)</code> as built targets and sources, respectively, while pure 11842procedure rules can take arbitrary arguments.</p> 11843</div> 11844<div class="paragraph"> 11845<p>When an updating rule is invoked, its updating actions are added to 11846those associated with its built targets (<code>$(1)</code>) before the rule’s 11847procedure is run. Later, to build the targets in the updating phase, 11848<em>commands</em> are passed to the OS command shell, with <code>$(1)</code> and <code>$(2)</code> 11849replaced by bound versions of the target names. See Binding above.</p> 11850</div> 11851<div class="paragraph"> 11852<p>Rule invocation may be indirected through a variable:</p> 11853</div> 11854<div class="listingblock"> 11855<div class="content"> 11856<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-si">$(var)</span><span class="tok-w"> </span>field1<span class="tok-w"> </span>:<span class="tok-w"> </span>field2<span class="tok-w"> </span>:<span class="tok-w"> </span>...<span class="tok-w"> </span>:<span class="tok-w"> </span>fieldN<span class="tok-w"> </span>;<span class="tok-w"></span> 11857 11858<span class="tok-k">on</span><span class="tok-w"> </span>target<span class="tok-w"> </span><span class="tok-si">$(var)</span><span class="tok-w"> </span>field1<span class="tok-w"> </span>:<span class="tok-w"> </span>field2<span class="tok-w"> </span>:<span class="tok-w"> </span>...<span class="tok-w"> </span>:<span class="tok-w"> </span>fieldN<span class="tok-w"> </span>;<span class="tok-w"></span> 11859 11860[<span class="tok-w"> </span><span class="tok-si">$(var)</span><span class="tok-w"> </span>field1<span class="tok-w"> </span>:<span class="tok-w"> </span>field2<span class="tok-w"> </span>:<span class="tok-w"> </span>...<span class="tok-w"> </span>:<span class="tok-w"> </span>fieldN<span class="tok-w"> </span>]<span class="tok-w"></span> 11861[<span class="tok-w"> </span><span class="tok-k">on</span><span class="tok-w"> </span>target<span class="tok-w"> </span><span class="tok-si">$(var)</span><span class="tok-w"> </span>field1<span class="tok-w"> </span>:<span class="tok-w"> </span>field2<span class="tok-w"> </span>:<span class="tok-w"> </span>...<span class="tok-w"> </span>:<span class="tok-w"> </span>fieldN<span class="tok-w"> </span>]<span class="tok-w"></span></code></pre> 11862</div> 11863</div> 11864<div class="paragraph"> 11865<p>The variable’s value names the rule (or rules) to be invoked. A rule is 11866invoked for each element in the list of <code>$(var)`s values. The fields 11867`field1 : field2 : …​</code> are passed as arguments for each invocation For the [ 11868…​ ] forms, the return value is the concatenation of the return values 11869for all of the invocations.</p> 11870</div> 11871<div class="sect4"> 11872<h5 id="jam.language.rules.action_modifiers"><a class="anchor" href="#jam.language.rules.action_modifiers"></a>Action Modifiers</h5> 11873<div class="paragraph"> 11874<p>The following action modifiers are understood:</p> 11875</div> 11876<div class="dlist"> 11877<dl> 11878<dt class="hdlist1"><code>actions bind vars</code></dt> 11879<dd> 11880<p><code>$(vars)</code> will be replaced with bound values.</p> 11881</dd> 11882<dt class="hdlist1"><code>actions existing</code></dt> 11883<dd> 11884<p><code>$(>)</code> includes only source targets currently existing.</p> 11885</dd> 11886<dt class="hdlist1"><code>actions ignore</code></dt> 11887<dd> 11888<p>The return status of the commands is ignored.</p> 11889</dd> 11890<dt class="hdlist1"><code>actions piecemeal</code></dt> 11891<dd> 11892<p>commands are repeatedly invoked with a subset of <code>$(>)</code> small enough 11893to fit in the command buffer on this OS.</p> 11894</dd> 11895<dt class="hdlist1"><code>actions quietly</code></dt> 11896<dd> 11897<p>The action is not echoed to the standard output.</p> 11898</dd> 11899<dt class="hdlist1"><code>actions together</code></dt> 11900<dd> 11901<p>The <code>$(>)</code> from multiple invocations of the same action on the same 11902built target are glommed together.</p> 11903</dd> 11904<dt class="hdlist1"><code>actions updated</code></dt> 11905<dd> 11906<p><code>$(>)</code> includes only source targets themselves marked for updating.</p> 11907</dd> 11908</dl> 11909</div> 11910</div> 11911<div class="sect4"> 11912<h5 id="jam.language.rules.argument_lists"><a class="anchor" href="#jam.language.rules.argument_lists"></a>Argument lists</h5> 11913<div class="paragraph"> 11914<p>You can describe the arguments accepted by a rule, and refer to them by 11915name within the rule. For example, the following prints "I’m sorry, 11916Dave" to the console:</p> 11917</div> 11918<div class="listingblock"> 11919<div class="content"> 11920<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-k">rule</span><span class="tok-w"> </span><span class="tok-nf">report</span><span class="tok-w"> </span><span class="tok-p">(</span><span class="tok-w"> </span><span class="tok-nv">pronoun</span><span class="tok-w"> </span><span class="tok-nv">index</span><span class="tok-w"> </span><span class="tok-p">?</span><span class="tok-w"> </span><span class="tok-p">:</span><span class="tok-w"> </span><span class="tok-nv">state</span><span class="tok-w"> </span><span class="tok-p">:</span><span class="tok-w"> </span><span class="tok-nv">names</span><span class="tok-w"> </span><span class="tok-p">+</span><span class="tok-w"> </span><span class="tok-p">)</span><span class="tok-w"></span> 11921{<span class="tok-w"></span> 11922<span class="tok-w"> </span><span class="tok-k">local</span><span class="tok-w"> </span>he.suffix<span class="tok-w"> </span>she.suffix<span class="tok-w"> </span>it.suffix<span class="tok-w"> </span>=<span class="tok-w"> </span>s<span class="tok-w"> </span>;<span class="tok-w"></span> 11923<span class="tok-w"> </span><span class="tok-k">local</span><span class="tok-w"> </span>I.suffix<span class="tok-w"> </span>=<span class="tok-w"> </span>m<span class="tok-w"> </span>;<span class="tok-w"></span> 11924<span class="tok-w"> </span><span class="tok-k">local</span><span class="tok-w"> </span>they.suffix<span class="tok-w"> </span>you.suffix<span class="tok-w"> </span>=<span class="tok-w"> </span>re<span class="tok-w"> </span>;<span class="tok-w"></span> 11925<span class="tok-w"> </span><span class="tok-nb">ECHO</span><span class="tok-w"> </span><span class="tok-si">$(pronoun)</span>'<span class="tok-si">$($(pronoun).suffix)</span><span class="tok-w"> </span><span class="tok-si">$(state)</span>,<span class="tok-w"> </span><span class="tok-si">$(names[$(index)</span>])<span class="tok-w"> </span>;<span class="tok-w"></span> 11926}<span class="tok-w"></span> 11927report<span class="tok-w"> </span>I<span class="tok-w"> </span>2<span class="tok-w"> </span>:<span class="tok-w"> </span>sorry<span class="tok-w"> </span>:<span class="tok-w"> </span>Joe<span class="tok-w"> </span>Dave<span class="tok-w"> </span>Pete<span class="tok-w"> </span>;<span class="tok-w"></span></code></pre> 11928</div> 11929</div> 11930<div class="paragraph"> 11931<p>Each name in a list of formal arguments (separated by <code>:</code> in the rule 11932declaration) is bound to a single element of the corresponding actual 11933argument unless followed by one of these modifiers:</p> 11934</div> 11935<table class="tableblock frame-all grid-all fit-content"> 11936<colgroup> 11937<col> 11938<col> 11939</colgroup> 11940<thead> 11941<tr> 11942<th class="tableblock halign-left valign-top">Symbol</th> 11943<th class="tableblock halign-left valign-top">Semantics of preceding symbol</th> 11944</tr> 11945</thead> 11946<tbody> 11947<tr> 11948<td class="tableblock halign-left valign-top"><p class="tableblock"><code>?</code></p></td> 11949<td class="tableblock halign-left valign-top"><p class="tableblock">optional</p></td> 11950</tr> 11951<tr> 11952<td class="tableblock halign-left valign-top"><p class="tableblock"><code>*</code></p></td> 11953<td class="tableblock halign-left valign-top"><p class="tableblock">Bind to zero or more unbound elements of the actual argument. When 11954<code>*</code> appears where an argument name is expected, any number of additional 11955arguments are accepted. This feature can be used to implement "varargs" 11956rules.</p></td> 11957</tr> 11958<tr> 11959<td class="tableblock halign-left valign-top"><p class="tableblock"><code>+</code></p></td> 11960<td class="tableblock halign-left valign-top"><p class="tableblock">Bind to one or more unbound elements of the actual argument.</p></td> 11961</tr> 11962</tbody> 11963</table> 11964<div class="paragraph"> 11965<p>The actual and formal arguments are checked for inconsistencies, which 11966cause <code>b2</code> to exit with an error code:</p> 11967</div> 11968<div class="listingblock"> 11969<div class="content"> 11970<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-c1">### argument error</span> 11971<span class="tok-c1"># rule report ( pronoun index ? : state : names + )</span> 11972<span class="tok-c1"># called with: ( I 2 foo : sorry : Joe Dave Pete )</span> 11973<span class="tok-c1"># extra argument foo</span> 11974<span class="tok-c1">### argument error</span> 11975<span class="tok-c1"># rule report ( pronoun index ? : state : names + )</span> 11976<span class="tok-c1"># called with: ( I 2 : sorry )</span> 11977<span class="tok-c1"># missing argument names</span></code></pre> 11978</div> 11979</div> 11980<div class="paragraph"> 11981<p>If you omit the list of formal arguments, all checking is bypassed as in 11982"classic" Jam. Argument lists drastically improve the reliability and 11983readability of your rules, however, and are <strong>strongly recommended</strong> for 11984any new Jam code you write.</p> 11985</div> 11986</div> 11987</div> 11988<div class="sect3"> 11989<h4 id="jam.language.rules.builtins"><a class="anchor" href="#jam.language.rules.builtins"></a>11.2.4. Built-in Rules</h4> 11990<div class="paragraph"> 11991<p><code>B2</code> has a growing set of built-in rules, all of which are pure 11992procedure rules without updating actions. They are in three groups: the 11993first builds the dependency graph; the second modifies it; and the third 11994are just utility rules.</p> 11995</div> 11996<div class="sect4"> 11997<h5 id="jam.language.rules.builtins.dependency_building"><a class="anchor" href="#jam.language.rules.builtins.dependency_building"></a>Dependency Building</h5> 11998<div class="sect5"> 11999<h6 id="jam.language.rules.builtins.dependency_building._depends__"><a class="anchor" href="#jam.language.rules.builtins.dependency_building._depends__"></a><code>DEPENDS</code></h6> 12000<div class="listingblock"> 12001<div class="content"> 12002<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-k">rule</span><span class="tok-w"> </span><span class="tok-nf">DEPENDS</span><span class="tok-w"> </span><span class="tok-p">(</span><span class="tok-w"> </span><span class="tok-nv">targets1</span><span class="tok-w"> </span><span class="tok-p">*</span><span class="tok-w"> </span><span class="tok-p">:</span><span class="tok-w"> </span><span class="tok-nv">targets2</span><span class="tok-w"> </span><span class="tok-p">*</span><span class="tok-w"> </span><span class="tok-p">)</span><span class="tok-w"></span></code></pre> 12003</div> 12004</div> 12005<div class="paragraph"> 12006<p>Builds a direct dependency: makes each of <em>targets1</em> depend on each of 12007<em>targets2</em>. Generally, <em>targets1</em> will be rebuilt if <em>targets2</em> are 12008themselves rebuilt or are newer than <em>targets1</em>.</p> 12009</div> 12010</div> 12011<div class="sect5"> 12012<h6 id="jam.language.rules.builtins.dependency_building._includes__"><a class="anchor" href="#jam.language.rules.builtins.dependency_building._includes__"></a><code>INCLUDES</code></h6> 12013<div class="listingblock"> 12014<div class="content"> 12015<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-k">rule</span><span class="tok-w"> </span><span class="tok-nf">INCLUDES</span><span class="tok-w"> </span><span class="tok-p">(</span><span class="tok-w"> </span><span class="tok-nv">targets1</span><span class="tok-w"> </span><span class="tok-p">*</span><span class="tok-w"> </span><span class="tok-p">:</span><span class="tok-w"> </span><span class="tok-nv">targets2</span><span class="tok-w"> </span><span class="tok-p">*</span><span class="tok-w"> </span><span class="tok-p">)</span><span class="tok-w"></span></code></pre> 12016</div> 12017</div> 12018<div class="paragraph"> 12019<p>Builds a sibling dependency: makes any target that depends on any of 12020<em>targets1</em> also depend on each of <em>targets2</em>. This reflects the 12021dependencies that arise when one source file includes another: the 12022object built from the source file depends both on the original and 12023included source file, but the two sources files don’t depend on each 12024other. For example:</p> 12025</div> 12026<div class="listingblock"> 12027<div class="content"> 12028<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-nb">DEPENDS</span><span class="tok-w"> </span>foo.o<span class="tok-w"> </span>:<span class="tok-w"> </span>foo.c<span class="tok-w"> </span>;<span class="tok-w"></span> 12029<span class="tok-nb">INCLUDES</span><span class="tok-w"> </span>foo.c<span class="tok-w"> </span>:<span class="tok-w"> </span>foo.h<span class="tok-w"> </span>;<span class="tok-w"></span></code></pre> 12030</div> 12031</div> 12032<div class="paragraph"> 12033<p><code>foo.o</code> depends on <code>foo.c</code> and <code>foo.h</code> in this example.</p> 12034</div> 12035</div> 12036</div> 12037<div class="sect4"> 12038<h5 id="jam.language.rules.builtins.modifying_binding"><a class="anchor" href="#jam.language.rules.builtins.modifying_binding"></a>Modifying Binding</h5> 12039<div class="paragraph"> 12040<p>The six rules <code>ALWAYS</code>, <code>LEAVES</code>, <code>NOCARE</code>, <code>NOTFILE</code>, <code>NOUPDATE</code>, and 12041<code>TEMPORARY</code> modify the dependency graph so that <code>b2</code> treats the targets 12042differently during its target binding phase. See Binding above. 12043Normally, <code>b2</code> updates a target if it is missing, if its filesystem 12044modification time is older than any of its dependencies (recursively), 12045or if any of its dependencies are being updated. This basic behavior can 12046be changed by invoking the following rules:</p> 12047</div> 12048<div class="sect5"> 12049<h6 id="jam.language.rules.builtins.modifying_binding._always__"><a class="anchor" href="#jam.language.rules.builtins.modifying_binding._always__"></a><code>ALWAYS</code></h6> 12050<div class="listingblock"> 12051<div class="content"> 12052<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-k">rule</span><span class="tok-w"> </span><span class="tok-nf">ALWAYS</span><span class="tok-w"> </span><span class="tok-p">(</span><span class="tok-w"> </span><span class="tok-nv">targets</span><span class="tok-w"> </span><span class="tok-p">*</span><span class="tok-w"> </span><span class="tok-p">)</span><span class="tok-w"></span></code></pre> 12053</div> 12054</div> 12055<div class="paragraph"> 12056<p>Causes <em>targets</em> to be rebuilt regardless of whether they are up-to-date 12057(they must still be in the dependency graph). This is used for the clean 12058and uninstall targets, as they have no dependencies and would otherwise 12059appear never to need building. It is best applied to targets that are 12060also <code>NOTFILE</code> targets, but it can also be used to force a real file to 12061be updated as well.</p> 12062</div> 12063</div> 12064<div class="sect5"> 12065<h6 id="jam.language.rules.builtins.modifying_binding._leaves__"><a class="anchor" href="#jam.language.rules.builtins.modifying_binding._leaves__"></a><code>LEAVES</code></h6> 12066<div class="listingblock"> 12067<div class="content"> 12068<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-k">rule</span><span class="tok-w"> </span><span class="tok-nf">LEAVES</span><span class="tok-w"> </span><span class="tok-p">(</span><span class="tok-w"> </span><span class="tok-nv">targets</span><span class="tok-w"> </span><span class="tok-p">*</span><span class="tok-w"> </span><span class="tok-p">)</span><span class="tok-w"></span></code></pre> 12069</div> 12070</div> 12071<div class="paragraph"> 12072<p>Makes each of <em>targets</em> depend only on its leaf sources, and not on any 12073intermediate targets. This makes it immune to its dependencies being 12074updated, as the "leaf" dependencies are those without their own 12075dependencies and without updating actions. This allows a target to be 12076updated only if original source files change.</p> 12077</div> 12078</div> 12079<div class="sect5"> 12080<h6 id="jam.language.rules.builtins.modifying_binding._nocare__"><a class="anchor" href="#jam.language.rules.builtins.modifying_binding._nocare__"></a><code>NOCARE</code></h6> 12081<div class="listingblock"> 12082<div class="content"> 12083<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-k">rule</span><span class="tok-w"> </span><span class="tok-nf">NOCARE</span><span class="tok-w"> </span><span class="tok-p">(</span><span class="tok-w"> </span><span class="tok-nv">targets</span><span class="tok-w"> </span><span class="tok-p">*</span><span class="tok-w"> </span><span class="tok-p">)</span><span class="tok-w"></span></code></pre> 12084</div> 12085</div> 12086<div class="paragraph"> 12087<p>Causes <code>b2</code> to ignore <em>targets</em> that neither can be found nor have 12088updating actions to build them. Normally for such targets <code>b2</code> issues a 12089warning and then skips other targets that depend on these missing 12090targets. The <code>HdrRule</code> in <code>Jambase</code> uses <code>NOCARE</code> on the header file 12091names found during header file scanning, to let <code>b2</code> know that the 12092included files may not exist. For example, if an <code>#include</code> is within an 12093<code>#ifdef</code>, the included file may not actually be around.</p> 12094</div> 12095<div class="admonitionblock warning"> 12096<table> 12097<tr> 12098<td class="icon"> 12099<div class="title">⚠</div> 12100</td> 12101<td class="content"> 12102For targets with build actions: if their build actions exit with a 12103nonzero return code, dependent targets will still be built. 12104</td> 12105</tr> 12106</table> 12107</div> 12108</div> 12109<div class="sect5"> 12110<h6 id="jam.language.rules.builtins.modifying_binding._notfile__"><a class="anchor" href="#jam.language.rules.builtins.modifying_binding._notfile__"></a><code>NOTFILE</code></h6> 12111<div class="listingblock"> 12112<div class="content"> 12113<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-k">rule</span><span class="tok-w"> </span><span class="tok-nf">NOTFILE</span><span class="tok-w"> </span><span class="tok-p">(</span><span class="tok-w"> </span><span class="tok-nv">targets</span><span class="tok-w"> </span><span class="tok-p">*</span><span class="tok-w"> </span><span class="tok-p">)</span><span class="tok-w"></span></code></pre> 12114</div> 12115</div> 12116<div class="paragraph"> 12117<p>Marks <em>targets</em> as pseudo-targets and not real files. No timestamp is 12118checked, and so the actions on such a target are only executed if the 12119target’s dependencies are updated, or if the target is also marked with 12120<code>ALWAYS</code>. The default <code>b2</code> target <code>all</code> is a pseudo-target In 12121<code>Jambase</code>, <code>NOTFILE</code> is used to define several addition convenient 12122pseudo-targets</p> 12123</div> 12124</div> 12125<div class="sect5"> 12126<h6 id="jam.language.rules.builtins.modifying_binding._noupdate__"><a class="anchor" href="#jam.language.rules.builtins.modifying_binding._noupdate__"></a><code>NOUPDATE</code></h6> 12127<div class="listingblock"> 12128<div class="content"> 12129<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-k">rule</span><span class="tok-w"> </span><span class="tok-nf">NOUPDATE</span><span class="tok-w"> </span><span class="tok-p">(</span><span class="tok-w"> </span><span class="tok-nv">targets</span><span class="tok-w"> </span><span class="tok-p">*</span><span class="tok-w"> </span><span class="tok-p">)</span><span class="tok-w"></span></code></pre> 12130</div> 12131</div> 12132<div class="paragraph"> 12133<p>Causes the timestamps on <em>targets</em> to be ignored. This has two effects: 12134first, once the target has been created it will never be updated; 12135second, manually updating target will not cause other targets to be 12136updated. In <code>Jambase</code>, for example, this rule is applied to directories 12137by the <code>MkDir</code> rule, because <code>MkDir</code> only cares that the target 12138directory exists, not when it has last been updated.</p> 12139</div> 12140</div> 12141<div class="sect5"> 12142<h6 id="jam.language.rules.builtins.modifying_binding._temporary__"><a class="anchor" href="#jam.language.rules.builtins.modifying_binding._temporary__"></a><code>TEMPORARY</code></h6> 12143<div class="listingblock"> 12144<div class="content"> 12145<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-k">rule</span><span class="tok-w"> </span><span class="tok-nf">TEMPORARY</span><span class="tok-w"> </span><span class="tok-p">(</span><span class="tok-w"> </span><span class="tok-nv">targets</span><span class="tok-w"> </span><span class="tok-p">*</span><span class="tok-w"> </span><span class="tok-p">)</span><span class="tok-w"></span></code></pre> 12146</div> 12147</div> 12148<div class="paragraph"> 12149<p>Marks <em>targets</em> as temporary, allowing them to be removed after other 12150targets that depend upon them have been updated. If a <code>TEMPORARY</code> target 12151is missing, <code>b2</code> uses the timestamp of the target’s parent. <code>Jambase</code> 12152uses <code>TEMPORARY</code> to mark object files that are archived in a library 12153after they are built, so that they can be deleted after they are 12154archived.</p> 12155</div> 12156</div> 12157<div class="sect5"> 12158<h6 id="jam.language.rules.builtins.modifying_binding._fail_expected__"><a class="anchor" href="#jam.language.rules.builtins.modifying_binding._fail_expected__"></a><code>FAIL_EXPECTED</code></h6> 12159<div class="listingblock"> 12160<div class="content"> 12161<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-k">rule</span><span class="tok-w"> </span><span class="tok-nf">FAIL_EXPECTED</span><span class="tok-w"> </span><span class="tok-p">(</span><span class="tok-w"> </span><span class="tok-nv">targets</span><span class="tok-w"> </span><span class="tok-p">*</span><span class="tok-w"> </span><span class="tok-p">)</span><span class="tok-w"></span></code></pre> 12162</div> 12163</div> 12164<div class="paragraph"> 12165<p>For handling targets whose build actions are expected to fail (e.g. when 12166testing that assertions or compile-time type checking work properly), 12167Boost Jam supplies the <code>FAIL_EXPECTED</code> rule in the same style as 12168<code>NOCARE</code>, et. al. During target updating, the return code of the build 12169actions for arguments to <code>FAIL_EXPECTED</code> is inverted: if it fails, 12170building of dependent targets continues as though it succeeded. If it 12171succeeds, dependent targets are skipped.</p> 12172</div> 12173</div> 12174<div class="sect5"> 12175<h6 id="jam.language.rules.builtins.modifying_binding._rmold__"><a class="anchor" href="#jam.language.rules.builtins.modifying_binding._rmold__"></a><code>RMOLD</code></h6> 12176<div class="listingblock"> 12177<div class="content"> 12178<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-k">rule</span><span class="tok-w"> </span><span class="tok-nf">RMOLD</span><span class="tok-w"> </span><span class="tok-p">(</span><span class="tok-w"> </span><span class="tok-nv">targets</span><span class="tok-w"> </span><span class="tok-p">*</span><span class="tok-w"> </span><span class="tok-p">)</span><span class="tok-w"></span></code></pre> 12179</div> 12180</div> 12181<div class="paragraph"> 12182<p><code>B2</code> removes any target files that may exist on disk when the rule used 12183to build those targets fails. However, targets whose dependencies fail 12184to build are not removed by default. The <code>RMOLD</code> rule causes its 12185arguments to be removed if any of their dependencies fail to build.</p> 12186</div> 12187</div> 12188<div class="sect5"> 12189<h6 id="jam.language.rules.builtins.modifying_binding._isfile__"><a class="anchor" href="#jam.language.rules.builtins.modifying_binding._isfile__"></a><code>ISFILE</code></h6> 12190<div class="listingblock"> 12191<div class="content"> 12192<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-k">rule</span><span class="tok-w"> </span><span class="tok-nf">ISFILE</span><span class="tok-w"> </span><span class="tok-p">(</span><span class="tok-w"> </span><span class="tok-nv">targets</span><span class="tok-w"> </span><span class="tok-p">*</span><span class="tok-w"> </span><span class="tok-p">)</span><span class="tok-w"></span></code></pre> 12193</div> 12194</div> 12195<div class="paragraph"> 12196<p><code>ISFILE</code> marks targets as required to be files. This changes the way 12197<code>b2</code> searches for the target such that it ignores matches for file 12198system items that are not files, like directories. This makes it 12199possible to avoid <code>#include "exception"</code> matching if one happens to have 12200a directory named exception in the header search path.</p> 12201</div> 12202<div class="admonitionblock warning"> 12203<table> 12204<tr> 12205<td class="icon"> 12206<div class="title">⚠</div> 12207</td> 12208<td class="content"> 12209This is currently not fully implemented. 12210</td> 12211</tr> 12212</table> 12213</div> 12214</div> 12215</div> 12216<div class="sect4"> 12217<h5 id="jam.language.rules.builtins.utility"><a class="anchor" href="#jam.language.rules.builtins.utility"></a>Utility</h5> 12218<div class="paragraph"> 12219<p>The two rules <code>ECHO</code> and <code>EXIT</code> are utility rules, used only in `b2`s 12220parsing phase.</p> 12221</div> 12222<div class="sect5"> 12223<h6 id="jam.language.rules.builtins.utility._echo__"><a class="anchor" href="#jam.language.rules.builtins.utility._echo__"></a><code>ECHO</code></h6> 12224<div class="listingblock"> 12225<div class="content"> 12226<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-k">rule</span><span class="tok-w"> </span><span class="tok-nf">ECHO</span><span class="tok-w"> </span><span class="tok-p">(</span><span class="tok-w"> </span><span class="tok-nv">args</span><span class="tok-w"> </span><span class="tok-p">*</span><span class="tok-w"> </span><span class="tok-p">)</span><span class="tok-w"></span></code></pre> 12227</div> 12228</div> 12229<div class="paragraph"> 12230<p>Blurts out the message <em>args</em> to stdout.</p> 12231</div> 12232</div> 12233<div class="sect5"> 12234<h6 id="jam.language.rules.builtins.utility._exit__"><a class="anchor" href="#jam.language.rules.builtins.utility._exit__"></a><code>EXIT</code></h6> 12235<div class="listingblock"> 12236<div class="content"> 12237<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-k">rule</span><span class="tok-w"> </span><span class="tok-nf">EXIT</span><span class="tok-w"> </span><span class="tok-p">(</span><span class="tok-w"> </span><span class="tok-nv">message</span><span class="tok-w"> </span><span class="tok-p">*</span><span class="tok-w"> </span><span class="tok-p">:</span><span class="tok-w"> </span><span class="tok-nv">result-value</span><span class="tok-w"> </span><span class="tok-p">?</span><span class="tok-w"> </span><span class="tok-p">)</span><span class="tok-w"></span></code></pre> 12238</div> 12239</div> 12240<div class="paragraph"> 12241<p>Blurts out the <em>message</em> to stdout and then exits with a failure status 12242if no <em>result-value</em> is given, otherwise it exits with the given 12243<em>result-value</em>.</p> 12244</div> 12245<div class="paragraph"> 12246<p><code>Echo</code>, <code>echo</code>, <code>Exit</code>, and <code>exit</code> are accepted as aliases for 12247<code>ECHO</code> and <code>EXIT</code>, since it is hard to tell that these are built-in 12248rules and not part of the language, like <code>include</code>.</p> 12249</div> 12250</div> 12251<div class="sect5"> 12252<h6 id="jam.language.rules.builtins.utility._glob__"><a class="anchor" href="#jam.language.rules.builtins.utility._glob__"></a><code>GLOB</code></h6> 12253<div class="paragraph"> 12254<p>The <code>GLOB</code> rule does filename globing</p> 12255</div> 12256<div class="listingblock"> 12257<div class="content"> 12258<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-k">rule</span><span class="tok-w"> </span><span class="tok-nf">GLOB</span><span class="tok-w"> </span><span class="tok-p">(</span><span class="tok-w"> </span><span class="tok-nv">directories</span><span class="tok-w"> </span><span class="tok-p">*</span><span class="tok-w"> </span><span class="tok-p">:</span><span class="tok-w"> </span><span class="tok-nv">patterns</span><span class="tok-w"> </span><span class="tok-p">*</span><span class="tok-w"> </span><span class="tok-p">:</span><span class="tok-w"> </span><span class="tok-nv">downcase-opt</span><span class="tok-w"> </span><span class="tok-p">?</span><span class="tok-w"> </span><span class="tok-p">)</span><span class="tok-w"></span></code></pre> 12259</div> 12260</div> 12261<div class="paragraph"> 12262<p>Using the same wildcards as for the patterns in the switch statement. It 12263is invoked by being used as an argument to a rule invocation inside of 12264"[ ]". For example: <code>FILES = [ GLOB dir1 dir2 : *.c *.h ]</code> sets <code>FILES</code> to 12265the list of C source 12266and header files in <code>dir1</code> and <code>dir2</code>. The resulting filenames are the 12267full pathnames, including the directory, but the pattern is applied only 12268to the file name without the directory.</p> 12269</div> 12270<div class="paragraph"> 12271<p>If <em>downcase-opt</em> is supplied, filenames are converted to all-lowercase 12272before matching against the pattern; you can use this to do 12273case-insensitive matching using lowercase patterns. The paths returned 12274will still have mixed case if the OS supplies them. On Windows NT and 12275Cygwin, and OpenVMS, filenames are always down-cased before matching.</p> 12276</div> 12277</div> 12278<div class="sect5"> 12279<h6 id="jam.language.rules.builtins.utility._glob_archive__"><a class="anchor" href="#jam.language.rules.builtins.utility._glob_archive__"></a><code>GLOB_ARCHIVE</code></h6> 12280<div class="paragraph"> 12281<p>The <code>GLOB_ARCHIVE</code> rule does name globing of object archive members.</p> 12282</div> 12283<div class="listingblock"> 12284<div class="content"> 12285<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-k">rule</span><span class="tok-w"> </span><span class="tok-nf">GLOB_ARCHIVE</span><span class="tok-w"> </span><span class="tok-p">(</span><span class="tok-w"> </span><span class="tok-nv">archives</span><span class="tok-w"> </span><span class="tok-p">*</span><span class="tok-w"> </span><span class="tok-p">:</span><span class="tok-w"> </span><span class="tok-nv">member-patterns</span><span class="tok-w"> </span><span class="tok-p">*</span><span class="tok-w"> </span><span class="tok-p">:</span><span class="tok-w"> </span><span class="tok-nv">downcase-opt</span><span class="tok-w"> </span><span class="tok-p">?</span><span class="tok-w"> </span><span class="tok-p">:</span><span class="tok-w"> </span><span class="tok-nv">symbol-patterns</span><span class="tok-w"> </span><span class="tok-p">?</span><span class="tok-w"> </span><span class="tok-p">)</span><span class="tok-w"></span></code></pre> 12286</div> 12287</div> 12288<div class="paragraph"> 12289<p>Similarly to <code>GLOB</code>, this rule is used to match names of member files in 12290an archive (static object library). List of successfully matched members 12291is returned or null otherwise. The resulting member names are qualified 12292with pathname of the containing archive in the form 12293<code>archive-path(member-name)</code>. Member patterns are for matching member 12294name only; when no wildcards specified — an exact match is assumed. 12295Member names generally correspond to object file names and as such are 12296platform-specific — use of platform-defined object suffix in the 12297matching patterns can allow for portability.</p> 12298</div> 12299<div class="paragraph"> 12300<p>If <em>downcase-opt</em> is supplied, the member names are converted to 12301all-lowercase before matching against the pattern; you can use this to 12302do case-insensitive matching using lowercase patterns. The paths 12303returned will still have mixed case if the OS supplies them. On Windows 12304NT, Cygwin, and OpenVMS, filenames are always down-cased before matching.</p> 12305</div> 12306<div class="paragraph"> 12307<p>Additionally, members can be matched with symbol/function patterns on 12308supported platforms (currently, OpenVMS only). In this case, members 12309containing the matching symbols are returned. Member and symbol patterns 12310are applied as OR conditions, with member patterns taking precedence. On 12311unsupported platforms, null is returned when any symbol patterns are 12312specified.</p> 12313</div> 12314</div> 12315<div class="sect5"> 12316<h6 id="jam.language.rules.builtins.utility._match__"><a class="anchor" href="#jam.language.rules.builtins.utility._match__"></a><code>MATCH</code></h6> 12317<div class="paragraph"> 12318<p>The <code>MATCH</code> rule does pattern matching.</p> 12319</div> 12320<div class="listingblock"> 12321<div class="content"> 12322<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-k">rule</span><span class="tok-w"> </span><span class="tok-nf">MATCH</span><span class="tok-w"> </span><span class="tok-p">(</span><span class="tok-w"> </span><span class="tok-nv">regexps</span><span class="tok-w"> </span><span class="tok-p">+</span><span class="tok-w"> </span><span class="tok-p">:</span><span class="tok-w"> </span><span class="tok-nv">list</span><span class="tok-w"> </span><span class="tok-p">*</span><span class="tok-w"> </span><span class="tok-p">)</span><span class="tok-w"></span></code></pre> 12323</div> 12324</div> 12325<div class="paragraph"> 12326<p>Matches the <code>egrep</code>(1) style regular expressions <em>regexps</em> against the 12327strings in <em>list</em>. The result is a list of matching <code>()</code> subexpressions 12328for each string in <em>list</em>, and for each regular expression in <em>regexps</em>.</p> 12329</div> 12330</div> 12331<div class="sect5"> 12332<h6 id="jam.language.rules.builtins.utility._backtrace__"><a class="anchor" href="#jam.language.rules.builtins.utility._backtrace__"></a><code>BACKTRACE</code></h6> 12333<div class="listingblock"> 12334<div class="content"> 12335<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-k">rule</span><span class="tok-w"> </span><span class="tok-nf">BACKTRACE</span><span class="tok-w"> </span><span class="tok-p">(</span><span class="tok-w"> </span><span class="tok-p">)</span><span class="tok-w"></span></code></pre> 12336</div> 12337</div> 12338<div class="paragraph"> 12339<p>Returns a list of quadruples: <em>filename</em> <em>line</em> <em>module</em> <em>rulename</em>…​, 12340describing each shallower level of the call stack. This rule can be used 12341to generate useful diagnostic messages from Jam rules.</p> 12342</div> 12343</div> 12344<div class="sect5"> 12345<h6 id="jam.language.rules.builtins.utility._update__"><a class="anchor" href="#jam.language.rules.builtins.utility._update__"></a><code>UPDATE</code></h6> 12346<div class="listingblock"> 12347<div class="content"> 12348<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-k">rule</span><span class="tok-w"> </span><span class="tok-nf">UPDATE</span><span class="tok-w"> </span><span class="tok-p">(</span><span class="tok-w"> </span><span class="tok-nv">targets</span><span class="tok-w"> </span><span class="tok-p">*</span><span class="tok-w"> </span><span class="tok-p">)</span><span class="tok-w"></span></code></pre> 12349</div> 12350</div> 12351<div class="paragraph"> 12352<p>Classic jam treats any non-option element of command line as a name of 12353target to be updated. This prevented more sophisticated handling of 12354command line. This is now enabled again but with additional changes to 12355the <code>UPDATE</code> rule to allow for the flexibility of changing the list of 12356targets to update. The UPDATE rule has two effects:</p> 12357</div> 12358<div class="olist arabic"> 12359<ol class="arabic"> 12360<li> 12361<p>It clears the list of targets to update, and</p> 12362</li> 12363<li> 12364<p>Causes the specified targets to be updated.</p> 12365</li> 12366</ol> 12367</div> 12368<div class="paragraph"> 12369<p>If no target was specified with the <code>UPDATE</code> rule, no targets will be 12370updated. To support changing of the update list in more useful ways, the 12371rule also returns the targets previously in the update list. This makes 12372it possible to add targets as such:</p> 12373</div> 12374<div class="listingblock"> 12375<div class="content"> 12376<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-k">local</span><span class="tok-w"> </span>previous-updates<span class="tok-w"> </span>=<span class="tok-w"> </span>[<span class="tok-w"> </span><span class="tok-nb">UPDATE</span><span class="tok-w"> </span>]<span class="tok-w"> </span>;<span class="tok-w"></span> 12377<span class="tok-nb">UPDATE</span><span class="tok-w"> </span><span class="tok-si">$(previous-updates)</span><span class="tok-w"> </span>a-new-target<span class="tok-w"> </span>;<span class="tok-w"></span></code></pre> 12378</div> 12379</div> 12380</div> 12381<div class="sect5"> 12382<h6 id="jam.language.rules.builtins.utility._w32_getreg__"><a class="anchor" href="#jam.language.rules.builtins.utility._w32_getreg__"></a><code>W32_GETREG</code></h6> 12383<div class="listingblock"> 12384<div class="content"> 12385<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-k">rule</span><span class="tok-w"> </span><span class="tok-nf">W32_GETREG</span><span class="tok-w"> </span><span class="tok-p">(</span><span class="tok-w"> </span><span class="tok-nv">path</span><span class="tok-w"> </span><span class="tok-p">:</span><span class="tok-w"> </span><span class="tok-nv">data</span><span class="tok-w"> </span><span class="tok-p">?</span><span class="tok-w"> </span><span class="tok-p">)</span><span class="tok-w"></span></code></pre> 12386</div> 12387</div> 12388<div class="paragraph"> 12389<p>Defined only for win32 platform. It reads the registry of Windows. 12390'<em>path</em>' is the location of the information, and '<em>data</em>' is the name of 12391the value which we want to get. If '<em>data</em>' is omitted, the default 12392value of '<em>path</em>' will be returned. The '<em>path</em>' value must conform to 12393MS key path format and must be prefixed with one of the predefined root 12394keys. As usual,</p> 12395</div> 12396<div class="ulist"> 12397<ul> 12398<li> 12399<p><code>HKLM</code> is equivalent to <code>HKEY_LOCAL_MACHINE</code>.</p> 12400</li> 12401<li> 12402<p><code>HKCU</code> is equivalent to <code>HKEY_CURRENT_USER</code>.</p> 12403</li> 12404<li> 12405<p><code>HKCR</code> is equivalent to <code>HKEY_CLASSES_ROOT</code>.</p> 12406</li> 12407</ul> 12408</div> 12409<div class="paragraph"> 12410<p>Other predefined root keys are not supported.</p> 12411</div> 12412<div class="paragraph"> 12413<p>Currently supported data types : <code>REG_DWORD</code>, <code>REG_SZ</code>, 12414<code>REG_EXPAND_SZ</code>, <code>REG_MULTI_SZ</code>. The data with <code>REG_DWORD</code> type 12415will be turned into a string, <code>REG_MULTI_SZ</code> into a list of strings, 12416and for those with <code>REG_EXPAND_SZ</code> type environment variables in it 12417will be replaced with their defined values. The data with <code>REG_SZ</code> 12418type and other unsupported types will be put into a string without 12419modification. If it can’t receive the value of the data, it just return 12420an empty list. For example,</p> 12421</div> 12422<div class="listingblock"> 12423<div class="content"> 12424<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-k">local</span><span class="tok-w"> </span>PSDK-location<span class="tok-w"> </span>=<span class="tok-w"></span> 12425<span class="tok-w"> </span>[<span class="tok-w"> </span><span class="tok-nb">W32_GETREG</span><span class="tok-w"> </span>HKEY_LOCAL_MACHINE\\SOFTWARE\\Microsoft\\MicrosoftSDK\\Directories<span class="tok-w"> </span>:<span class="tok-w"> </span>"Install<span class="tok-w"> </span>Dir"<span class="tok-w"> </span>]<span class="tok-w"> </span>;<span class="tok-w"></span></code></pre> 12426</div> 12427</div> 12428</div> 12429<div class="sect5"> 12430<h6 id="jam.language.rules.builtins.utility._w32_getregnames__"><a class="anchor" href="#jam.language.rules.builtins.utility._w32_getregnames__"></a><code>W32_GETREGNAMES</code></h6> 12431<div class="listingblock"> 12432<div class="content"> 12433<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-k">rule</span><span class="tok-w"> </span><span class="tok-nf">W32_GETREGNAMES</span><span class="tok-w"> </span><span class="tok-p">(</span><span class="tok-w"> </span><span class="tok-nv">path</span><span class="tok-w"> </span><span class="tok-p">:</span><span class="tok-w"> </span><span class="tok-nv">result-type</span><span class="tok-w"> </span><span class="tok-p">)</span><span class="tok-w"></span></code></pre> 12434</div> 12435</div> 12436<div class="paragraph"> 12437<p>Defined only for win32 platform. It reads the registry of Windows. 12438'<em>path</em>' is the location of the information, and '<em>result-type</em>' is 12439either <code>subkeys</code> or <code>values</code>. For more information on '<em>path</em>' 12440format and constraints, please see <code>W32_GETREG</code>.</p> 12441</div> 12442<div class="paragraph"> 12443<p>Depending on '<em>result-type</em>', the rule returns one of the following:</p> 12444</div> 12445<div class="dlist"> 12446<dl> 12447<dt class="hdlist1"><code>subkeys</code></dt> 12448<dd> 12449<p>Names of all direct sub-keys of '<em>path</em>'.</p> 12450</dd> 12451<dt class="hdlist1"><code>values</code></dt> 12452<dd> 12453<p>Names of values contained in registry key given by '<em>path</em>'. The 12454"default" value of the key appears in the returned list only if its 12455value has been set in the registry.</p> 12456</dd> 12457</dl> 12458</div> 12459<div class="paragraph"> 12460<p>If '<em>result-type</em>' is not recognized, or requested data cannot be 12461retrieved, the rule returns an empty list. Example:</p> 12462</div> 12463<div class="listingblock"> 12464<div class="content"> 12465<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-k">local</span><span class="tok-w"> </span>key<span class="tok-w"> </span>=<span class="tok-w"> </span>"HKEY_LOCAL_MACHINE\\SOFTWARE\\Microsoft\\Windows\\CurrentVersion\\App<span class="tok-w"> </span>Paths"<span class="tok-w"> </span>;<span class="tok-w"></span> 12466<span class="tok-k">local</span><span class="tok-w"> </span>subkeys<span class="tok-w"> </span>=<span class="tok-w"> </span>[<span class="tok-w"> </span><span class="tok-nb">W32_GETREGNAMES</span><span class="tok-w"> </span>"<span class="tok-si">$(key)</span>"<span class="tok-w"> </span>:<span class="tok-w"> </span>subkeys<span class="tok-w"> </span>]<span class="tok-w"> </span>;<span class="tok-w"></span> 12467<span class="tok-k">for</span><span class="tok-w"> </span><span class="tok-k">local</span><span class="tok-w"> </span>subkey<span class="tok-w"> </span><span class="tok-k">in</span><span class="tok-w"> </span><span class="tok-si">$(subkeys)</span><span class="tok-w"></span> 12468{<span class="tok-w"></span> 12469<span class="tok-w"> </span><span class="tok-k">local</span><span class="tok-w"> </span>values<span class="tok-w"> </span>=<span class="tok-w"> </span>[<span class="tok-w"> </span><span class="tok-nb">W32_GETREGNAMES</span><span class="tok-w"> </span>"<span class="tok-si">$(key)</span>\\<span class="tok-si">$(subkey)</span>"<span class="tok-w"> </span>:<span class="tok-w"> </span>values<span class="tok-w"> </span>]<span class="tok-w"> </span>;<span class="tok-w"></span> 12470<span class="tok-w"> </span><span class="tok-k">for</span><span class="tok-w"> </span><span class="tok-k">local</span><span class="tok-w"> </span>value<span class="tok-w"> </span><span class="tok-k">in</span><span class="tok-w"> </span><span class="tok-si">$(values)</span><span class="tok-w"></span> 12471<span class="tok-w"> </span>{<span class="tok-w"></span> 12472<span class="tok-w"> </span><span class="tok-k">local</span><span class="tok-w"> </span>data<span class="tok-w"> </span>=<span class="tok-w"> </span>[<span class="tok-w"> </span><span class="tok-nb">W32_GETREG</span><span class="tok-w"> </span>"<span class="tok-si">$(key)</span>\\<span class="tok-si">$(subkey)</span>"<span class="tok-w"> </span>:<span class="tok-w"> </span>"<span class="tok-si">$(value)</span>"<span class="tok-w"> </span>]<span class="tok-w"> </span>;<span class="tok-w"></span> 12473<span class="tok-w"> </span><span class="tok-nb">ECHO</span><span class="tok-w"> </span>"Registry<span class="tok-w"> </span>path:<span class="tok-w"> </span>"<span class="tok-w"> </span><span class="tok-si">$(key)</span>\\<span class="tok-si">$(subkey)</span><span class="tok-w"> </span>":"<span class="tok-w"> </span><span class="tok-si">$(value)</span><span class="tok-w"> </span>"="<span class="tok-w"> </span><span class="tok-si">$(data)</span><span class="tok-w"> </span>;<span class="tok-w"></span> 12474<span class="tok-w"> </span>}<span class="tok-w"></span> 12475}<span class="tok-w"></span></code></pre> 12476</div> 12477</div> 12478</div> 12479<div class="sect5"> 12480<h6 id="jam.language.rules.builtins.utility._shell__"><a class="anchor" href="#jam.language.rules.builtins.utility._shell__"></a><code>SHELL</code></h6> 12481<div class="listingblock"> 12482<div class="content"> 12483<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-k">rule</span><span class="tok-w"> </span><span class="tok-nf">SHELL</span><span class="tok-w"> </span><span class="tok-p">(</span><span class="tok-w"> </span><span class="tok-nv">command</span><span class="tok-w"> </span><span class="tok-p">:</span><span class="tok-w"> </span><span class="tok-p">*</span><span class="tok-w"> </span><span class="tok-p">)</span><span class="tok-w"></span></code></pre> 12484</div> 12485</div> 12486<div class="paragraph"> 12487<p><code>SHELL</code> executes <em>command</em>, and then returns the standard output of 12488<em>command</em>. <code>SHELL</code> only works on platforms with a <code>popen()</code> function in 12489the C library. On platforms without a working <code>popen()</code> function, 12490<code>SHELL</code> is implemented as a no-op. <code>SHELL</code> works on Unix, MacOS X, and 12491most Windows compilers. <code>SHELL</code> is a no-op on Metrowerks compilers under 12492Windows. There is a variable set of allowed options as additional 12493arguments:</p> 12494</div> 12495<div class="dlist"> 12496<dl> 12497<dt class="hdlist1"><code>exit-status</code></dt> 12498<dd> 12499<p>In addition to the output the result status of the executed command is 12500returned as a second element of the result.</p> 12501</dd> 12502<dt class="hdlist1"><code>no-output</code></dt> 12503<dd> 12504<p>Don’t capture the output of the command. Instead an empty ("") string 12505value is returned in place of the output.</p> 12506</dd> 12507<dt class="hdlist1"><code>strip-eol</code></dt> 12508<dd> 12509<p>Remove trailing end-of-line character from output, if any.</p> 12510</dd> 12511</dl> 12512</div> 12513<div class="paragraph"> 12514<p>Because the Perforce/Jambase defines a <code>SHELL</code> rule which hides the 12515builtin rule, <code>COMMAND</code> can be used as an alias for <code>SHELL</code> in such a 12516case.</p> 12517</div> 12518</div> 12519<div class="sect5"> 12520<h6 id="jam.language.rules.builtins.utility._md5__"><a class="anchor" href="#jam.language.rules.builtins.utility._md5__"></a><code>MD5</code></h6> 12521<div class="listingblock"> 12522<div class="content"> 12523<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-k">rule</span><span class="tok-w"> </span><span class="tok-nf">MD5</span><span class="tok-w"> </span><span class="tok-p">(</span><span class="tok-w"> </span><span class="tok-nv">string</span><span class="tok-w"> </span><span class="tok-p">)</span><span class="tok-w"></span></code></pre> 12524</div> 12525</div> 12526<div class="paragraph"> 12527<p><code>MD5</code> computes the MD5 hash of the string passed as parameter and 12528returns it.</p> 12529</div> 12530</div> 12531<div class="sect5"> 12532<h6 id="jam.language.rules.builtins.utility._split_by_characters__"><a class="anchor" href="#jam.language.rules.builtins.utility._split_by_characters__"></a><code>SPLIT_BY_CHARACTERS</code></h6> 12533<div class="listingblock"> 12534<div class="content"> 12535<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-k">rule</span><span class="tok-w"> </span><span class="tok-nf">SPLIT_BY_CHARACTERS</span><span class="tok-w"> </span><span class="tok-p">(</span><span class="tok-w"> </span><span class="tok-nv">string</span><span class="tok-w"> </span><span class="tok-p">:</span><span class="tok-w"> </span><span class="tok-nv">delimiters</span><span class="tok-w"> </span><span class="tok-p">)</span><span class="tok-w"></span></code></pre> 12536</div> 12537</div> 12538<div class="paragraph"> 12539<p><code>SPLIT_BY_CHARACTERS</code> splits the specified <em>string</em> on any delimiter 12540character present in <em>delimiters</em> and returns the resulting list.</p> 12541</div> 12542</div> 12543<div class="sect5"> 12544<h6 id="jam.language.rules.builtins.utility._precious__"><a class="anchor" href="#jam.language.rules.builtins.utility._precious__"></a><code>PRECIOUS</code></h6> 12545<div class="listingblock"> 12546<div class="content"> 12547<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-k">rule</span><span class="tok-w"> </span><span class="tok-nf">PRECIOUS</span><span class="tok-w"> </span><span class="tok-p">(</span><span class="tok-w"> </span><span class="tok-nv">targets</span><span class="tok-w"> </span><span class="tok-p">*</span><span class="tok-w"> </span><span class="tok-p">)</span><span class="tok-w"></span></code></pre> 12548</div> 12549</div> 12550<div class="paragraph"> 12551<p>The <code>PRECIOUS</code> rule specifies that each of the targets passed as the 12552arguments should not be removed even if the command updating that target 12553fails.</p> 12554</div> 12555</div> 12556<div class="sect5"> 12557<h6 id="jam.language.rules.builtins.utility._pad__"><a class="anchor" href="#jam.language.rules.builtins.utility._pad__"></a><code>PAD</code></h6> 12558<div class="listingblock"> 12559<div class="content"> 12560<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-k">rule</span><span class="tok-w"> </span><span class="tok-nf">PAD</span><span class="tok-w"> </span><span class="tok-p">(</span><span class="tok-w"> </span><span class="tok-nv">string</span><span class="tok-w"> </span><span class="tok-p">:</span><span class="tok-w"> </span><span class="tok-nv">width</span><span class="tok-w"> </span><span class="tok-p">)</span><span class="tok-w"></span></code></pre> 12561</div> 12562</div> 12563<div class="paragraph"> 12564<p>If <em>string</em> is shorter than <em>width</em> characters, pads it with whitespace 12565characters on the right, and returns the result. Otherwise, returns 12566<em>string</em> unmodified.</p> 12567</div> 12568</div> 12569<div class="sect5"> 12570<h6 id="jam.language.rules.builtins.utility._file_open__"><a class="anchor" href="#jam.language.rules.builtins.utility._file_open__"></a><code>FILE_OPEN</code></h6> 12571<div class="listingblock"> 12572<div class="content"> 12573<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-k">rule</span><span class="tok-w"> </span><span class="tok-nf">FILE_OPEN</span><span class="tok-w"> </span><span class="tok-p">(</span><span class="tok-w"> </span><span class="tok-nv">filename</span><span class="tok-w"> </span><span class="tok-p">:</span><span class="tok-w"> </span><span class="tok-nv">mode</span><span class="tok-w"> </span><span class="tok-p">)</span><span class="tok-w"></span></code></pre> 12574</div> 12575</div> 12576<div class="paragraph"> 12577<p>The <code>FILE_OPEN</code> rule opens the specified file and returns a file 12578descriptor. The <em>mode</em> parameter can be either "w" or "r". Note that at 12579present, only the <code>UPDATE_NOW</code> rule can use the resulting file 12580descriptor number.</p> 12581</div> 12582</div> 12583<div class="sect5"> 12584<h6 id="jam.language.rules.builtins.utility._update_now__"><a class="anchor" href="#jam.language.rules.builtins.utility._update_now__"></a><code>UPDATE_NOW</code></h6> 12585<div class="listingblock"> 12586<div class="content"> 12587<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-k">rule</span><span class="tok-w"> </span><span class="tok-nf">UPDATE_NOW</span><span class="tok-w"> </span><span class="tok-p">(</span><span class="tok-w"> </span><span class="tok-nv">targets</span><span class="tok-w"> </span><span class="tok-p">*</span><span class="tok-w"> </span><span class="tok-p">:</span><span class="tok-w"> </span><span class="tok-nv">log</span><span class="tok-w"> </span><span class="tok-p">?</span><span class="tok-w"> </span><span class="tok-p">:</span><span class="tok-w"> </span><span class="tok-nv">ignore-minus-n</span><span class="tok-w"> </span><span class="tok-p">?</span><span class="tok-w"> </span><span class="tok-p">)</span><span class="tok-w"></span></code></pre> 12588</div> 12589</div> 12590<div class="paragraph"> 12591<p>The <code>UPDATE_NOW</code> caused the specified targets to be updated immediately. 12592If update was successful, non-empty string is returned. The <em>log</em> 12593parameter, if present, specifies a descriptor of a file where all output 12594from building is redirected. If the <em>ignore-minus-n</em> parameter is 12595specified, the targets are updated even if the <code>-n</code> parameter is 12596specified on the command line.</p> 12597</div> 12598</div> 12599</div> 12600</div> 12601<div class="sect3"> 12602<h4 id="jam.language.flow_of_control"><a class="anchor" href="#jam.language.flow_of_control"></a>11.2.5. Flow-of-Control</h4> 12603<div class="paragraph"> 12604<p><code>B2</code> has several simple flow-of-control statements:</p> 12605</div> 12606<div class="listingblock"> 12607<div class="content"> 12608<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-k">for</span><span class="tok-w"> </span>var<span class="tok-w"> </span><span class="tok-k">in</span><span class="tok-w"> </span>list<span class="tok-w"> </span>{<span class="tok-w"> </span>statements<span class="tok-w"> </span>}<span class="tok-w"></span></code></pre> 12609</div> 12610</div> 12611<div class="paragraph"> 12612<p>Executes <em>statements</em> for each element in <em>list</em>, setting the variable 12613<em>var</em> to the element value.</p> 12614</div> 12615<div class="listingblock"> 12616<div class="content"> 12617<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-k">if</span><span class="tok-w"> </span>cond<span class="tok-w"> </span>{<span class="tok-w"> </span>statements<span class="tok-w"> </span>}<span class="tok-w"></span> 12618[<span class="tok-w"> </span><span class="tok-k">else</span><span class="tok-w"> </span>{<span class="tok-w"> </span>statements<span class="tok-w"> </span>}<span class="tok-w"> </span>]<span class="tok-w"></span></code></pre> 12619</div> 12620</div> 12621<div class="paragraph"> 12622<p>Does the obvious; the <code>else</code> clause is optional. <em>cond</em> is built of:</p> 12623</div> 12624<div class="dlist"> 12625<dl> 12626<dt class="hdlist1"><code>a</code></dt> 12627<dd> 12628<p>true if any <em>a</em> element is a non-zero-length string</p> 12629</dd> 12630<dt class="hdlist1"><code>a = b</code></dt> 12631<dd> 12632<p>list <em>a</em> matches list <em>b</em> string-for-string</p> 12633</dd> 12634<dt class="hdlist1"><code>a != b</code></dt> 12635<dd> 12636<p>list <em>a</em> does not match list <em>b</em></p> 12637</dd> 12638<dt class="hdlist1"><code>a < b</code></dt> 12639<dd> 12640<p><em>a[i]</em> string is less than <em>b[i]</em> string, where <em>i</em> is first 12641mismatched element in lists <em>a</em> and <em>b</em></p> 12642</dd> 12643<dt class="hdlist1"><code>a <= b</code></dt> 12644<dd> 12645<p>every <em>a</em> string is less than or equal to its <em>b</em> counterpart</p> 12646</dd> 12647<dt class="hdlist1"><code>a > b</code></dt> 12648<dd> 12649<p><em>a[i]</em> string is greater than <em>b[i]</em> string, where <em>i</em> is first 12650mismatched element</p> 12651</dd> 12652<dt class="hdlist1"><code>a >= b</code></dt> 12653<dd> 12654<p>every <em>a</em> string is greater than or equal to its <em>b</em> counterpart</p> 12655</dd> 12656<dt class="hdlist1"><code>a in b</code></dt> 12657<dd> 12658<p>true if all elements of <em>a</em> can be found in <em>b</em>, or if <em>a</em> has no 12659elements</p> 12660</dd> 12661<dt class="hdlist1"><code>! cond</code></dt> 12662<dd> 12663<p>condition not true</p> 12664</dd> 12665<dt class="hdlist1"><code>cond && cond</code></dt> 12666<dd> 12667<p>conjunction</p> 12668</dd> 12669<dt class="hdlist1"><code>cond || cond</code></dt> 12670<dd> 12671<p>disjunction</p> 12672</dd> 12673<dt class="hdlist1"><code>( cond )</code></dt> 12674<dd> 12675<p>precedence grouping</p> 12676</dd> 12677</dl> 12678</div> 12679<div class="listingblock"> 12680<div class="content"> 12681<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-k">include</span><span class="tok-w"> </span>file<span class="tok-w"> </span>;<span class="tok-w"></span></code></pre> 12682</div> 12683</div> 12684<div class="paragraph"> 12685<p>Causes <code>b2</code> to read the named <em>file</em>. The <em>file</em> is bound like a regular 12686target (see Binding above) but unlike a regular target the include 12687<em>file</em> cannot be built.</p> 12688</div> 12689<div class="paragraph"> 12690<p>The include <em>file</em> is inserted into the input stream during the parsing 12691phase. The primary input file and all the included file(s) are treated 12692as a single file; that is, <code>b2</code> infers no scope boundaries from included 12693files.</p> 12694</div> 12695<div class="listingblock"> 12696<div class="content"> 12697<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-k">local</span><span class="tok-w"> </span>vars<span class="tok-w"> </span>[<span class="tok-w"> </span>=<span class="tok-w"> </span>values<span class="tok-w"> </span>]<span class="tok-w"> </span>;<span class="tok-w"></span></code></pre> 12698</div> 12699</div> 12700<div class="paragraph"> 12701<p>Creates new <em>vars</em> inside to the enclosing <code>{}</code> block, obscuring any 12702previous values they might have. The previous values for vars are 12703restored when the current block ends. Any rule called or file included 12704will see the local and not the previous value (this is sometimes called 12705Dynamic Scoping). The local statement may appear anywhere, even outside 12706of a block (in which case the previous value is restored when the input 12707ends). The <em>vars</em> are initialized to <em>values</em> if present, or left 12708uninitialized otherwise.</p> 12709</div> 12710<div class="listingblock"> 12711<div class="content"> 12712<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-k">return</span><span class="tok-w"> </span>values<span class="tok-w"> </span>;<span class="tok-w"></span></code></pre> 12713</div> 12714</div> 12715<div class="paragraph"> 12716<p>Within a rule body, the return statement sets the return value for an 12717invocation of the rule and returns to the caller.</p> 12718</div> 12719<div class="listingblock"> 12720<div class="content"> 12721<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-k">switch</span><span class="tok-w"> </span>value<span class="tok-w"></span> 12722{<span class="tok-w"></span> 12723<span class="tok-w"> </span><span class="tok-k">case</span><span class="tok-w"> </span>pattern1<span class="tok-w"> </span>:<span class="tok-w"> </span>statements<span class="tok-w"> </span>;<span class="tok-w"></span> 12724<span class="tok-w"> </span><span class="tok-k">case</span><span class="tok-w"> </span>pattern2<span class="tok-w"> </span>:<span class="tok-w"> </span>statements<span class="tok-w"> </span>;<span class="tok-w"></span> 12725<span class="tok-w"> </span>...<span class="tok-w"></span> 12726}<span class="tok-w"></span></code></pre> 12727</div> 12728</div> 12729<div class="paragraph"> 12730<p>The switch statement executes zero or one of the enclosed <em>statements</em>, 12731depending on which, if any, is the first case whose <em>pattern</em> matches 12732<em>value</em>. The <em>pattern</em> values are not variable-expanded. The pattern 12733values may include the following wildcards:</p> 12734</div> 12735<div class="dlist"> 12736<dl> 12737<dt class="hdlist1"><code>?</code></dt> 12738<dd> 12739<p>match any single character</p> 12740</dd> 12741<dt class="hdlist1"><code>*</code></dt> 12742<dd> 12743<p>match zero or more characters</p> 12744</dd> 12745<dt class="hdlist1"><code>[chars]</code></dt> 12746<dd> 12747<p>match any single character in <em>chars</em></p> 12748</dd> 12749<dt class="hdlist1"><code>[^chars]</code></dt> 12750<dd> 12751<p>match any single character not in <em>chars</em></p> 12752</dd> 12753<dt class="hdlist1"><code>\x</code></dt> 12754<dd> 12755<p>match <em>x</em> (escapes the other wildcards)</p> 12756</dd> 12757</dl> 12758</div> 12759<div class="listingblock"> 12760<div class="content"> 12761<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-k">while</span><span class="tok-w"> </span>cond<span class="tok-w"> </span>{<span class="tok-w"> </span>statements<span class="tok-w"> </span>}<span class="tok-w"></span></code></pre> 12762</div> 12763</div> 12764<div class="paragraph"> 12765<p>Repeatedly execute <em>statements</em> while <em>cond</em> remains true upon entry. 12766(See the description of <em>cond</em> expression syntax under if, above).</p> 12767</div> 12768<div class="listingblock"> 12769<div class="content"> 12770<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-k">break</span><span class="tok-w"> </span>;<span class="tok-w"></span></code></pre> 12771</div> 12772</div> 12773<div class="paragraph"> 12774<p>Immediately exits the nearest enclosing while or for loop.</p> 12775</div> 12776<div class="listingblock"> 12777<div class="content"> 12778<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-k">continue</span><span class="tok-w"> </span>;<span class="tok-w"></span></code></pre> 12779</div> 12780</div> 12781<div class="paragraph"> 12782<p>Jumps to the top of the nearest enclosing while or for loop.</p> 12783</div> 12784</div> 12785<div class="sect3"> 12786<h4 id="jam.language.variables"><a class="anchor" href="#jam.language.variables"></a>11.2.6. Variables</h4> 12787<div class="paragraph"> 12788<p><code>B2</code> variables are lists of zero or more elements, with each element 12789being a string value. An undefined variable is indistinguishable from a 12790variable with an empty list, however, a defined variable may have one 12791more elements which are null strings. All variables are referenced as 12792<code>$(variable)</code>.</p> 12793</div> 12794<div class="paragraph"> 12795<p>Variables are either global or target-specific. In the latter case, the 12796variable takes on the given value only during the updating of the 12797specific target.</p> 12798</div> 12799<div class="paragraph"> 12800<p>A variable is defined with:</p> 12801</div> 12802<div class="listingblock"> 12803<div class="content"> 12804<pre class="pygments highlight"><code data-lang="jam"><span></span>variable<span class="tok-w"> </span>=<span class="tok-w"> </span>elements<span class="tok-w"> </span>;<span class="tok-w"></span> 12805variable<span class="tok-w"> </span>+=<span class="tok-w"> </span>elements<span class="tok-w"> </span>;<span class="tok-w"></span> 12806variable<span class="tok-w"> </span><span class="tok-k">on</span><span class="tok-w"> </span>targets<span class="tok-w"> </span>=<span class="tok-w"> </span>elements<span class="tok-w"> </span>;<span class="tok-w"></span> 12807variable<span class="tok-w"> </span><span class="tok-k">on</span><span class="tok-w"> </span>targets<span class="tok-w"> </span>+=<span class="tok-w"> </span>elements<span class="tok-w"> </span>;<span class="tok-w"></span> 12808variable<span class="tok-w"> </span>default<span class="tok-w"> </span>=<span class="tok-w"> </span>elements<span class="tok-w"> </span>;<span class="tok-w"></span> 12809variable<span class="tok-w"> </span>?=<span class="tok-w"> </span>elements<span class="tok-w"> </span>;<span class="tok-w"></span></code></pre> 12810</div> 12811</div> 12812<div class="paragraph"> 12813<p>The first two forms set <em>variable</em> globally. The third and forth forms 12814set a target-specific variable. The <code>=</code> operator replaces any previous 12815elements of <em>variable</em> with <em>elements</em>; the <code>+=</code> operation adds 12816<em>elements</em> to <em>variable</em>'s list of elements. The final two forms are 12817synonymous: they set <em>variable</em> globally, but only if it was previously 12818unset.</p> 12819</div> 12820<div class="paragraph"> 12821<p>Variables referenced in updating commands will be replaced with their 12822values; target-specific values take precedence over global values. 12823Variables passed as arguments (<code>$(1)</code> and <code>$(2)</code>) to actions are 12824replaced with their bound values; the <code>bind</code> modifier can be used on 12825actions to cause other variables to be replaced with bound values. See 12826Action Modifiers above.</p> 12827</div> 12828<div class="paragraph"> 12829<p><code>B2</code> variables are not re-exported to the environment of the shell that 12830executes the updating actions, but the updating actions can reference 12831<code>b2</code> variables with <code>$(variable)</code>.</p> 12832</div> 12833<div class="sect4"> 12834<h5 id="jam.language.variables.expansion"><a class="anchor" href="#jam.language.variables.expansion"></a>Variable Expansion</h5> 12835<div class="paragraph"> 12836<p>During parsing, <code>b2</code> performs variable expansion on each token that is 12837not a keyword or rule name. Such tokens with embedded variable 12838references are replaced with zero or more tokens. Variable references 12839are of the form <code>$(v)</code> or <code>$(vm)</code>, where <em>v</em> is the variable name, and 12840<em>m</em> are optional modifiers.</p> 12841</div> 12842<div class="paragraph"> 12843<p>Variable expansion in a rule’s actions is similar to variable expansion 12844in statements, except that the action string is tokenized at whitespace 12845regardless of quoting.</p> 12846</div> 12847<div class="paragraph"> 12848<p>The result of a token after variable expansion is the <em>product</em> of the 12849components of the token, where each component is a literal substring or 12850a list substituting a variable reference. For example:</p> 12851</div> 12852<div class="listingblock"> 12853<div class="content"> 12854<pre>$(X) -> a b c 12855t$(X) -> ta tb tc 12856$(X)z -> az bz cz 12857$(X)-$(X) -> a-a a-b a-c b-a b-b b-c c-a c-b c-c</pre> 12858</div> 12859</div> 12860<div class="paragraph"> 12861<p>The variable name and modifiers can themselves contain a variable 12862reference, and this partakes of the product as well:</p> 12863</div> 12864<div class="listingblock"> 12865<div class="content"> 12866<pre>$(X) -> a b c 12867$(Y) -> 1 2 12868$(Z) -> X Y 12869$($(Z)) -> a b c 1 2</pre> 12870</div> 12871</div> 12872<div class="paragraph"> 12873<p>Because of this product expansion, if any variable reference in a token 12874is undefined, the result of the expansion is an empty list. If any 12875variable element is a null string, the result propagates the non-null 12876elements:</p> 12877</div> 12878<div class="listingblock"> 12879<div class="content"> 12880<pre>$(X) -> a "" 12881$(Y) -> "" 1 12882$(Z) -> 12883-$(X)$(Y)- -> -a- -a1- -- -1- 12884-$(X)$(Z)- -></pre> 12885</div> 12886</div> 12887<div class="paragraph"> 12888<p>A variable element’s string value can be parsed into grist and 12889filename-related components. Modifiers to a variable are used to select 12890elements, select components, and replace components. The modifiers are:</p> 12891</div> 12892<div class="dlist"> 12893<dl> 12894<dt class="hdlist1"><code>[n]</code></dt> 12895<dd> 12896<div class="paragraph"> 12897<p>Select element number <em>n</em> (starting at 1). If the variable contains 12898fewer than <em>n</em> elements, the result is a zero-element list. <em>n</em> can be 12899negative in which case the element number <em>n</em> from the last leftward 12900is returned.</p> 12901</div> 12902</dd> 12903<dt class="hdlist1"><code>[n-m]</code></dt> 12904<dd> 12905<div class="paragraph"> 12906<p>Select elements number <em>n</em> through <em>m</em>. <em>n</em> and <em>m</em> can be negative in 12907which case they refer to elements counting from the last leftward.</p> 12908</div> 12909</dd> 12910<dt class="hdlist1"><code>[n-]</code></dt> 12911<dd> 12912<div class="paragraph"> 12913<p>Select elements number <em>n</em> through the last. <em>n</em> can be negative in 12914which case it refers to the element counting from the last leftward.</p> 12915</div> 12916</dd> 12917<dt class="hdlist1"><code>:B</code></dt> 12918<dd> 12919<div class="paragraph"> 12920<p>Select filename base — a basename without extension.</p> 12921</div> 12922</dd> 12923<dt class="hdlist1"><code>:S</code></dt> 12924<dd> 12925<div class="paragraph"> 12926<p>Select file extension — a (last) filename suffix.</p> 12927</div> 12928</dd> 12929<dt class="hdlist1"><code>:M</code></dt> 12930<dd> 12931<div class="paragraph"> 12932<p>Select archive member name.</p> 12933</div> 12934</dd> 12935<dt class="hdlist1"><code>:D</code></dt> 12936<dd> 12937<div class="paragraph"> 12938<p>Select directory path.</p> 12939</div> 12940</dd> 12941<dt class="hdlist1"><code>:P</code></dt> 12942<dd> 12943<div class="paragraph"> 12944<p>Select parent directory.</p> 12945</div> 12946</dd> 12947<dt class="hdlist1"><code>:G</code></dt> 12948<dd> 12949<div class="paragraph"> 12950<p>Select grist.</p> 12951</div> 12952</dd> 12953<dt class="hdlist1"><code>:U</code></dt> 12954<dd> 12955<div class="paragraph"> 12956<p>Replace lowercase characters with uppercase.</p> 12957</div> 12958</dd> 12959<dt class="hdlist1"><code>:L</code></dt> 12960<dd> 12961<div class="paragraph"> 12962<p>Replace uppercase characters with lowercase.</p> 12963</div> 12964</dd> 12965<dt class="hdlist1"><code>:T</code></dt> 12966<dd> 12967<div class="paragraph"> 12968<p>Converts all back-slashes ("\") to forward slashes ("/"). For example</p> 12969</div> 12970<div class="listingblock"> 12971<div class="content"> 12972<pre>x = "C:\\Program Files\\Borland" ; ECHO $(x:T) ;</pre> 12973</div> 12974</div> 12975<div class="paragraph"> 12976<p>prints <code>C:/Program Files/Borland</code></p> 12977</div> 12978</dd> 12979<dt class="hdlist1"><code>:W</code></dt> 12980<dd> 12981<div class="paragraph"> 12982<p>When invoking Windows-based tools from <a href="http://www.cygwin.com/">Cygwin</a> 12983it can be important to pass them true windows-style paths. The <code>:W</code> 12984modifier, <strong>under Cygwin only</strong>, turns a cygwin path into a Win32 path 12985using the 12986<a href="http://www.cygwin.com/cygwin-api/func-cygwin-conv-to-win32-path.html"><code>cygwin_conv_to_win32_path</code></a> 12987function. For example</p> 12988</div> 12989<div class="listingblock"> 12990<div class="content"> 12991<pre>x = "/cygdrive/c/Program Files/Borland" ; ECHO $(x:W) ;</pre> 12992</div> 12993</div> 12994<div class="paragraph"> 12995<p>prints <code>C:\Program Files\Borland</code> on Cygwin</p> 12996</div> 12997<div class="paragraph"> 12998<p>Similarly, when used on OpenVMS, the <code>:W</code> modifier translates a 12999POSIX-style path into native VMS-style format using <code>decc$to_vms</code> CRTL 13000function. This modifier is generally used inside action blocks to 13001properly specify file paths in VMS-specific commands. For example</p> 13002</div> 13003<div class="listingblock"> 13004<div class="content"> 13005<pre>x = "subdir/filename.c" ; ECHO $(x:W) ;</pre> 13006</div> 13007</div> 13008<div class="paragraph"> 13009<p>prints <code>[.subdir]filename.c</code> on OpenVMS</p> 13010</div> 13011<div class="paragraph"> 13012<p>On other platforms, the string is unchanged.</p> 13013</div> 13014</dd> 13015<dt class="hdlist1"><code>:chars</code></dt> 13016<dd> 13017<p>Select the components listed in <em>chars</em>.</p> 13018<div class="paragraph"> 13019<p>For example, <code>:BS</code> selects filename (basename and extension).</p> 13020</div> 13021</dd> 13022<dt class="hdlist1"><code>:G=grist</code></dt> 13023<dd> 13024<p>Replace grist with <em>grist</em>.</p> 13025</dd> 13026<dt class="hdlist1"><code>:D=path</code></dt> 13027<dd> 13028<p>Replace directory with <em>path</em>.</p> 13029</dd> 13030<dt class="hdlist1"><code>:B=base</code></dt> 13031<dd> 13032<p>Replace the base part of file name with <em>base</em>.</p> 13033</dd> 13034<dt class="hdlist1"><code>:S=suf</code></dt> 13035<dd> 13036<p>Replace the suffix of file name with <em>suf</em>.</p> 13037</dd> 13038<dt class="hdlist1"><code>:M=mem</code></dt> 13039<dd> 13040<p>Replace the archive member name with <em>mem</em>.</p> 13041</dd> 13042<dt class="hdlist1"><code>:R=root</code></dt> 13043<dd> 13044<p>Prepend <em>root</em> to the whole file name, if not already rooted.</p> 13045</dd> 13046<dt class="hdlist1"><code>:E=value</code></dt> 13047<dd> 13048<p>Assign <em>value</em> to the variable if it is unset.</p> 13049</dd> 13050<dt class="hdlist1"><code>:J=joinval</code></dt> 13051<dd> 13052<p>Concatenate list elements into single element, separated by 13053<em>joinval</em>.</p> 13054</dd> 13055</dl> 13056</div> 13057<div class="paragraph"> 13058<p>On VMS, <code>$(var:P)</code> is the parent directory of <code>$(var:D)</code>.</p> 13059</div> 13060</div> 13061<div class="sect4"> 13062<h5 id="jam.language.variables.local_for_loop_variables"><a class="anchor" href="#jam.language.variables.local_for_loop_variables"></a>Local For Loop Variables</h5> 13063<div class="paragraph"> 13064<p>Boost Jam allows you to declare a local for loop control variable right 13065in the loop:</p> 13066</div> 13067<div class="listingblock"> 13068<div class="content"> 13069<pre class="pygments highlight"><code data-lang="jam"><span></span>x<span class="tok-w"> </span>=<span class="tok-w"> </span>1<span class="tok-w"> </span>2<span class="tok-w"> </span>3<span class="tok-w"> </span>;<span class="tok-w"></span> 13070y<span class="tok-w"> </span>=<span class="tok-w"> </span>4<span class="tok-w"> </span>5<span class="tok-w"> </span>6<span class="tok-w"> </span>;<span class="tok-w"></span> 13071<span class="tok-k">for</span><span class="tok-w"> </span><span class="tok-k">local</span><span class="tok-w"> </span>y<span class="tok-w"> </span><span class="tok-k">in</span><span class="tok-w"> </span><span class="tok-si">$(x)</span><span class="tok-w"></span> 13072{<span class="tok-w"></span> 13073<span class="tok-w"> </span><span class="tok-nb">ECHO</span><span class="tok-w"> </span><span class="tok-si">$(y)</span><span class="tok-w"> </span>;<span class="tok-w"> </span><span class="tok-c1"># prints "1", "2", or "3"</span> 13074}<span class="tok-w"></span> 13075<span class="tok-nb">ECHO</span><span class="tok-w"> </span><span class="tok-si">$(y)</span><span class="tok-w"> </span>;<span class="tok-w"> </span><span class="tok-c1"># prints "4 5 6"</span></code></pre> 13076</div> 13077</div> 13078</div> 13079<div class="sect4"> 13080<h5 id="jam.language.variables.atfile"><a class="anchor" href="#jam.language.variables.atfile"></a>Generated File Expansion</h5> 13081<div class="paragraph"> 13082<p>During expansion of expressions <code>b2</code> also looks for subexpressions of 13083the form <code>@(filename:E=filecontents)</code> and replaces the expression with 13084<code>filename</code> after creating the given file with the contents set to 13085<code>filecontents</code>. This is useful for creating compiler response files, and 13086other "internal" files. The expansion works both during parsing and 13087action execution. Hence it is possible to create files during any of the 13088three build phases.</p> 13089</div> 13090</div> 13091<div class="sect4"> 13092<h5 id="jam.language.variables.builtins"><a class="anchor" href="#jam.language.variables.builtins"></a>Built-in Variables</h5> 13093<div class="paragraph"> 13094<p>This section discusses variables that have special meaning to <code>b2</code>. All 13095of these must be defined or used in the global module — using those 13096variables inside a named module will not have the desired effect. See 13097<a href="#jam.language.modules">Modules</a>.</p> 13098</div> 13099<div class="sect5"> 13100<h6 id="jam.language.variables.builtins.search"><a class="anchor" href="#jam.language.variables.builtins.search"></a>SEARCH and LOCATE</h6> 13101<div class="paragraph"> 13102<p>These two variables control the binding of file target names to 13103locations in the file system. Generally, <code>$(SEARCH)</code> is used to find 13104existing sources while <code>$(LOCATE)</code> is used to fix the location for built 13105targets.</p> 13106</div> 13107<div class="paragraph"> 13108<p>Rooted (absolute path) file targets are bound as is. Unrooted file 13109target names are also normally bound as is, and thus relative to the 13110current directory, but the settings of <code>$(LOCATE)</code> and <code>$(SEARCH)</code> alter 13111this:</p> 13112</div> 13113<div class="ulist"> 13114<ul> 13115<li> 13116<p>If <code>$(LOCATE)</code> is set then the target is bound relative to the first 13117directory in <code>$(LOCATE)</code>. Only the first element is used for binding.</p> 13118</li> 13119<li> 13120<p>If <code>$(SEARCH)</code> is set then the target is bound to the first directory 13121in <code>$(SEARCH)</code> where the target file already exists.</p> 13122</li> 13123<li> 13124<p>If the <code>$(SEARCH)</code> search fails, the target is bound relative to the 13125current directory anyhow.</p> 13126</li> 13127</ul> 13128</div> 13129<div class="paragraph"> 13130<p>Both <code>$(SEARCH)</code> and <code>$(LOCATE)</code> should be set target-specific and not 13131globally. If they were set globally, <code>b2</code> would use the same paths for 13132all file binding, which is not likely to produce sane results. When 13133writing your own rules, especially ones not built upon those in Jambase, 13134you may need to set <code>$(SEARCH)</code> or <code>$(LOCATE)</code> directly. Almost all of 13135the rules defined in Jambase set <code>$(SEARCH)</code> and <code>$(LOCATE)</code> to sensible 13136values for sources they are looking for and targets they create, 13137respectively.</p> 13138</div> 13139</div> 13140<div class="sect5"> 13141<h6 id="jam.language.variables.builtins.hdrscan"><a class="anchor" href="#jam.language.variables.builtins.hdrscan"></a>HDRSCAN and HDRRULE</h6> 13142<div class="paragraph"> 13143<p>These two variables control header file scanning. <code>$(HDRSCAN)</code> is an 13144<code>egrep(1)</code> pattern, with ()'s surrounding the file name, used to find 13145file inclusion statements in source files. <code>Jambase</code> uses 13146<code>$(HDRPATTERN)</code> as the pattern for <code>$(HDRSCAN)</code>. <code>$(HDRRULE)</code> is the 13147name of a rule to invoke with the results of the scan: the scanned file 13148is the target, the found files are the sources. This is the only place 13149where <code>b2</code> invokes a rule through a variable setting.</p> 13150</div> 13151<div class="paragraph"> 13152<p>Both <code>$(HDRSCAN)</code> and <code>$(HDRRULE)</code> must be set for header file scanning 13153to take place, and they should be set target-specific and not globally. 13154If they were set globally, all files, including executables and 13155libraries, would be scanned for header file include statements.</p> 13156</div> 13157<div class="paragraph"> 13158<p>The scanning for header file inclusions is not exact, but it is at least 13159dynamic, so there is no need to run something like <code>makedepend(GNU)</code> to 13160create a static dependency file. The scanning mechanism errs on the side 13161of inclusion (i.e., it is more likely to return filenames that are not 13162actually used by the compiler than to miss include files) because it 13163can’t tell if <code>#include</code> lines are inside <code>#ifdefs</code> or other conditional 13164logic. In <code>Jambase</code>, <code>HdrRule</code> applies the <code>NOCARE</code> rule to each header 13165file found during scanning so that if the file isn’t present yet doesn’t 13166cause the compilation to fail, <code>b2</code> won’t care.</p> 13167</div> 13168<div class="paragraph"> 13169<p>Also, scanning for regular expressions only works where the included 13170file name is literally in the source file. It can’t handle languages 13171that allow including files using variable names (as the <code>Jam</code> language 13172itself does).</p> 13173</div> 13174</div> 13175<div class="sect5"> 13176<h6 id="jam.language.variables.builtins.semaphores"><a class="anchor" href="#jam.language.variables.builtins.semaphores"></a>Semaphores</h6> 13177<div class="paragraph"> 13178<p>It is sometimes desirable to disallow parallel execution of some 13179actions. For example:</p> 13180</div> 13181<div class="ulist"> 13182<ul> 13183<li> 13184<p>Old versions of yacc use files with fixed names. So, running two yacc 13185actions is dangerous.</p> 13186</li> 13187<li> 13188<p>One might want to perform parallel compiling, but not do parallel 13189linking, because linking is i/o bound and only gets slower.</p> 13190</li> 13191</ul> 13192</div> 13193<div class="paragraph"> 13194<p>Craig McPeeters has extended Perforce Jam to solve such problems, and 13195that extension was integrated in Boost.Jam.</p> 13196</div> 13197<div class="paragraph"> 13198<p>Any target can be assigned a <em>semaphore</em>, by setting a variable called 13199<code>SEMAPHORE</code> on that target. The value of the variable is the semaphore 13200name. It must be different from names of any declared target, but is 13201arbitrary otherwise.</p> 13202</div> 13203<div class="paragraph"> 13204<p>The semantic of semaphores is that in a group of targets which have the 13205same semaphore, only one can be updated at the moment, regardless of 13206<code>-j</code> option.</p> 13207</div> 13208</div> 13209<div class="sect5"> 13210<h6 id="jam.language.variables.builtins.platform_identifier"><a class="anchor" href="#jam.language.variables.builtins.platform_identifier"></a>Platform Identifier</h6> 13211<div class="paragraph"> 13212<p>A number of Jam built-in variables can be used to identify runtime 13213platform:</p> 13214</div> 13215<div class="dlist"> 13216<dl> 13217<dt class="hdlist1"><code>OS</code></dt> 13218<dd> 13219<p>OS identifier string</p> 13220</dd> 13221<dt class="hdlist1"><code>OSPLAT</code></dt> 13222<dd> 13223<p>Underlying architecture, when applicable</p> 13224</dd> 13225<dt class="hdlist1"><code>MAC</code></dt> 13226<dd> 13227<p>true on MAC platform</p> 13228</dd> 13229<dt class="hdlist1"><code>NT</code></dt> 13230<dd> 13231<p>true on NT platform</p> 13232</dd> 13233<dt class="hdlist1"><code>OS2</code></dt> 13234<dd> 13235<p>true on OS2 platform</p> 13236</dd> 13237<dt class="hdlist1"><code>UNIX</code></dt> 13238<dd> 13239<p>true on Unix platforms</p> 13240</dd> 13241<dt class="hdlist1"><code>VMS</code></dt> 13242<dd> 13243<p>true on VMS platform</p> 13244</dd> 13245</dl> 13246</div> 13247</div> 13248</div> 13249<div class="sect4"> 13250<h5 id="jam.language.variables.builtins.jam_version"><a class="anchor" href="#jam.language.variables.builtins.jam_version"></a>Jam Version</h5> 13251<div class="dlist"> 13252<dl> 13253<dt class="hdlist1"><code>JAMDATE</code></dt> 13254<dd> 13255<p>Time and date at <code>b2</code> start-up as an ISO-8601 UTC value.</p> 13256</dd> 13257<dt class="hdlist1"><code>JAMUNAME</code></dt> 13258<dd> 13259<p>Output of uname(1) command (Unix only)</p> 13260</dd> 13261<dt class="hdlist1"><code>JAMVERSION</code></dt> 13262<dd> 13263<p><code>b2</code> version, as a sematic triplet "X.Y.Z".</p> 13264</dd> 13265<dt class="hdlist1"><code>JAM_VERSION</code></dt> 13266<dd> 13267<p>A predefined global variable with two elements indicates the version 13268number of Boost Jam. Boost Jam versions start at <code>03</code> <code>00</code>. 13269Earlier versions of <code>Jam</code> do not automatically define <code>JAM_VERSION</code>.</p> 13270</dd> 13271</dl> 13272</div> 13273<div class="sect5"> 13274<h6 id="jam.language.variables.builtins.jamshell"><a class="anchor" href="#jam.language.variables.builtins.jamshell"></a>JAMSHELL</h6> 13275<div class="paragraph"> 13276<p>When <code>b2</code> executes a rule’s action block, it forks and execs a shell, 13277passing the action block as an argument to the shell. The invocation of 13278the shell can be controlled by <code>$(JAMSHELL)</code>. The default on Unix is, 13279for example:</p> 13280</div> 13281<div class="listingblock"> 13282<div class="content"> 13283<pre class="pygments highlight"><code data-lang="jam"><span></span>JAMSHELL<span class="tok-w"> </span>=<span class="tok-w"> </span>/bin/sh<span class="tok-w"> </span>-c<span class="tok-w"> </span>%<span class="tok-w"> </span>;<span class="tok-w"></span></code></pre> 13284</div> 13285</div> 13286<div class="paragraph"> 13287<p>The <code>%</code> is replaced with the text of the action block.</p> 13288</div> 13289<div class="paragraph"> 13290<p><code>B2</code> does not directly support building in parallel across multiple 13291hosts, since that is heavily dependent on the local environment. To 13292build in parallel across multiple hosts, you need to write your own 13293shell that provides access to the multiple hosts. You then reset 13294<code>$(JAMSHELL)</code> to reference it.</p> 13295</div> 13296<div class="paragraph"> 13297<p>Just as <code>b2</code> expands a <code>%</code> to be the text of the rule’s action block, it 13298expands a <code>!</code> to be the multi-process slot number. The slot number 13299varies between 1 and the number of concurrent jobs permitted by the <code>-j</code> 13300flag given on the command line. Armed with this, it is possible to write 13301a multiple host shell. For example:</p> 13302</div> 13303<div class="listingblock"> 13304<div class="content"> 13305<pre class="pygments highlight"><code data-lang="bash"><span></span><span class="tok-ch">#!/bin/sh</span> 13306 13307<span class="tok-c1"># This sample JAMSHELL uses the SunOS on(1) command to execute a</span> 13308<span class="tok-c1"># command string with an identical environment on another host.</span> 13309 13310<span class="tok-c1"># Set JAMSHELL = jamshell ! %</span> 13311<span class="tok-c1">#</span> 13312<span class="tok-c1"># where jamshell is the name of this shell file.</span> 13313<span class="tok-c1">#</span> 13314<span class="tok-c1"># This version handles up to -j6; after that they get executed</span> 13315<span class="tok-c1"># locally.</span> 13316 13317<span class="tok-k">case</span> <span class="tok-nv">$1</span> in 13318<span class="tok-m">1</span><span class="tok-p">|</span><span class="tok-m">4</span><span class="tok-o">)</span> on winken sh -c <span class="tok-s2">"</span><span class="tok-nv">$2</span><span class="tok-s2">"</span><span class="tok-p">;;</span> 13319<span class="tok-m">2</span><span class="tok-p">|</span><span class="tok-m">5</span><span class="tok-o">)</span> on blinken sh -c <span class="tok-s2">"</span><span class="tok-nv">$2</span><span class="tok-s2">"</span><span class="tok-p">;;</span> 13320<span class="tok-m">3</span><span class="tok-p">|</span><span class="tok-m">6</span><span class="tok-o">)</span> on nod sh -c <span class="tok-s2">"</span><span class="tok-nv">$2</span><span class="tok-s2">"</span><span class="tok-p">;;</span> 13321*<span class="tok-o">)</span> <span class="tok-nb">eval</span> <span class="tok-s2">"</span><span class="tok-nv">$2</span><span class="tok-s2">"</span><span class="tok-p">;;</span> 13322<span class="tok-k">esac</span></code></pre> 13323</div> 13324</div> 13325</div> 13326<div class="sect5"> 13327<h6 id="jam.language.variables.builtins.actionrule"><a class="anchor" href="#jam.language.variables.builtins.actionrule"></a><code>__TIMING_RULE__</code> and <code>__ACTION_RULE__</code></h6> 13328<div class="paragraph"> 13329<p>The <code>__TIMING_RULE__</code> and <code>__ACTION_RULE__</code> can be set to the name of a 13330rule for <code>b2</code> to call <strong>after</strong> an action completes for a target. They 13331both give diagnostic information about the action that completed. For 13332<code>__TIMING_RULE__</code> the rule is called as:</p> 13333</div> 13334<div class="listingblock"> 13335<div class="content"> 13336<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-k">rule</span><span class="tok-w"> </span><span class="tok-nf">timing-rule</span><span class="tok-w"> </span><span class="tok-p">(</span><span class="tok-w"> </span><span class="tok-nv">args</span><span class="tok-w"> </span><span class="tok-p">*</span><span class="tok-w"> </span><span class="tok-p">:</span><span class="tok-w"> </span><span class="tok-nv">target</span><span class="tok-w"> </span><span class="tok-p">:</span><span class="tok-w"> </span><span class="tok-nv">start</span><span class="tok-w"> </span><span class="tok-nv">end</span><span class="tok-w"> </span><span class="tok-nv">user</span><span class="tok-w"> </span><span class="tok-nv">system</span><span class="tok-w"> </span><span class="tok-p">)</span><span class="tok-w"></span></code></pre> 13337</div> 13338</div> 13339<div class="paragraph"> 13340<p>And <code>__ACTION_RULE__</code> is called as:</p> 13341</div> 13342<div class="listingblock"> 13343<div class="content"> 13344<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-k">rule</span><span class="tok-w"> </span><span class="tok-nf">action-rule</span><span class="tok-w"> </span><span class="tok-p">(</span><span class="tok-w"> </span><span class="tok-nv">args</span><span class="tok-w"> </span><span class="tok-p">*</span><span class="tok-w"> </span><span class="tok-p">:</span><span class="tok-w"> </span><span class="tok-nv">target</span><span class="tok-w"> </span><span class="tok-p">:</span><span class="tok-w"> </span><span class="tok-nv">command</span><span class="tok-w"> </span><span class="tok-nv">status</span><span class="tok-w"> </span><span class="tok-nv">start</span><span class="tok-w"> </span><span class="tok-nv">end</span><span class="tok-w"> </span><span class="tok-nv">user</span><span class="tok-w"> </span><span class="tok-nv">system</span><span class="tok-w"> </span><span class="tok-p">:</span><span class="tok-w"> </span><span class="tok-nv">output</span><span class="tok-w"> </span><span class="tok-p">?</span><span class="tok-w"> </span><span class="tok-p">)</span><span class="tok-w"></span></code></pre> 13345</div> 13346</div> 13347<div class="paragraph"> 13348<p>The arguments for both are:</p> 13349</div> 13350<div class="dlist"> 13351<dl> 13352<dt class="hdlist1"><code>args</code></dt> 13353<dd> 13354<p>Any values following the rule name in the <code>__TIMING_RULE__</code> or 13355<code>__ACTION_RULE__</code> are passed along here.</p> 13356</dd> 13357<dt class="hdlist1"><code>target</code></dt> 13358<dd> 13359<p>The <code>b2</code> target that was built.</p> 13360</dd> 13361<dt class="hdlist1"><code>command</code></dt> 13362<dd> 13363<p>The text of the executed command in the action body.</p> 13364</dd> 13365<dt class="hdlist1"><code>status</code></dt> 13366<dd> 13367<p>The integer result of the executed command.</p> 13368</dd> 13369<dt class="hdlist1"><code>start</code></dt> 13370<dd> 13371<p>The starting timestamp of the executed command as a ISO-8601 UTC 13372value.</p> 13373</dd> 13374<dt class="hdlist1"><code>end</code></dt> 13375<dd> 13376<p>The completion timestamp of the executed command as a ISO-8601 UTC 13377value.</p> 13378</dd> 13379<dt class="hdlist1"><code>user</code></dt> 13380<dd> 13381<p>The number of user CPU seconds the executed command spent as a 13382floating point value.</p> 13383</dd> 13384<dt class="hdlist1"><code>system</code></dt> 13385<dd> 13386<p>The number of system CPU seconds the executed command spent as a 13387floating point value.</p> 13388</dd> 13389<dt class="hdlist1"><code>output</code></dt> 13390<dd> 13391<p>The output of the command as a single string. The content of the 13392output reflects the use of the <code>-pX</code> option.</p> 13393</dd> 13394</dl> 13395</div> 13396<div class="admonitionblock note"> 13397<table> 13398<tr> 13399<td class="icon"> 13400<div class="title">ℹ</div> 13401</td> 13402<td class="content"> 13403If both variables are set for a target both are called, first 13404<code>__TIMING_RULE__</code> then <code>__ACTION_RULE__</code>. 13405</td> 13406</tr> 13407</table> 13408</div> 13409</div> 13410</div> 13411</div> 13412<div class="sect3"> 13413<h4 id="jam.language.modules"><a class="anchor" href="#jam.language.modules"></a>11.2.7. Modules</h4> 13414<div class="paragraph"> 13415<p>Boost Jam introduces support for modules, which provide some rudimentary 13416namespace protection for rules and variables. A new keyword, <code>module</code> 13417was also introduced. The features described in this section are 13418primitives, meaning that they are meant to provide the operations needed 13419to write Jam rules which provide a more elegant module interface.</p> 13420</div> 13421<div class="sect4"> 13422<h5 id="jam.language.modules.declaration"><a class="anchor" href="#jam.language.modules.declaration"></a>Declaration</h5> 13423<div class="listingblock"> 13424<div class="content"> 13425<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-k">module</span><span class="tok-w"> </span><span class="tok-nn">expression</span><span class="tok-w"> </span><span class="tok-p">{</span><span class="tok-w"> </span>...<span class="tok-w"> </span>}<span class="tok-w"></span></code></pre> 13426</div> 13427</div> 13428<div class="paragraph"> 13429<p>Code within the <code>{ …​ }</code> executes within the module named by evaluating 13430expression. Rule definitions can be found in the module’s own namespace, 13431and in the namespace of the global module as <em>module-name</em>.<em>rule-name</em>, 13432so within a module, other rules in that module may always be invoked 13433without qualification:</p> 13434</div> 13435<div class="listingblock"> 13436<div class="content"> 13437<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-k">module</span><span class="tok-w"> </span><span class="tok-nn">my_module</span><span class="tok-w"></span> 13438<span class="tok-p">{</span><span class="tok-w"></span> 13439<span class="tok-w"> </span><span class="tok-k">rule</span><span class="tok-w"> </span><span class="tok-nf">salute</span><span class="tok-w"> </span><span class="tok-p">(</span><span class="tok-w"> </span><span class="tok-nv">x</span><span class="tok-w"> </span><span class="tok-p">)</span><span class="tok-w"> </span>{<span class="tok-w"> </span><span class="tok-nb">ECHO</span><span class="tok-w"> </span><span class="tok-si">$(x)</span>,<span class="tok-w"> </span>world<span class="tok-w"> </span>;<span class="tok-w"> </span>}<span class="tok-w"></span> 13440<span class="tok-w"> </span><span class="tok-k">rule</span><span class="tok-w"> </span><span class="tok-nf">greet</span><span class="tok-w"> </span><span class="tok-p">(</span><span class="tok-w"> </span><span class="tok-p">)</span><span class="tok-w"> </span>{<span class="tok-w"> </span>salute<span class="tok-w"> </span>hello<span class="tok-w"> </span>;<span class="tok-w"> </span>}<span class="tok-w"></span> 13441<span class="tok-w"> </span>greet<span class="tok-w"> </span>;<span class="tok-w"></span> 13442}<span class="tok-w"></span> 13443my_module.salute<span class="tok-w"> </span>goodbye<span class="tok-w"> </span>;<span class="tok-w"></span></code></pre> 13444</div> 13445</div> 13446<div class="paragraph"> 13447<p>When an invoked rule is not found in the current module’s namespace, it 13448is looked up in the namespace of the global module, so qualified calls 13449work across modules:</p> 13450</div> 13451<div class="listingblock"> 13452<div class="content"> 13453<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-k">module</span><span class="tok-w"> </span><span class="tok-nn">your_module</span><span class="tok-w"></span> 13454<span class="tok-p">{</span><span class="tok-w"></span> 13455<span class="tok-w"> </span><span class="tok-k">rule</span><span class="tok-w"> </span><span class="tok-nf">bedtime</span><span class="tok-w"> </span><span class="tok-p">(</span><span class="tok-w"> </span><span class="tok-p">)</span><span class="tok-w"> </span>{<span class="tok-w"> </span>my_module.salute<span class="tok-w"> </span>goodnight<span class="tok-w"> </span>;<span class="tok-w"> </span>}<span class="tok-w"></span> 13456}<span class="tok-w"></span></code></pre> 13457</div> 13458</div> 13459</div> 13460<div class="sect4"> 13461<h5 id="jam.language.modules.variable_scope"><a class="anchor" href="#jam.language.modules.variable_scope"></a>Variable Scope</h5> 13462<div class="paragraph"> 13463<p>Each module has its own set of dynamically nested variable scopes. When 13464execution passes from module A to module B, all the variable bindings 13465from A become unavailable, and are replaced by the bindings that belong 13466to B. This applies equally to local and global variables:</p> 13467</div> 13468<div class="listingblock"> 13469<div class="content"> 13470<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-k">module</span><span class="tok-w"> </span><span class="tok-nn">A</span><span class="tok-w"></span> 13471<span class="tok-p">{</span><span class="tok-w"></span> 13472<span class="tok-w"> </span>x<span class="tok-w"> </span>=<span class="tok-w"> </span>1<span class="tok-w"> </span>;<span class="tok-w"></span> 13473<span class="tok-w"> </span><span class="tok-k">rule</span><span class="tok-w"> </span><span class="tok-nf">f</span><span class="tok-w"> </span><span class="tok-p">(</span><span class="tok-w"> </span><span class="tok-p">)</span><span class="tok-w"></span> 13474<span class="tok-w"> </span>{<span class="tok-w"></span> 13475<span class="tok-w"> </span><span class="tok-k">local</span><span class="tok-w"> </span>y<span class="tok-w"> </span>=<span class="tok-w"> </span>999<span class="tok-w"> </span>;<span class="tok-w"> </span><span class="tok-c1"># becomes visible again when B.f calls A.g</span> 13476<span class="tok-w"> </span>B.f<span class="tok-w"> </span>;<span class="tok-w"></span> 13477<span class="tok-w"> </span>}<span class="tok-w"></span> 13478<span class="tok-w"> </span><span class="tok-k">rule</span><span class="tok-w"> </span><span class="tok-nf">g</span><span class="tok-w"> </span><span class="tok-p">(</span><span class="tok-w"> </span><span class="tok-p">)</span><span class="tok-w"></span> 13479<span class="tok-w"> </span>{<span class="tok-w"></span> 13480<span class="tok-w"> </span><span class="tok-nb">ECHO</span><span class="tok-w"> </span><span class="tok-si">$(y)</span><span class="tok-w"> </span>;<span class="tok-w"> </span><span class="tok-c1"># prints "999"</span> 13481<span class="tok-w"> </span>}<span class="tok-w"></span> 13482}<span class="tok-w"></span> 13483<span class="tok-k">module</span><span class="tok-w"> </span><span class="tok-nn">B</span><span class="tok-w"></span> 13484<span class="tok-p">{</span><span class="tok-w"></span> 13485<span class="tok-w"> </span>y<span class="tok-w"> </span>=<span class="tok-w"> </span>2<span class="tok-w"> </span>;<span class="tok-w"></span> 13486<span class="tok-w"> </span><span class="tok-k">rule</span><span class="tok-w"> </span><span class="tok-nf">f</span><span class="tok-w"> </span><span class="tok-p">(</span><span class="tok-w"> </span><span class="tok-p">)</span><span class="tok-w"></span> 13487<span class="tok-w"> </span>{<span class="tok-w"></span> 13488<span class="tok-w"> </span><span class="tok-nb">ECHO</span><span class="tok-w"> </span><span class="tok-si">$(y)</span><span class="tok-w"> </span>;<span class="tok-w"> </span><span class="tok-c1"># always prints "2"</span> 13489<span class="tok-w"> </span>A.g<span class="tok-w"> </span>;<span class="tok-w"></span> 13490<span class="tok-w"> </span>}<span class="tok-w"></span> 13491}<span class="tok-w"></span></code></pre> 13492</div> 13493</div> 13494<div class="paragraph"> 13495<p>The only way to access another module’s variables is by entering that 13496module:</p> 13497</div> 13498<div class="listingblock"> 13499<div class="content"> 13500<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-k">rule</span><span class="tok-w"> </span><span class="tok-nf">peek</span><span class="tok-w"> </span><span class="tok-p">(</span><span class="tok-w"> </span><span class="tok-nv">module-name</span><span class="tok-w"> </span><span class="tok-p">?</span><span class="tok-w"> </span><span class="tok-p">:</span><span class="tok-w"> </span><span class="tok-nv">variables</span><span class="tok-w"> </span><span class="tok-p">+</span><span class="tok-w"> </span><span class="tok-p">)</span><span class="tok-w"></span> 13501{<span class="tok-w"></span> 13502<span class="tok-w"> </span><span class="tok-k">module</span><span class="tok-w"> </span><span class="tok-nn">$(module-name)</span><span class="tok-w"></span> 13503<span class="tok-w"> </span><span class="tok-p">{</span><span class="tok-w"></span> 13504<span class="tok-w"> </span><span class="tok-k">return</span><span class="tok-w"> </span><span class="tok-si">$($(>))</span><span class="tok-w"> </span>;<span class="tok-w"></span> 13505<span class="tok-w"> </span>}<span class="tok-w"></span> 13506}<span class="tok-w"></span></code></pre> 13507</div> 13508</div> 13509<div class="paragraph"> 13510<p>Note that because existing variable bindings change whenever a new 13511module scope is entered, argument bindings become unavailable. That 13512explains the use of <code>$(>)</code> in the peek rule above.</p> 13513</div> 13514</div> 13515<div class="sect4"> 13516<h5 id="jam.language.modules.local_rules"><a class="anchor" href="#jam.language.modules.local_rules"></a>Local Rules</h5> 13517<div class="listingblock"> 13518<div class="content"> 13519<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-k">local</span><span class="tok-w"> </span><span class="tok-k">rule</span><span class="tok-w"> </span><span class="tok-nf">rulename...</span><span class="tok-w"></span></code></pre> 13520</div> 13521</div> 13522<div class="paragraph"> 13523<p>The rule is declared locally to the current module. It is not entered in 13524the global module with qualification, and its name will not appear in 13525the result of:</p> 13526</div> 13527<div class="listingblock"> 13528<div class="content"> 13529<pre class="pygments highlight"><code data-lang="jam"><span></span>[<span class="tok-w"> </span><span class="tok-nb">RULENAMES</span><span class="tok-w"> </span><span class="tok-k">module</span>-name<span class="tok-w"> </span>]<span class="tok-w"></span></code></pre> 13530</div> 13531</div> 13532</div> 13533<div class="sect4"> 13534<h5 id="jam.language.modules.the__rulenames__rule"><a class="anchor" href="#jam.language.modules.the__rulenames__rule"></a>The <code>RULENAMES</code> Rule</h5> 13535<div class="listingblock"> 13536<div class="content"> 13537<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-k">rule</span><span class="tok-w"> </span><span class="tok-nf">RULENAMES</span><span class="tok-w"> </span><span class="tok-p">(</span><span class="tok-w"> </span><span class="tok-nv">module</span><span class="tok-w"> </span><span class="tok-p">?</span><span class="tok-w"> </span><span class="tok-p">)</span><span class="tok-w"></span></code></pre> 13538</div> 13539</div> 13540<div class="paragraph"> 13541<p>Returns a list of the names of all non-local rules in the given module. 13542If <em>module</em> is omitted, the names of all non-local rules in the global 13543module are returned.</p> 13544</div> 13545</div> 13546<div class="sect4"> 13547<h5 id="jam.language.modules.the__varnames__rule"><a class="anchor" href="#jam.language.modules.the__varnames__rule"></a>The <code>VARNAMES</code> Rule</h5> 13548<div class="listingblock"> 13549<div class="content"> 13550<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-k">rule</span><span class="tok-w"> </span><span class="tok-nf">VARNAMES</span><span class="tok-w"> </span><span class="tok-p">(</span><span class="tok-w"> </span><span class="tok-nv">module</span><span class="tok-w"> </span><span class="tok-p">?</span><span class="tok-w"> </span><span class="tok-p">)</span><span class="tok-w"></span></code></pre> 13551</div> 13552</div> 13553<div class="paragraph"> 13554<p>Returns a list of the names of all variable bindings in the given 13555module. If <em>module</em> is omitted, the names of all variable bindings in 13556the global module are returned.</p> 13557</div> 13558<div class="admonitionblock note"> 13559<table> 13560<tr> 13561<td class="icon"> 13562<div class="title">ℹ</div> 13563</td> 13564<td class="content"> 13565This includes any local variables in rules from the call stack which 13566have not returned at the time of the <code>VARNAMES</code> invocation. 13567</td> 13568</tr> 13569</table> 13570</div> 13571</div> 13572<div class="sect4"> 13573<h5 id="jam.language.modules.the__import__rule"><a class="anchor" href="#jam.language.modules.the__import__rule"></a>The <code>IMPORT</code> Rule</h5> 13574<div class="paragraph"> 13575<p><code>IMPORT</code> allows rule name aliasing across modules:</p> 13576</div> 13577<div class="listingblock"> 13578<div class="content"> 13579<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-k">rule</span><span class="tok-w"> </span><span class="tok-nf">IMPORT</span><span class="tok-w"> </span><span class="tok-p">(</span><span class="tok-w"> </span><span class="tok-nv">source_module</span><span class="tok-w"> </span><span class="tok-p">?</span><span class="tok-w"> </span><span class="tok-p">:</span><span class="tok-w"> </span><span class="tok-nv">source_rules</span><span class="tok-w"> </span><span class="tok-p">*</span><span class="tok-w"></span> 13580<span class="tok-w"> </span><span class="tok-p">:</span><span class="tok-w"> </span><span class="tok-nv">target_module</span><span class="tok-w"> </span><span class="tok-p">?</span><span class="tok-w"> </span><span class="tok-p">:</span><span class="tok-w"> </span><span class="tok-nv">target_rules</span><span class="tok-w"> </span><span class="tok-p">*</span><span class="tok-w"> </span><span class="tok-p">)</span><span class="tok-w"></span></code></pre> 13581</div> 13582</div> 13583<div class="paragraph"> 13584<p>The <code>IMPORT</code> rule copies rules from the <em>source_module</em> into the 13585<em>target_module</em> as local rules. If either <em>source_module</em> or 13586<em>target_module</em> is not supplied, it refers to the global module. 13587<em>source_rules</em> specifies which rules from the <em>source_module</em> to import; 13588<em>target_rules</em> specifies the names to give those rules in 13589<em>target_module</em>. If <em>source_rules</em> contains a name which doesn’t 13590correspond to a rule in <em>source_module</em>, or if it contains a different 13591number of items than <em>target_rules</em>, an error is issued. For example,</p> 13592</div> 13593<div class="listingblock"> 13594<div class="content"> 13595<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-c1"># import m1.rule1 into m2 as local rule m1-rule1.</span> 13596<span class="tok-nb">IMPORT</span><span class="tok-w"> </span>m1<span class="tok-w"> </span>:<span class="tok-w"> </span>rule1<span class="tok-w"> </span>:<span class="tok-w"> </span>m2<span class="tok-w"> </span>:<span class="tok-w"> </span>m1-rule1<span class="tok-w"> </span>;<span class="tok-w"></span> 13597<span class="tok-c1"># import all non-local rules from m1 into m2</span> 13598<span class="tok-nb">IMPORT</span><span class="tok-w"> </span>m1<span class="tok-w"> </span>:<span class="tok-w"> </span>[<span class="tok-w"> </span><span class="tok-nb">RULENAMES</span><span class="tok-w"> </span>m1<span class="tok-w"> </span>]<span class="tok-w"> </span>:<span class="tok-w"> </span>m2<span class="tok-w"> </span>:<span class="tok-w"> </span>[<span class="tok-w"> </span><span class="tok-nb">RULENAMES</span><span class="tok-w"> </span>m1<span class="tok-w"> </span>]<span class="tok-w"> </span>;<span class="tok-w"></span></code></pre> 13599</div> 13600</div> 13601</div> 13602<div class="sect4"> 13603<h5 id="jam.language.modules.the__export__rule"><a class="anchor" href="#jam.language.modules.the__export__rule"></a>The <code>EXPORT</code> Rule</h5> 13604<div class="paragraph"> 13605<p><code>EXPORT</code> allows rule name aliasing across modules:</p> 13606</div> 13607<div class="listingblock"> 13608<div class="content"> 13609<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-k">rule</span><span class="tok-w"> </span><span class="tok-nf">EXPORT</span><span class="tok-w"> </span><span class="tok-p">(</span><span class="tok-w"> </span><span class="tok-nv">module</span><span class="tok-w"> </span><span class="tok-p">?</span><span class="tok-w"> </span><span class="tok-p">:</span><span class="tok-w"> </span><span class="tok-nv">rules</span><span class="tok-w"> </span><span class="tok-p">*</span><span class="tok-w"> </span><span class="tok-p">)</span><span class="tok-w"></span></code></pre> 13610</div> 13611</div> 13612<div class="paragraph"> 13613<p>The <code>EXPORT</code> rule marks <em>rules</em> from the <code>source_module</code> as non-local 13614(and thus exportable). If an element of <em>rules</em> does not name a rule in 13615<em>module</em>, an error is issued. For example,</p> 13616</div> 13617<div class="listingblock"> 13618<div class="content"> 13619<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-k">module</span><span class="tok-w"> </span><span class="tok-nn">X</span><span class="tok-w"> </span><span class="tok-p">{</span><span class="tok-w"></span> 13620<span class="tok-w"> </span><span class="tok-k">local</span><span class="tok-w"> </span><span class="tok-k">rule</span><span class="tok-w"> </span><span class="tok-nf">r</span><span class="tok-w"> </span><span class="tok-nv">{</span><span class="tok-w"> </span><span class="tok-nv">ECHO</span><span class="tok-w"> </span><span class="tok-nv">X.r</span><span class="tok-w"> </span><span class="tok-nv">;</span><span class="tok-w"> </span><span class="tok-nv">}</span><span class="tok-w"></span> 13621<span class="tok-nv">}</span><span class="tok-w"></span> 13622<span class="tok-nv">IMPORT</span><span class="tok-w"> </span><span class="tok-nv">X</span><span class="tok-w"> </span><span class="tok-p">:</span><span class="tok-w"> </span><span class="tok-nv">r</span><span class="tok-w"> </span><span class="tok-p">:</span><span class="tok-w"> </span><span class="tok-p">:</span><span class="tok-w"> </span><span class="tok-nv">r</span><span class="tok-w"> </span><span class="tok-nv">;</span><span class="tok-w"> </span><span class="tok-c1"># error - r is local in X</span> 13623<span class="tok-nv">EXPORT</span><span class="tok-w"> </span><span class="tok-nv">X</span><span class="tok-w"> </span><span class="tok-p">:</span><span class="tok-w"> </span><span class="tok-nv">r</span><span class="tok-w"> </span><span class="tok-nv">;</span><span class="tok-w"></span> 13624<span class="tok-nv">IMPORT</span><span class="tok-w"> </span><span class="tok-nv">X</span><span class="tok-w"> </span><span class="tok-p">:</span><span class="tok-w"> </span><span class="tok-nv">r</span><span class="tok-w"> </span><span class="tok-p">:</span><span class="tok-w"> </span><span class="tok-p">:</span><span class="tok-w"> </span><span class="tok-nv">r</span><span class="tok-w"> </span><span class="tok-nv">;</span><span class="tok-w"> </span><span class="tok-c1"># OK.</span></code></pre> 13625</div> 13626</div> 13627</div> 13628<div class="sect4"> 13629<h5 id="jam.language.modules.the__caller_module__rule"><a class="anchor" href="#jam.language.modules.the__caller_module__rule"></a>The <code>CALLER_MODULE</code> Rule</h5> 13630<div class="listingblock"> 13631<div class="content"> 13632<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-k">rule</span><span class="tok-w"> </span><span class="tok-nf">CALLER_MODULE</span><span class="tok-w"> </span><span class="tok-p">(</span><span class="tok-w"> </span><span class="tok-nv">levels</span><span class="tok-w"> </span><span class="tok-p">?</span><span class="tok-w"> </span><span class="tok-p">)</span><span class="tok-w"></span></code></pre> 13633</div> 13634</div> 13635<div class="paragraph"> 13636<p><code>CALLER_MODULE</code> returns the name of the module scope enclosing the call 13637to its caller (if levels is supplied, it is interpreted as an integer 13638number of additional levels of call stack to traverse to locate the 13639module). If the scope belongs to the global module, or if no such module 13640exists, returns the empty list. For example, the following prints "{Y} 13641{X}":</p> 13642</div> 13643<div class="listingblock"> 13644<div class="content"> 13645<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-k">module</span><span class="tok-w"> </span><span class="tok-nn">X</span><span class="tok-w"> </span><span class="tok-p">{</span><span class="tok-w"></span> 13646<span class="tok-w"> </span><span class="tok-k">rule</span><span class="tok-w"> </span><span class="tok-nf">get-caller</span><span class="tok-w"> </span><span class="tok-nv">{</span><span class="tok-w"> </span><span class="tok-nv">return</span><span class="tok-w"> </span><span class="tok-nv">[</span><span class="tok-w"> </span><span class="tok-nv">CALLER_MODULE</span><span class="tok-w"> </span><span class="tok-nv">]</span><span class="tok-w"> </span><span class="tok-nv">;</span><span class="tok-w"> </span><span class="tok-nv">}</span><span class="tok-w"></span> 13647<span class="tok-w"> </span><span class="tok-nv">rule</span><span class="tok-w"> </span><span class="tok-nv">get-caller's-caller</span><span class="tok-w"> </span><span class="tok-nv">{</span><span class="tok-w"> </span><span class="tok-nv">return</span><span class="tok-w"> </span><span class="tok-nv">[</span><span class="tok-w"> </span><span class="tok-nv">CALLER_MODULE</span><span class="tok-w"> </span><span class="tok-nv">1</span><span class="tok-w"> </span><span class="tok-nv">]</span><span class="tok-w"> </span><span class="tok-nv">;</span><span class="tok-w"> </span><span class="tok-nv">}</span><span class="tok-w"></span> 13648<span class="tok-w"> </span><span class="tok-nv">rule</span><span class="tok-w"> </span><span class="tok-nv">call-Y</span><span class="tok-w"> </span><span class="tok-nv">{</span><span class="tok-w"> </span><span class="tok-nv">return</span><span class="tok-w"> </span><span class="tok-nv">Y.call-X2</span><span class="tok-w"> </span><span class="tok-nv">;</span><span class="tok-w"> </span><span class="tok-nv">}</span><span class="tok-w"></span> 13649<span class="tok-nv">}</span><span class="tok-w"></span> 13650<span class="tok-nv">module</span><span class="tok-w"> </span><span class="tok-nv">Y</span><span class="tok-w"> </span><span class="tok-nv">{</span><span class="tok-w"></span> 13651<span class="tok-w"> </span><span class="tok-nv">rule</span><span class="tok-w"> </span><span class="tok-nv">call-X</span><span class="tok-w"> </span><span class="tok-nv">{</span><span class="tok-w"> </span><span class="tok-nv">return</span><span class="tok-w"> </span><span class="tok-nv">X.get-caller</span><span class="tok-w"> </span><span class="tok-nv">;</span><span class="tok-w"> </span><span class="tok-nv">}</span><span class="tok-w"></span> 13652<span class="tok-w"> </span><span class="tok-nv">rule</span><span class="tok-w"> </span><span class="tok-nv">call-X2</span><span class="tok-w"> </span><span class="tok-nv">{</span><span class="tok-w"> </span><span class="tok-nv">return</span><span class="tok-w"> </span><span class="tok-nv">X.get-caller's-caller</span><span class="tok-w"> </span><span class="tok-nv">;</span><span class="tok-w"> </span><span class="tok-nv">}</span><span class="tok-w"></span> 13653<span class="tok-nv">}</span><span class="tok-w"></span> 13654<span class="tok-nv">callers</span><span class="tok-w"> </span><span class="tok-nv">=</span><span class="tok-w"> </span><span class="tok-nv">[</span><span class="tok-w"> </span><span class="tok-nv">X.get-caller</span><span class="tok-w"> </span><span class="tok-nv">]</span><span class="tok-w"> </span><span class="tok-nv">[</span><span class="tok-w"> </span><span class="tok-nv">Y.call-X</span><span class="tok-w"> </span><span class="tok-nv">]</span><span class="tok-w"> </span><span class="tok-nv">[</span><span class="tok-w"> </span><span class="tok-nv">X.call-Y</span><span class="tok-w"> </span><span class="tok-nv">]</span><span class="tok-w"> </span><span class="tok-nv">;</span><span class="tok-w"></span> 13655<span class="tok-nv">ECHO</span><span class="tok-w"> </span><span class="tok-nv">{$(callers</span><span class="tok-p">)</span>}<span class="tok-w"> </span>;<span class="tok-w"></span></code></pre> 13656</div> 13657</div> 13658</div> 13659<div class="sect4"> 13660<h5 id="jam.language.modules.the__delete_module__rule"><a class="anchor" href="#jam.language.modules.the__delete_module__rule"></a>The <code>DELETE_MODULE</code> Rule</h5> 13661<div class="listingblock"> 13662<div class="content"> 13663<pre class="pygments highlight"><code data-lang="jam"><span></span><span class="tok-k">rule</span><span class="tok-w"> </span><span class="tok-nf">DELETE_MODULE</span><span class="tok-w"> </span><span class="tok-p">(</span><span class="tok-w"> </span><span class="tok-nv">module</span><span class="tok-w"> </span><span class="tok-p">?</span><span class="tok-w"> </span><span class="tok-p">)</span><span class="tok-w"></span></code></pre> 13664</div> 13665</div> 13666<div class="paragraph"> 13667<p><code>DELETE_MODULE</code> removes all of the variable bindings and 13668otherwise-unreferenced rules from the given module (or the global 13669module, if no module is supplied), and returns their memory to the 13670system.</p> 13671</div> 13672<div class="admonitionblock note"> 13673<table> 13674<tr> 13675<td class="icon"> 13676<div class="title">ℹ</div> 13677</td> 13678<td class="content"> 13679Though it won’t affect rules that are currently executing until they 13680complete, <code>DELETE_MODULE</code> should be used with extreme care because it 13681will wipe out any others and all variable (including locals in that 13682module) immediately. Because of the way dynamic binding works, variables 13683which are shadowed by locals will not be destroyed, so the results can 13684be really unpredictable. 13685</td> 13686</tr> 13687</table> 13688</div> 13689</div> 13690</div> 13691</div> 13692<div class="sect2"> 13693<h3 id="jam.miscellaneous"><a class="anchor" href="#jam.miscellaneous"></a>11.3. Miscellaneous</h3> 13694<div class="sect3"> 13695<h4 id="jam.miscellaneous.diagnostics"><a class="anchor" href="#jam.miscellaneous.diagnostics"></a>11.3.1. Diagnostics</h4> 13696<div class="paragraph"> 13697<p>In addition to generic error messages, <code>b2</code> may emit one of the 13698following:</p> 13699</div> 13700<div class="listingblock"> 13701<div class="content"> 13702<pre>warning: unknown rule X</pre> 13703</div> 13704</div> 13705<div class="paragraph"> 13706<p>A rule was invoked that has not been defined with an <code>actions</code> or 13707<code>rule</code> statement.</p> 13708</div> 13709<div class="listingblock"> 13710<div class="content"> 13711<pre>using N temp target(s)</pre> 13712</div> 13713</div> 13714<div class="paragraph"> 13715<p>Targets marked as being temporary (but nonetheless present) have been 13716found.</p> 13717</div> 13718<div class="listingblock"> 13719<div class="content"> 13720<pre>updating N target(s)</pre> 13721</div> 13722</div> 13723<div class="paragraph"> 13724<p>Targets are out-of-date and will be updated.</p> 13725</div> 13726<div class="listingblock"> 13727<div class="content"> 13728<pre>can't find N target(s)</pre> 13729</div> 13730</div> 13731<div class="paragraph"> 13732<p>Source files can’t be found and there are no actions to create them.</p> 13733</div> 13734<div class="listingblock"> 13735<div class="content"> 13736<pre>can't make N target(s)</pre> 13737</div> 13738</div> 13739<div class="paragraph"> 13740<p>Due to sources not being found, other targets cannot be made.</p> 13741</div> 13742<div class="listingblock"> 13743<div class="content"> 13744<pre>warning: X depends on itself</pre> 13745</div> 13746</div> 13747<div class="paragraph"> 13748<p>A target depends on itself either directly or through its sources.</p> 13749</div> 13750<div class="listingblock"> 13751<div class="content"> 13752<pre>don't know how to make X</pre> 13753</div> 13754</div> 13755<div class="paragraph"> 13756<p>A target is not present and no actions have been defined to create it.</p> 13757</div> 13758<div class="listingblock"> 13759<div class="content"> 13760<pre>X skipped for lack of Y</pre> 13761</div> 13762</div> 13763<div class="paragraph"> 13764<p>A source failed to build, and thus a target cannot be built.</p> 13765</div> 13766<div class="listingblock"> 13767<div class="content"> 13768<pre>warning: using independent target X</pre> 13769</div> 13770</div> 13771<div class="paragraph"> 13772<p>A target that is not a dependency of any other target is being 13773referenced with <code>$(<)</code> or <code>$(>)</code>.</p> 13774</div> 13775<div class="listingblock"> 13776<div class="content"> 13777<pre>X removed</pre> 13778</div> 13779</div> 13780<div class="paragraph"> 13781<p><code>B2</code> removed a partially built target after being interrupted.</p> 13782</div> 13783</div> 13784<div class="sect3"> 13785<h4 id="jam.miscellaneous.bugs__limitations"><a class="anchor" href="#jam.miscellaneous.bugs__limitations"></a>11.3.2. Bugs, Limitations</h4> 13786<div class="paragraph"> 13787<p>For parallel building to be successful, the dependencies among files 13788must be properly spelled out, as targets tend to get built in a 13789quickest-first ordering. Also, beware of un-parallelizable commands that 13790drop fixed-named files into the current directory, like <code>yacc(1)</code> does.</p> 13791</div> 13792<div class="paragraph"> 13793<p>A poorly set <code>$(JAMSHELL)</code> is likely to result in silent failure.</p> 13794</div> 13795</div> 13796<div class="sect3"> 13797<h4 id="jam.miscellaneous.fundamentals"><a class="anchor" href="#jam.miscellaneous.fundamentals"></a>11.3.3. Fundamentals</h4> 13798<div class="paragraph"> 13799<p>This section is derived from the official Jam documentation and from 13800experience using it and reading the Jambase rules. We repeat the 13801information here mostly because it is essential to understanding and 13802using Jam, but is not consolidated in a single place. Some of it is 13803missing from the official documentation altogether. We hope it will be 13804useful to anyone wishing to become familiar with Jam and the Boost build 13805system.</p> 13806</div> 13807<div class="ulist"> 13808<ul> 13809<li> 13810<p>Jam <code>rules</code> are actually simple procedural entities. Think of them 13811as functions. Arguments are separated by colons.</p> 13812</li> 13813<li> 13814<p>A Jam <strong>target</strong> is an abstract entity identified by an arbitrary 13815string. The built-in <code>DEPENDS</code> rule creates a link in the dependency 13816graph between the named targets.</p> 13817</li> 13818<li> 13819<p>Note that the original Jam documentation for the built-in <code>INCLUDES</code> 13820rule is incorrect: <code>INCLUDES targets1 : targets2</code> causes everything that 13821depends on a member of 13822<em>targets1</em> to depend on all members of <em>targets2</em>. It does this in an 13823odd way, by tacking <em>targets2</em> onto a special tail section in the 13824dependency list of everything in <em>targets1</em>. It seems to be OK to create 13825circular dependencies this way; in fact, it appears to be the "right 13826thing to do" when a single build action produces both <em>targets1</em> and 13827<em>targets2</em>.</p> 13828</li> 13829<li> 13830<p>When a rule is invoked, if there are <code>actions</code> declared with the same 13831name as the rule, the actions are added to the updating actions for the 13832target identified by the rule’s first argument. It is actually possible 13833to invoke an undeclared rule if corresponding actions are declared: the 13834rule is treated as empty.</p> 13835</li> 13836<li> 13837<p>Targets (other than <code>NOTFILE</code> targets) are associated with paths in 13838the file system through a process called binding. Binding is a process 13839of searching for a file with the same name as the target (sans grist), 13840based on the settings of the target-specific <code>SEARCH</code> and <code>LOCATE</code> 13841variables.</p> 13842</li> 13843<li> 13844<p>In addition to local and global variables, jam allows you to set a 13845variable <code>on</code> a target. Target-specific variable values can usually not 13846be read, and take effect only in the following contexts:</p> 13847<div class="ulist"> 13848<ul> 13849<li> 13850<p>In updating actions, variable values are first looked up <code>on</code> the 13851target named by the first argument (the target being updated). Because 13852Jam builds its entire dependency tree before executing actions, Jam 13853rules make target-specific variable settings as a way of supplying 13854parameters to the corresponding actions.</p> 13855</li> 13856<li> 13857<p>Binding is controlled <em>entirely</em> by the target-specific setting of 13858the <code>SEARCH</code> and <code>LOCATE</code> variables, as described here.</p> 13859</li> 13860<li> 13861<p>In the special rule used for header file scanning, variable values 13862are first looked up <code>on</code> the target named by the rule’s first argument 13863(the source file being scanned).</p> 13864</li> 13865</ul> 13866</div> 13867</li> 13868<li> 13869<p>The "bound value" of a variable is the path associated with the target 13870named by the variable. In build actions, the first two arguments are 13871automatically replaced with their bound values. Target-specific 13872variables can be selectively replaced by their bound values using the 13873<code>bind</code> action modifier.</p> 13874</li> 13875<li> 13876<p>Note that the term "binding" as used in the Jam documentation 13877indicates a phase of processing that includes three sub-phases: 13878<em>binding</em> (yes!), update determination, and header file scanning. The 13879repetition of the term "binding" can lead to some confusion. In 13880particular, the Modifying Binding section in the Jam documentation 13881should probably be titled "Modifying Update Determination".</p> 13882</li> 13883<li> 13884<p>"Grist" is just a string prefix of the form <<em>characters</em>>. It is 13885used in Jam to create unique target names based on simpler names. For 13886example, the file name <code>test.exe</code> may be used by targets in separate 13887sub-projects, or for the debug and release variants of the "same" 13888abstract target. Each distinct target bound to a file called "test.exe" 13889has its own unique grist prefix. The Boost build system also takes full 13890advantage of Jam’s ability to divide strings on grist boundaries, 13891sometimes concatenating multiple gristed elements at the beginning of a 13892string. Grist is used instead of identifying targets with absolute paths 13893for two reasons:</p> 13894<div class="olist arabic"> 13895<ol class="arabic"> 13896<li> 13897<p>The location of targets cannot always be derived solely from what 13898the user puts in a Jamfile, but sometimes depends also on the binding 13899process. Some mechanism to distinctly identify targets with the same 13900name is still needed.</p> 13901</li> 13902<li> 13903<p>Grist allows us to use a uniform abstract identifier for each built 13904target, regardless of target file location (as allowed by setting 13905ALL_LOCATE_TARGET).</p> 13906</li> 13907</ol> 13908</div> 13909</li> 13910<li> 13911<p>When grist is extracted from a name with $(var:G), the result includes 13912the leading and trailing angle brackets. When grist is added to a name 13913with <code>$(var:G=expr)</code>, existing grist is first stripped. Then, if <code>expr</code> is 13914non-empty, leading <s and trailing >s are added if necessary to form an 13915expression of the form <expr2>; <expr2> is then prepended.</p> 13916</li> 13917<li> 13918<p>When Jam is invoked it imports all environment variable settings into 13919corresponding Jam variables, followed by all command-line (-s…​) 13920variable settings. Variables whose name ends in PATH, Path, or path are 13921split into string lists on OS-specific path-list separator boundaries 13922(e.g. ":" for UNIX and ";" for Windows). All other variables are split 13923on space (" ") boundaries. Boost Jam modifies that behavior by allowing 13924variables to be quoted.</p> 13925</li> 13926<li> 13927<p>A variable whose value is an empty list or which consists entirely of 13928empty strings has a negative logical value. Thus, for example, code like 13929the following allows a sensible non-empty default which can easily be 13930overridden by the user:</p> 13931<div class="listingblock"> 13932<div class="content"> 13933<pre>MESSAGE ?\= starting jam... ; 13934if $(MESSAGE) { ECHO The message is: $(MESSAGE) ; }</pre> 13935</div> 13936</div> 13937<div class="paragraph"> 13938<p>If the user wants a specific message, he invokes jam with 13939<code>-sMESSAGE=message 13940 text</code>. If he wants no message, he invokes jam with 13941<code>-sMESSAGE=</code> and nothing at all is printed.</p> 13942</div> 13943</li> 13944<li> 13945<p>The parsing of command line options in Jam can be rather unintuitive, 13946with regards to how other Unix programs accept options. There are two 13947variants accepted as valid for an option:</p> 13948<div class="olist arabic"> 13949<ol class="arabic"> 13950<li> 13951<p><code>-xvalue</code>, and</p> 13952</li> 13953<li> 13954<p><code>-x value</code>.</p> 13955</li> 13956</ol> 13957</div> 13958</li> 13959</ul> 13960</div> 13961</div> 13962</div> 13963</div> 13964</div> 13965<div class="sect1"> 13966<h2 id="b2.history"><a class="anchor" href="#b2.history"></a>12. History</h2> 13967<div class="sectionbody"> 13968<div class="sect2"> 13969<h3 id="_version_4_3_0"><a class="anchor" href="#_version_4_3_0"></a>12.1. Version 4.3.0</h3> 13970<div class="paragraph"> 13971<p>There are many invidual fixes in this release. Many thanks for the 13972contributions. Special thanks to Nikita for the many improvements to msvc 13973and general plugging of support holes in all the compilers.</p> 13974</div> 13975<div class="paragraph"> 13976<p>There are some notable new features from Dmitry, Edward, and Nkita:</p> 13977</div> 13978<div class="ulist"> 13979<ul> 13980<li> 13981<p><strong>New:</strong> Add <code>force-include</code> feature to include headers before all sources. — <em>Nikita Kniazev</em></p> 13982</li> 13983<li> 13984<p><strong>New:</strong> Partial support for Embarcadero C++ compilers based on clang-5. — <em>Edward Diener</em></p> 13985</li> 13986<li> 13987<p><strong>New:</strong> Implement configurable installation prefixes that use features. — <em>Dmitry Arkhipov</em></p> 13988</li> 13989<li> 13990<p><strong>New:</strong> Add <code>translate-path</code> feature. The translate-path feature allows for 13991custom path handling, with a provided rule, on a per target basis. This can 13992be used to support custom path syntax. — <em>René Ferdinand Rivera Morell</em></p> 13993</li> 13994<li> 13995<p><strong>New:</strong> Add portable B2 system install option. This allows the b2 executable 13996and the build system files to live side by side. And hence to be (re)located 13997anywhere on disk. Soon to be used to supports Windows and other installers. 13998This removes the need for the <code>boost-build.jam</code> file for bootstrap. Making 13999it easier for users to get started. — <em>René Ferdinand Rivera Morell</em></p> 14000</li> 14001<li> 14002<p>Unbreak building from VS Preview command prompt. — <em>Marcel Raad</em></p> 14003</li> 14004<li> 14005<p>Fix compiler version check on macOS darwin toolset. — <em>Bo Anderson</em></p> 14006</li> 14007<li> 14008<p>Remove pch target naming restriction on GCC. — <em>Nikita Kniazev</em></p> 14009</li> 14010<li> 14011<p>Select appropriate QNX target platform. — <em>Alexander Karzhenkov</em></p> 14012</li> 14013<li> 14014<p>Various space & performance improvements to the b2 engine build on Windows. — <em>Nikita Kniazev</em></p> 14015</li> 14016<li> 14017<p>Fill extra and pedantic warning options for every compiler. — <em>Nikita Kniazev</em></p> 14018</li> 14019<li> 14020<p>Include OS error reason for engine IO failures. — <em>Nikita Kniazev</em></p> 14021</li> 14022<li> 14023<p>Use /Zc:inline and /Zc:throwingNew flags for better language conformance. — <em>Nikita Kniazev</em></p> 14024</li> 14025<li> 14026<p>Add cxxstd value 20 for C++20. — <em>Andrey Semashev</em></p> 14027</li> 14028<li> 14029<p>Parallel B2 engine compilation on MSVC. — <em>Nikita Kniazev</em></p> 14030</li> 14031<li> 14032<p>Updated instruction-set feature with new x86 targets. — <em>Andrey Semashev</em></p> 14033</li> 14034<li> 14035<p>Pass /nologo to rc on Windows compilers. — <em>Nikita Kniazev</em></p> 14036</li> 14037<li> 14038<p>Fixed negation in conditional properties. — <em>Nikita Kniazev</em></p> 14039</li> 14040<li> 14041<p>Remove leftover manifest generation early exiting. — <em>Nikita Kniazev</em></p> 14042</li> 14043<li> 14044<p>Fix timestamp delta calculation. — <em>Nikita Kniazev</em></p> 14045</li> 14046<li> 14047<p>Add missing assembler options to clang-win.jam, to enable Context to build. — <em>Peter Dimov</em></p> 14048</li> 14049<li> 14050<p>Updated scarce <code>:chars</code> documentation with <code>:BS</code> example. — <em>Nikita Kniazev</em></p> 14051</li> 14052<li> 14053<p>Fix link statically against boost-python on linux. — <em>Joris Carrier</em></p> 14054</li> 14055<li> 14056<p>Ongoing cleanup of engine build warnings. — <em>René Ferdinand Rivera Morell</em></p> 14057</li> 14058<li> 14059<p>Allow self-testing of toolsets that use response files. — <em>René Ferdinand Rivera Morell</em></p> 14060</li> 14061<li> 14062<p>Port <code>Jambase</code> to native C++. Hence removing one of the oldest parts of the 14063original Jam bootstrap process. — <em>René Ferdinand Rivera Morell</em></p> 14064</li> 14065</ul> 14066</div> 14067</div> 14068<div class="sect2"> 14069<h3 id="_version_4_2_0"><a class="anchor" href="#_version_4_2_0"></a>12.2. Version 4.2.0</h3> 14070<div class="paragraph"> 14071<p>This release is predominantly minor fixes and cleanup of the engine. In 14072particular the bootstrap/build process now clearly communicates C++11 14073requirement.</p> 14074</div> 14075<div class="ulist"> 14076<ul> 14077<li> 14078<p>Add <code>saxonhe_dir</code> action. — <em>Richard Hodges</em></p> 14079</li> 14080<li> 14081<p>Add CI testing for historical Boost versions on Windows MSVC. — <em>René Ferdinand Rivera Morell</em></p> 14082</li> 14083<li> 14084<p>Check for C++11 support when building engine. Including an informative 14085error message as to that fact. — <em>René Ferdinand Rivera Morell</em></p> 14086</li> 14087<li> 14088<p>Update Jam grammar parser with latest <code>bison</code> version. — <em>René Ferdinand Rivera Morell</em></p> 14089</li> 14090<li> 14091<p>Allow root <code>b2 b2</code> engine build to work even if <code>bison</code> grammar generator 14092is not available. — <em>René Ferdinand Rivera Morell</em></p> 14093</li> 14094<li> 14095<p>Warning free engine build on at least Windows, macOS, and Linux. — <em>René Ferdinand Rivera Morell</em></p> 14096</li> 14097<li> 14098<p>Sanitize Windows engine build to consistently use ANSI Win32 API. — <em>Mateusz Loskot</em></p> 14099</li> 14100<li> 14101<p>Fix b2 engine not exiting, with error, early when it detects a Jam language 14102error. — <em>Mateusz Loskot</em></p> 14103</li> 14104<li> 14105<p>Print help for local modules, i.e. current dir. — <em>Thomas Brown</em></p> 14106</li> 14107</ul> 14108</div> 14109</div> 14110<div class="sect2"> 14111<h3 id="_version_4_1_0"><a class="anchor" href="#_version_4_1_0"></a>12.3. Version 4.1.0</h3> 14112<div class="paragraph"> 14113<p>Many small bug fixes in this release. But there are some new features also. 14114There’s now an <code>lto</code> feature to specify the use of LTO, and what kind. The 14115existing <code>stdlib</code> feature now has real values and corresponding options 14116for some toolsets. But most importantly there’s new documentation for all 14117the features.</p> 14118</div> 14119<div class="paragraph"> 14120<p>Thank to all the users that contributed to this release with these changes:</p> 14121</div> 14122<div class="ulist"> 14123<ul> 14124<li> 14125<p>Support for VS2019 for intel-vin 19.0. — <em>Edward Diener</em></p> 14126</li> 14127<li> 14128<p>Fix compiler warnings about <code>-std=gnu11</code> when building <code>b2</code> on Cygwin. — <em>Andrey Semashev</em></p> 14129</li> 14130<li> 14131<p>Add example of creating multiple PCHs for individual headers. — <em>René Ferdinand Rivera Morell</em></p> 14132</li> 14133<li> 14134<p>Add QNX threading flags for GCC toolset. — <em>Aurelien Chartier</em></p> 14135</li> 14136<li> 14137<p>Fix version option for IBM and Sun compilers when building b2 engine — <em>Juan Alday</em></p> 14138</li> 14139<li> 14140<p>Rename <code>strings.h</code> to <code>jam_strings.h</code> in <code>b2</code> engine to avoid clash with 14141POSIX <code>strings.h</code> header. — <em>Andrey Semashev</em></p> 14142</li> 14143<li> 14144<p>Add options for <code>cxxstd</code> feature for IBM compiler. — <em>Edward Diener</em></p> 14145</li> 14146<li> 14147<p>Many fixes to intel-win toolset. — <em>Edwad Diener</em></p> 14148</li> 14149<li> 14150<p>Add z15 instruction set for gcc based toolsets. — <em>Neale Ferguson</em></p> 14151</li> 14152<li> 14153<p>Improve using MSVC from a Cygwin shell. — <em>Michael Haubenwallner</em></p> 14154</li> 14155<li> 14156<p>Add LTO feature and corresponding support for gcc and clang toolsets. — <em>Dmitry Arkhipov</em></p> 14157</li> 14158<li> 14159<p>Fix errors when a source doesn’t have a type. — <em>Peter Dimov</em></p> 14160</li> 14161<li> 14162<p>Add documentation for features. — <em>Dmitry Arkhipov</em></p> 14163</li> 14164<li> 14165<p>Enhance <code>stdlib</code> feature, and corresponding documentation, for clang, gcc, 14166and sun toolsets. — <em>Dmitry Arkhipov</em></p> 14167</li> 14168<li> 14169<p>Install rule now makes explicit only the immediate targets it creates. —  <em>Dmitry Arkhipov</em></p> 14170</li> 14171<li> 14172<p>Add armasm (32 and 64) support for msvc toolset. — <em>Michał Janiszewski</em></p> 14173</li> 14174<li> 14175<p>Fix errors with custom un-versioned gcc toolset specifications. — <em>Peter Dimov</em></p> 14176</li> 14177<li> 14178<p>Allow arflags override in gcc toolset specifications. — <em>hyc</em></p> 14179</li> 14180<li> 14181<p>Fix founds libs not making it to the clang-win link command line. — <em>Peter Dimov</em></p> 14182</li> 14183<li> 14184<p>Updated intel-win toolset to support for Intel C++ 19.1. — <em>Edward Diener</em></p> 14185</li> 14186<li> 14187<p>Detect difference between MIPS32 and MIPS64 for OS in b2 engine. — <em>YunQiang Su</em></p> 14188</li> 14189</ul> 14190</div> 14191</div> 14192<div class="sect2"> 14193<h3 id="_version_4_0_1"><a class="anchor" href="#_version_4_0_1"></a>12.4. Version 4.0.1</h3> 14194<div class="paragraph"> 14195<p>This patch release fixes a minor issue when trying to configure toolsets that 14196override the toolset version with a non-version tag. Currently this is only 14197known to be a problem if you: (a) configure a toolset version to something 14198like “tot” (b) in Boost 1.72.0 when it creates cmake install artifacts. 14199Fix for this was provided Peter Dimov.</p> 14200</div> 14201</div> 14202<div class="sect2"> 14203<h3 id="_version_4_0_0"><a class="anchor" href="#_version_4_0_0"></a>12.5. Version 4.0.0</h3> 14204<div class="paragraph"> 14205<p>After even more years of development the landscape of build systems has changed 14206considerably, and so has the landscape of compilers. This version marks the 14207start of B2 transitioning to a C++ implementation. Initially this means that 14208the engine will be compiled as C++ source but that source is still the base 14209C implementation. Over time it will transform to a C++ code base in both the 14210engine and build system. Some changes in this start:</p> 14211</div> 14212<div class="ulist"> 14213<ul> 14214<li> 14215<p>Requires C++ 11 to build engine.</p> 14216</li> 14217<li> 14218<p>Simplified build scripts to make it easier to maintain.</p> 14219</li> 14220<li> 14221<p>Building with C++ optimizations gives an immediate performance improvement.</p> 14222</li> 14223</ul> 14224</div> 14225<div class="paragraph"> 14226<p>Other changes in this release:</p> 14227</div> 14228<div class="ulist"> 14229<ul> 14230<li> 14231<p>Add support for using prebuilt OpenSSL. — <em>Damian Jarek</em></p> 14232</li> 14233<li> 14234<p>Define the riscv architecture feature. — <em>Andreas Schwab</em></p> 14235</li> 14236<li> 14237<p>Add ARM64 as a valid architecture for MSVC. — <em>Marc Sweetgall</em></p> 14238</li> 14239<li> 14240<p>Set coverage flags, from coverage feature, for gcc and clang. — <em>Damian Jarek</em></p> 14241</li> 14242<li> 14243<p>Add s390x CPU and support in gcc/clang. — <em>Neale Ferguson</em></p> 14244</li> 14245<li> 14246<p>Support importing pkg-config packages. — <em>Dmitry Arkhipov</em></p> 14247</li> 14248<li> 14249<p>Support for leak sanitizer. — <em>Damian Jarek</em></p> 14250</li> 14251<li> 14252<p>Fix missing <code>/manifest</code> option in clang-win to fix admin elevation for exes 14253with "update" in the name. — <em>Peter Dimov</em></p> 14254</li> 14255<li> 14256<p>Add <code>freertos</code> to <code>os</code> feature. — <em>Thomas Brown</em></p> 14257</li> 14258<li> 14259<p>Default parallel jobs (<code>-jX</code>) to the available CPU threads. — <em>René Ferdinand Rivera Morell</em></p> 14260</li> 14261<li> 14262<p>Simpler coverage feature. — <em>Hans Dembinski</em></p> 14263</li> 14264<li> 14265<p>Better stacks for sanitizers. — <em>James E. King III</em></p> 14266</li> 14267</ul> 14268</div> 14269<div class="admonitionblock warning"> 14270<table> 14271<tr> 14272<td class="icon"> 14273<div class="title">⚠</div> 14274</td> 14275<td class="content"> 14276The default number of parallel jobs has changed in this release from 14277"1" to the number of cores. There are circumstances when that default can be 14278larger than the allocated cpu resources, for instance in some virtualized 14279container installs. 14280</td> 14281</tr> 14282</table> 14283</div> 14284</div> 14285</div> 14286</div> 14287</div> 14288<div id="footnotes"> 14289<hr> 14290<div class="footnote" id="_footnotedef_1"> 14291<a href="#_footnoteref_1">1</a>. See <a href="#bbv2.reference.features.attributes">the section called “Feature Attributes”</a> 14292</div> 14293<div class="footnote" id="_footnotedef_2"> 14294<a href="#_footnoteref_2">2</a>. Many features will be overridden, rather than added-to, in sub-projects See <a href="#bbv2.reference.features.attributes">the section called “Feature Attributes”</a> for more information 14295</div> 14296<div class="footnote" id="_footnotedef_3"> 14297<a href="#_footnoteref_3">3</a>. see the definition of "free" in <a href="#bbv2.reference.features.attributes">the section called “Feature Attributes”</a>. 14298</div> 14299<div class="footnote" id="_footnotedef_4"> 14300<a href="#_footnoteref_4">4</a>. This name is historic, and will be eventually changed to <code>metatarget</code> 14301</div> 14302<div class="footnote" id="_footnotedef_5"> 14303<a href="#_footnoteref_5">5</a>. This create-then-register pattern is caused by limitations of the Boost.Jam language. Python port is likely to never create duplicate targets. 14304</div> 14305</div> 14306</body> 14307</html>