<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
"http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
<head>
<meta http-equiv="Content-Type" content="application/xhtml+xml; charset=UTF-8" />
<meta name="generator" content="AsciiDoc 8.6.4" />
<title>Geany Build System User Guide</title>
<style type="text/css">
/* Sans-serif font. */
h1, h2, h3, h4, h5, h6,
div.title, caption.title,
thead, p.table.header,
div#toctitle,
span#author, span#revnumber, span#revdate, span#revremark,
div#footer {
font-family: Arial,Helvetica,sans-serif;
}
/* Serif font. */
div.sectionbody {
font-family: Georgia,"Times New Roman",Times,serif;
}
/* Monospace font. */
tt {
font-size: inherit;
}
body {
margin: 1em 5% 1em 5%;
}
a {
color: blue;
text-decoration: underline;
}
a:visited {
color: fuchsia;
}
em {
font-style: italic;
color: navy;
}
strong {
font-weight: bold;
color: #083194;
}
tt {
font-size: inherit;
color: navy;
}
h1, h2, h3, h4, h5, h6 {
color: #527bbd;
margin-top: 1.2em;
margin-bottom: 0.5em;
line-height: 1.3;
}
h1, h2, h3 {
border-bottom: 2px solid silver;
}
h2 {
padding-top: 0.5em;
}
h3 {
float: left;
}
h3 + * {
clear: left;
}
div.sectionbody {
margin-left: 0;
}
hr {
border: 1px solid silver;
}
p {
margin-top: 0.5em;
margin-bottom: 0.5em;
}
ul, ol, li > p {
margin-top: 0;
}
ul > li { color: #aaa; }
ul > li > * { color: black; }
pre {
padding: 0;
margin: 0;
}
span#author {
color: #527bbd;
font-weight: bold;
font-size: 1.1em;
}
span#email {
}
span#revnumber, span#revdate, span#revremark {
}
div#footer {
font-size: small;
border-top: 2px solid silver;
padding-top: 0.5em;
margin-top: 4.0em;
}
div#footer-text {
float: left;
padding-bottom: 0.5em;
}
div#footer-badges {
float: right;
padding-bottom: 0.5em;
}
div#preamble {
margin-top: 1.5em;
margin-bottom: 1.5em;
}
div.tableblock, div.imageblock, div.exampleblock, div.verseblock,
div.quoteblock, div.literalblock, div.listingblock, div.sidebarblock,
div.admonitionblock {
margin-top: 1.0em;
margin-bottom: 1.5em;
}
div.admonitionblock {
margin-top: 2.0em;
margin-bottom: 2.0em;
margin-right: 10%;
color: #606060;
}
div.content { /* Block element content. */
padding: 0;
}
/* Block element titles. */
div.title, caption.title {
color: #527bbd;
font-weight: bold;
text-align: left;
margin-top: 1.0em;
margin-bottom: 0.5em;
}
div.title + * {
margin-top: 0;
}
td div.title:first-child {
margin-top: 0.0em;
}
div.content div.title:first-child {
margin-top: 0.0em;
}
div.content + div.title {
margin-top: 0.0em;
}
div.sidebarblock > div.content {
background: #ffffee;
border: 1px solid #dddddd;
border-left: 4px solid #f0f0f0;
padding: 0.5em;
}
div.listingblock > div.content {
border: 1px solid #dddddd;
border-left: 5px solid #f0f0f0;
background: #f8f8f8;
padding: 0.5em;
}
div.quoteblock, div.verseblock {
padding-left: 1.0em;
margin-left: 1.0em;
margin-right: 10%;
border-left: 5px solid #f0f0f0;
color: #777777;
}
div.quoteblock > div.attribution {
padding-top: 0.5em;
text-align: right;
}
div.verseblock > pre.content {
font-family: inherit;
font-size: inherit;
}
div.verseblock > div.attribution {
padding-top: 0.75em;
text-align: left;
}
/* DEPRECATED: Pre version 8.2.7 verse style literal block. */
div.verseblock + div.attribution {
text-align: left;
}
div.admonitionblock .icon {
vertical-align: top;
font-size: 1.1em;
font-weight: bold;
text-decoration: underline;
color: #527bbd;
padding-right: 0.5em;
}
div.admonitionblock td.content {
padding-left: 0.5em;
border-left: 3px solid #dddddd;
}
div.exampleblock > div.content {
border-left: 3px solid #dddddd;
padding-left: 0.5em;
}
div.imageblock div.content { padding-left: 0; }
span.image img { border-style: none; }
a.image:visited { color: white; }
dl {
margin-top: 0.8em;
margin-bottom: 0.8em;
}
dt {
margin-top: 0.5em;
margin-bottom: 0;
font-style: normal;
color: navy;
}
dd > *:first-child {
margin-top: 0.1em;
}
ul, ol {
list-style-position: outside;
}
ol.arabic {
list-style-type: decimal;
}
ol.loweralpha {
list-style-type: lower-alpha;
}
ol.upperalpha {
list-style-type: upper-alpha;
}
ol.lowerroman {
list-style-type: lower-roman;
}
ol.upperroman {
list-style-type: upper-roman;
}
div.compact ul, div.compact ol,
div.compact p, div.compact p,
div.compact div, div.compact div {
margin-top: 0.1em;
margin-bottom: 0.1em;
}
div.tableblock > table {
border: 3px solid #527bbd;
}
thead, p.table.header {
font-weight: bold;
color: #527bbd;
}
tfoot {
font-weight: bold;
}
td > div.verse {
white-space: pre;
}
p.table {
margin-top: 0;
}
/* Because the table frame attribute is overriden by CSS in most browsers. */
div.tableblock > table[frame="void"] {
border-style: none;
}
div.tableblock > table[frame="hsides"] {
border-left-style: none;
border-right-style: none;
}
div.tableblock > table[frame="vsides"] {
border-top-style: none;
border-bottom-style: none;
}
div.hdlist {
margin-top: 0.8em;
margin-bottom: 0.8em;
}
div.hdlist tr {
padding-bottom: 15px;
}
dt.hdlist1.strong, td.hdlist1.strong {
font-weight: bold;
}
td.hdlist1 {
vertical-align: top;
font-style: normal;
padding-right: 0.8em;
color: navy;
}
td.hdlist2 {
vertical-align: top;
}
div.hdlist.compact tr {
margin: 0;
padding-bottom: 0;
}
.comment {
background: yellow;
}
.footnote, .footnoteref {
font-size: 0.8em;
}
span.footnote, span.footnoteref {
vertical-align: super;
}
#footnotes {
margin: 20px 0 20px 0;
padding: 7px 0 0 0;
}
#footnotes div.footnote {
margin: 0 0 5px 0;
}
#footnotes hr {
border: none;
border-top: 1px solid silver;
height: 1px;
text-align: left;
margin-left: 0;
width: 20%;
min-width: 100px;
}
div.colist td {
padding-right: 0.5em;
padding-bottom: 0.3em;
vertical-align: top;
}
div.colist td img {
margin-top: 0.3em;
}
@media print {
div#footer-badges { display: none; }
}
div#toc {
margin-bottom: 2.5em;
}
div#toctitle {
color: #527bbd;
font-size: 1.1em;
font-weight: bold;
margin-top: 1.0em;
margin-bottom: 0.1em;
}
div.toclevel1, div.toclevel2, div.toclevel3, div.toclevel4 {
margin-top: 0;
margin-bottom: 0;
}
div.toclevel2 {
margin-left: 2em;
font-size: 0.9em;
}
div.toclevel3 {
margin-left: 4em;
font-size: 0.9em;
}
div.toclevel4 {
margin-left: 6em;
font-size: 0.9em;
}
span.aqua { color: aqua; }
span.black { color: black; }
span.blue { color: blue; }
span.fuchsia { color: fuchsia; }
span.gray { color: gray; }
span.green { color: green; }
span.lime { color: lime; }
span.maroon { color: maroon; }
span.navy { color: navy; }
span.olive { color: olive; }
span.purple { color: purple; }
span.red { color: red; }
span.silver { color: silver; }
span.teal { color: teal; }
span.white { color: white; }
span.yellow { color: yellow; }
span.aqua-background { background: aqua; }
span.black-background { background: black; }
span.blue-background { background: blue; }
span.fuchsia-background { background: fuchsia; }
span.gray-background { background: gray; }
span.green-background { background: green; }
span.lime-background { background: lime; }
span.maroon-background { background: maroon; }
span.navy-background { background: navy; }
span.olive-background { background: olive; }
span.purple-background { background: purple; }
span.red-background { background: red; }
span.silver-background { background: silver; }
span.teal-background { background: teal; }
span.white-background { background: white; }
span.yellow-background { background: yellow; }
span.big { font-size: 2em; }
span.small { font-size: 0.6em; }
</style>
<script type="text/javascript">
/*<+'])');
// Function that scans the DOM tree for header elements (the DOM2
// nodeIterator API would be a better technique but not supported by all
// browsers).
var iterate = function (el) {
for (var i = el.firstChild; i != null; i = i.nextSibling) {
if (i.nodeType == 1 /* Node.ELEMENT_NODE */) {
var mo = re.exec(i.tagName);
if (mo && (i.getAttribute("class") || i.getAttribute("className")) != "float") {
result[result.length] = new TocEntry(i, getText(i), mo[1]-1);
}
iterate(i);
}
}
}
iterate(el);
return result;
}
var toc = document.getElementById("toc");
var entries = tocEntries(document.getElementById("content"), toclevels);
for (var i = 0; i < entries.length; ++i) {
var entry = entries[i];
if (entry.element.id == "")
entry.element.id = "_toc_" + i;
var a = document.createElement("a");
a.href = "#" + entry.element.id;
a.appendChild(document.createTextNode(entry.text));
var div = document.createElement("div");
div.appendChild(a);
div.className = "toclevel" + entry.toclevel;
toc.appendChild(div);
}
if (entries.length == 0)
toc.parentNode.removeChild(toc);
},
/////////////////////////////////////////////////////////////////////
// Footnotes generator
/////////////////////////////////////////////////////////////////////
/* Based on footnote generation code from:
* http://www.brandspankingnew.net/archive/2005/07/format_footnote.html
*/
footnotes: function () {
var cont = document.getElementById("content");
var noteholder = document.getElementById("footnotes");
var spans = cont.getElementsByTagName("span");
var refs = {};
var n = 0;
for (i=0; i<spans.length; i++) {
if (spans[i].className == "footnote") {
n++;
// Use [\s\S] in place of . so multi-line matches work.
// Because JavaScript has no s (dotall) regex flag.
note = spans[i].innerHTML.match(/\s*\[([\s\S]*)]\s*/)[1];
noteholder.innerHTML +=
"<div class='footnote' id='_footnote_" + n + "'>" +
"<a href='#_footnoteref_" + n + "' title='Return to text'>" +
n + "</a>. " + note + "</div>";
spans[i].innerHTML =
"[<a id='_footnoteref_" + n + "' href='#_footnote_" + n +
"' title='View footnote' class='footnote'>" + n + "</a>]";
var id =spans[i].getAttribute("id");
if (id != null) refs["#"+id] = n;
}
}
if (n == 0)
noteholder.parentNode.removeChild(noteholder);
else {
// Process footnoterefs.
for (i=0; i<spans.length; i++) {
if (spans[i].className == "footnoteref") {
var href = spans[i].getElementsByTagName("a")[0].getAttribute("href");
href = href.match(/#.*/)[0]; // Because IE return full URL.
n = refs[href];
spans[i].innerHTML =
"[<a href='#_footnote_" + n +
"' title='View footnote' class='footnote'>" + n + "</a>]";
}
}
}
}
}
/*]]>*/
</script>
</head>
<body class="article" style="max-width:40em">
<div id="header">
<h1>Geany Build System User Guide</h1>
<span id="author">Lex Trotman</span><br />
<span id="revdate">Version 0.1 for Geany 0.19 and up</span>
</div>
<div id="content">
<div class="sect1">
<h2 id="_introduction">Introduction</h2>
<div class="sectionbody">
<div class="paragraph"><p>At some point in most software development workflows there comes a time when
the editing is over and a
command needs to be run. Some of the commands used are:</p></div>
<div class="ulist"><ul>
<li>
<p>
Simply running the program using an interpreter, eg Python code, or viewing
HTML, where the command depends on the language being used.
</p>
</li>
<li>
<p>
Compiling a source file and running the result, or building a document where
again the command depends on the language in use.
</p>
</li>
<li>
<p>
Compiling and linking several source files and running/viewing the result
</p>
</li>
<li>
<p>
Complex processes involving multiple source files, installation etc.
</p>
</li>
</ul></div>
<div class="paragraph"><p>Where multiple files are involved it is usual to use some sort of build tool,
make, Cmake, JHbuild, BJam, Ant, Scons, WAF, Fabricate etc. These tools
usually have their own configuration and the commands to activate them do not
depend on the language the source files use.</p></div>
<div class="paragraph"><p>It is also rare that a programmer works on only one thing at a time, most of
us have several projects (using the word in its normal English meaning) on the
go at one time. These may need different tool sets, even for the same
source language.</p></div>
<div class="paragraph"><p>Overall there can be potentially quite complex requirements.</p></div>
<div class="paragraph"><p>Development environments have traditionally addressed this complexity in one
of two ways:</p></div>
<div class="olist arabic"><ol class="arabic">
<li>
<p>
Limiting the complexity by restricting the user to one or two tool sets.
This tends to result in tight integration and detailed support from the
development environment.
</p>
</li>
<li>
<p>
Providing a lot of flexibility allowing users to configure the tools that
suit them. This tends to result in a slightly more arms length approach to
the integration of tools.
</p>
</li>
</ol></div>
<div class="paragraph"><p>The approach of limiting the tool sets is appropriate for development
environments which concentrate on limited languages, the original model of
IDEs like Eclipse and Netbeans which heavily integrated the Java workflow.</p></div>
<div class="paragraph"><p>However Geany supports a wide range of platforms and programming and
documentation languages so it is more appropriate that it takes the approach
of providing flexibility.</p></div>
<div class="paragraph"><p>This document describes the implementation of that flexibility in Geany, how
it is presented to the user and how it is configured using the GUI and by
editing the configuration files.</p></div>
</div>
</div>
<div class="sect1">
<h2 id="Using">Using the Build System, the Build Menu</h2>
<div class="sectionbody">
<div class="paragraph"><p>Geany supports a wide range of user experience, from beginners to experts,
from occasional users to continuous users. So it is important that its
flexibility is presented to the user in a simple, intuitive manner. This is
provided by the Build menu.</p></div>
<div class="paragraph"><p>image of menu here</p></div>
<div class="paragraph"><p>The menu is broken into sections that roughly follow the usual workflow for
software/document development.</p></div>
<div class="olist arabic"><ol class="arabic">
<li>
<p>
The top section generally provides menu items for working with the file you
are currently working on, eg to compile it. These commands naturally depend
on the language the file uses, and the menu items change as you change files.
This section may even disappear entirely if Geany doesn’t know what to do with
a particular filetype (specifically filetype None).
</p>
</li>
<li>
<p>
The second section generally provides menu items that do not depend on the
specific file, usually they are for working on groups of files, eg running a
builder program.
</p>
</li>
<li>
<p>
The third section helps with navigation to the places that the tools found
errors in your source so you can correct them.
</p>
</li>
<li>
<p>
The fourth section provides methods of executing the program that results
from a successful compile/build, or of viewing resulting documents. These
commands may depend on the type of the source file or may not.
</p>
</li>
<li>
<p>
The final section opens a dialog to assist in configuration (see
<a href="#GUI Configuration">GUI Configuration</a> below)
</p>
</li>
</ol></div>
<div class="paragraph"><p>This structure has been used by Geany for some time and has proven easy to use
and flexible. Many other development environments also use a similar
arrangement further supporting its utility.</p></div>
<div class="paragraph"><p>Commands from the first and second sections are run in such a way that Geany
can see their output and can parse it for recognisable messages, usually
errors. The results of this parse are used to mark the source file and to
allow clicking on the message in the compile window to cause the editor to go
to that file and line.</p></div>
</div>
</div>
<div class="sect1">
<h2 id="_implementation_how_flexibility_is_achieved">Implementation, how flexibility is achieved</h2>
<div class="sectionbody">
<div class="paragraph"><p>Behind the simple menu presentation to the user Geany still has to manage the
complexity of the range of use-cases described in the introduction and map it
to the menu.</p></div>
<div class="paragraph"><p>This is achieved using a technique that is common in software, ordering the
sources of information from most general to most specific and having more
specific settings override less specific ones. Examples of its use that you
may be familiar with include object oriented languages where functions
redefined on derived (ie more specific) types override the same function of
the (more general) base type, or cascading style sheets for HTML where more
specifc and later settings override less specific/earlier one.</p></div>
<div class="paragraph"><p>This overriding occurs independently for each position in the build menu, so
some menu items may derive their settings from the user, some from the project
and some from the system sources.</p></div>
<div class="paragraph"><p>For the build system configuration the sources of the settings are fixed and
the ordering (from general to specific) is:</p></div>
<div class="olist arabic"><ol class="arabic">
<li>
<p>
default settings coded in Geany
</p>
</li>
<li>
<p>
settings in system the installed filetype file for the type of file selected
in the editor
</p>
</li>
<li>
<p>
settings from the user preferences file
</p>
</li>
<li>
<p>
settings from the user configured filetype file for the type of file selected
in the editor
</p>
</li>
<li>
<p>
settings independent of filetype from the open project file
</p>
</li>
<li>
<p>
settings for a specific filetype for the type of file selected in the
editor which come from the open project file
</p>
</li>
</ol></div>
<div class="paragraph"><p>Remember the setting from the source lowest in the list "wins", ie that is
what is used in the particular menu item, and each menu item is determined
individually.</p></div>
<div class="paragraph"><p>Not all the sources will exist, for example the user may have no configured
filetype files or may not have a project open. Missing sources are simply
ignored.</p></div>
<div class="paragraph"><p>Notice that in reality there are only three sources, system, user and project
settings with project overriding user overriding system. Within each of these,
settings that depend on the filetype of the file selected in the editor are
considered more specific than, and so override, settings for all filetypes.</p></div>
<div class="paragraph"><p>This simple paradigm handles most of the use cases outlined in the introduction.</p></div>
</div>
</div>
<div class="sect1">
<h2 id="GUI_Configuration">Configuring with the GUI, the easy way</h2>
<div class="sectionbody">
<div class="paragraph"><p>Geany provides GUI configuration dialogs for some of the build system
settings. To keep the GUI simple not all combinations of settings can be
handled from the GUI, but the most common can. All configuration
combinations can be achieved by hand editing the configuration files as
described in the next section. Note that even if you do end up hand
editing, you should start off defining as much as you can using the GUI so
that you will have a template to use for your changes.</p></div>
<div class="paragraph"><p>There are two configuration dialogs:</p></div>
<div class="olist arabic"><ol class="arabic">
<li>
<p>
one for editing user preference settings, activated by the "Set Build
Commands" menu item, and
</p>
</li>
<li>
<p>
one for editing project preferences settings, it is a tab in the
"Project"→"Properties" dialog and is only available when a project is open.
</p>
</li>
</ol></div>
<div class="paragraph"><p>Both dialogs are arranged the same:</p></div>
<div class="paragraph"><p>image of dialog here</p></div>
<div class="paragraph"><p>The dialog shows the three configurable sections of the build menu and the
items in them in the same order as they are shown on the finished menu.</p></div>
<div class="paragraph"><p>The dialog shows only the configurable sections of the build menu, section
three (the navigate error items) and section five (the set build commands)
cannot be configured and are not shown to avoid the dialog getting too big.</p></div>
<div class="paragraph"><p>Like the menu the dialog shows the commands for menu items in section one that
relate to the filetype of the file currently selected in the editor.</p></div>
<div class="paragraph"><p>Thus the dialog directly relates to the menu that is available as soon as it
is closed.</p></div>
<div class="paragraph"><p>The three columns show:</p></div>
<div class="olist arabic"><ol class="arabic">
<li>
<p>
the label to be shown on the menu,
</p>
</li>
<li>
<p>
the command to be executed, and
</p>
</li>
<li>
<p>
the working directory to run the command in.
</p>
</li>
</ol></div>
<div class="paragraph"><p>The numbers of items in each section of the menu are set at startup by
hidden preferences (see the Geany manual), so there can be spare unused
items which show in the dialog, but if they do not have a label, they are
not shown on the menu (well after all what good is a blank menu item).</p></div>
<div class="paragraph"><p>To add/edit a label click on the button in the label column and a sub-dialog
will open. If you precede a character with an underscore (_) that character
will be the mnemonic character for that menu item, make sure that they are
all unique within the menu.</p></div>
<div class="paragraph"><p>To remove an item use the clear button on the right, do not just remove the
label.</p></div>
<div class="admonitionblock">
<table><tr>
<td class="icon">
<div class="title">Note</div>
</td>
<td class="content">An entry with a blank label (you deleted all the characters in
the label submenu) will not show in the menu, but will still override lower
priority entries, this is how you can hide unwanted default menu items, and
so projects can ensure that there are no unwanted user configurations or
defaults that could cause confusion.</td>
</tr></table>
</div>
<div class="paragraph"><p>Within the command and working directory entries the following character
strings are substituted when the command is run.</p></div>
<div class="dlist"><dl>
<dt class="hdlist1">
<strong>%f</strong>
</dt>
<dd>
<p>
replaced by the filename of the file selected in the editor when the
menu item is selected.
</p>
</dd>
<dt class="hdlist1">
<strong>%e</strong>
</dt>
<dd>
<p>
replaced by the same filename but without the last extension.
</p>
</dd>
<dt class="hdlist1">
<strong>%d</strong>
</dt>
<dd>
<p>
replaced by the absolute path of the directory of the file selected
in the editor when the menu item is selected.
</p>
</dd>
<dt class="hdlist1">
<strong>%p</strong>
</dt>
<dd>
<p>
replaced by the absolute path of the base directory of the currently
open project.
</p>
</dd>
</dl></div>
<div class="paragraph"><p>More than one substitution can be made so for instance <strong>%d\%e.exe</strong> could be
used for the absolute filename of an executable on a windows system.</p></div>
<div class="paragraph"><p>An empty command will of course do nothing, but an empty working directory
will default to the same directory as <strong>%d</strong>.</p></div>
<div class="paragraph"><p>Since the commands run by the first two menu sections have the output parsed
for error messages, each of those sections has a regular expression that can
customise the parse. This is a GNU-style extended regular expression where
the first two match groups provide the filename and the line number. These
can occur in any order, a match group containing only digits is taken as the
line number and the othe ris taken as the filename. If no regular
expression is specified for a menu section then a hard coded default parser
that matches many of the common error message formats will be used for the
menu items in that section.</p></div>
<div class="paragraph"><p>Changes are not saved until you click ok.</p></div>
<div class="paragraph"><p>Remember that these comamnds can be set in the project preferences where they
will be applicable only when the project is open. These settings will
override settings in the user preferences dialog. If this is the case the
whole row of the user preferences dialog will be insensitive and will show the
values configured by the project preferences. This ensures that the user
preference dialog continues to show the menu as it will be when the dialog is
closed, and it also prevents possible confusion from editing a user preference
setting and finding that it has no effect.</p></div>
<div class="paragraph"><p>When there is a setting that can be overridden by editing it in this dialog
(eg user by project or default by user), it will be shown in a lighter text
colour. When you start to edit anything in the row, all the values from the
settings being overridden are copied to the dialog and so will become normal
coloured text. This copying ensures that all entries are complete.</p></div>
</div>
</div>
<div class="sect1">
<h2 id="_configuring_by_hand_with_absolute_power_comes_absolute_responsibility">Configuring by hand, with absolute power comes absolute responsibility</h2>
<div class="sectionbody">
<div class="paragraph"><p>This section assumes that you have the basic skills to find the files to edit
and understand the basic layout of Geany configuration files. If not review
the manual now.</p></div>
<div class="paragraph"><p>As the implementation section above explained there are six sources of build
system settings. Five of them are files that can be edited, but you should
not edit the system filetype files. These are overwritten each time you
upgrade Geany and you will lose your customisations.</p></div>
<div class="paragraph"><p>Also the project filetype dependent settings and prject filetype independent
settings are both stored in the project configuration (the .geany) file, so
in fact there are only three places to edit:</p></div>
<div class="olist arabic"><ol class="arabic">
<li>
<p>
filetype files in the user configuration directory, <em>filetype.</em>*ext*
where <strong>ext</strong> is a filetype name.
</p>
</li>
<li>
<p>
the user preference file , <em>geany.conf</em> in the user configuration
directory, and
</p>
</li>
<li>
<p>
the project file <strong>project_name</strong><em>.geany</em> which can be stored in the
project tree or outside it as you chose.
</p>
</li>
</ol></div>
<div class="paragraph"><p>Within these files only the contents of the <em>[build_menu]</em> section will be
discussed, but first a mention of the <em>[build_settings]</em> section.</p></div>
<div class="sect2">
<h3 id="_em_build_settings_em"><em>[build_settings]</em></h3>
<div class="paragraph"><p>The <em>[build_settings]</em> section is the section where build settings were
stored pre-Geany 0.19. So that the system filetypes files didn’t have to
all be updated at once and to remain backward compatible with older user
configurations, the settings in the <em>[build_settings]</em> section are loaded
it the menu item they are defining is not already defined by a
<em>[build_menu]</em> section entry in the same file. This has worked so well
that at the time of writing almost no system filetypes files have been
converted.</p></div>
<div class="paragraph"><p>Geany 0.19 and later will only write changes made in the build GUI to the
<em>[build_menu]</em> section and will not touch the <em>[build_settings]</em> section.
Because of the restricted changes that can be made in the GUI this should
work. But the semantics of the two sections are different, so when you are
hand editing you probably should not have both sections in the same file.</p></div>
</div>
<div class="sect2">
<h3 id="_em_build_menu_em"><em>[build_menu]</em></h3>
<div class="paragraph"><p>As noted before, filetype dependent settings are only considered if the file
currently selected in the editor matches the filetype the setting is for.
For settings in the filetype file, clearly that is the filetype the settings
are in, but for project settings both the filetype and non-filetype
dependent settings are stored in the project file. As detailed below, the
format of the entries will specify which filetype they apply to.</p></div>
<div class="paragraph"><p>As described in <a href="#Using">Using</a> the Build menu is divided into sections with filetype
dependent items, filetype independent items and execute items.</p></div>
<div class="paragraph"><p>Unlike editing with the GUI, when configuring by hand, despite the names,
this division is purely convention, there is no restriction on which section
of the Build menu can be configured by which source, filetype files can
configure menu items in the filetype independent section of the menu and
vice versa.</p></div>
<div class="paragraph"><p>But why would you want to mix things up like that?</p></div>
<div class="paragraph"><p>Consider a Ruby programmer, it might be appropriate to configure the Ruby
filetype to replace the Make commands in the filetype independent section of
the Build menu with Rake commands, while still having Make available for
other languages.</p></div>
<div class="paragraph"><p>And although the default execute command uses the name of the file currently
selected in the editor, this is incorrect when using builders like make,
since they generate the same target program irrespective of the file open in
the editor. A solution is to have a project file configured to override
the default execute with a command that runs the fixed
result of the builder. Putting this in the project file allows it to be kept
with the commands used to build the executable and overrides the user and
system filetype dependent settings. Putting it in the user filetype
independent settings would not work as it would be overridden by any user
filetype settings (although you could delete those of course).</p></div>
<div class="paragraph"><p>Of course this flexibility can be used for evil as well as good, moving menu
items around in shared configurations without reason is sure to confuse other
users, so don’t do it.</p></div>
<div class="paragraph"><p>Entries in the <em>[build_menu]</em> section of configuration files all have the
same format:</p></div>
<div class="listingblock">
<div class="content">
<pre><tt> SS_NN_FF</tt></pre>
</div></div>
<div class="paragraph"><p>where:</p></div>
<div class="dlist"><dl>
<dt class="hdlist1">
SS
</dt>
<dd>
<p>
is a two letter mnemonic for the menu section:
</p>
<div class="dlist"><dl>
<dt class="hdlist1">
FT
</dt>
<dd>
<p>
for the filetype (first) section
</p>
</dd>
<dt class="hdlist1">
NF
</dt>
<dd>
<p>
for the non-filetype (second) section
</p>
</dd>
<dt class="hdlist1">
EX
</dt>
<dd>
<p>
for the execute (fourth) section
</p>
</dd>
</dl></div>
</dd>
<dt class="hdlist1">
NN
</dt>
<dd>
<p>
is a two digit decimal number of the position within the section,
starting at 00
</p>
</dd>
<dt class="hdlist1">
FF
</dt>
<dd>
<p>
is a two character mnemonic for the field to change:
</p>
<div class="dlist"><dl>
<dt class="hdlist1">
LB
</dt>
<dd>
<p>
is the text of the label, remember that an underscore prefixes the
mnemonic character
</p>
</dd>
<dt class="hdlist1">
CM
</dt>
<dd>
<p>
is the command field
</p>
</dd>
<dt class="hdlist1">
WD
</dt>
<dd>
<p>
is the working directory field
</p>
</dd>
</dl></div>
</dd>
</dl></div>
<div class="paragraph"><p>The label field entries can be localised by specifying the language in square
brackets after the entry name, there may be several entries with different
translations, eg</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>FT_00_LB = _Beer!
FT_00_LB[de] = _Bier!
FT_00_LB[fr] = _Bière!
FT_00_CM = drink
FT_00_WD = bar</tt></pre>
</div></div>
<div class="paragraph"><p>To allow entries for multiple filetypes to be stored in the one project
file, the entries can be prefixed by the filetype name, eg</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>CFT_01_LB = Compile
CFT_01_CM = gcc -c %f
CFT_01_WD =
C++FT_01_LB = Compile
C++FT_01_CM = g++ -g -c %f
C++FT_01_WD =</tt></pre>
</div></div>
<div class="paragraph"><p>This prefixing only applies to project files.</p></div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_miscellaneous_use_cases">Miscellaneous Use-Cases</h2>
<div class="sectionbody">
<div class="sect2">
<h3 id="_multiple_project_files">Multiple Project Files</h3>
<div class="paragraph"><p>There is no reason that you cannot have multiple project files for the one
source tree allowing commands for differing uses to be stored, but not mixed.
An example would be to have "secret-project-x-linux.geany" that used Gcc and
friends to compile the project and "secret-project-x-windows.geany" that
contained the commands to compile with the windows tools.</p></div>
<div class="paragraph"><p>Since you can only get one set of commands or the other instead of them side
by side in the same menu there is no chance of hitting the wrong one.</p></div>
<div class="paragraph"><p>When doing this it is best to turn project session files off.</p></div>
</div>
<div class="sect2">
<h3 id="_different_build_types">Different Build Types</h3>
<div class="paragraph"><p>Often software has the concept of different build types which use differing
options such as "debug", "release" or "testing".</p></div>
<div class="paragraph"><p>These differing commands are good candidates for replacing the default Make
commands, either in the project or your own user preferences if you haven’t
used a project.</p></div>
<div class="paragraph"><p>The following image shows the project configuration dialog with some likely
option sets.</p></div>
<div class="paragraph"><p>include image here</p></div>
</div>
</div>
</div>
</div>
<div id="footnotes"><hr /></div>
<div id="footer">
<div id="footer-text">
Last updated 2011-05-12 21:16:46 EST
</div>
</div>
</body>
</html>