This document describes the proposed changes to the Geany build system specification and design. This document describes changes from the last released version of Geany (0.18), but also reflects the lessons learned from a first implementation attempt.
The purpose of the changes is to improve the flexibility and configurability of the actions performed by the Build menu.
The main use cases which triggered the changes were:
support for running more genralised commands to support build tools other than make
ability to store customisations in project files to support projects using different tool sets
ability to set working directories for customised commands
GUI setup of all customisations
ability for plugins to affect the build process
Since the terms action, event, command etc. have specific meanings the term operation will be used in this document to describe what happens when a Build menu item is activated.
An operation has a configurable label with mnemonic, to be shown on the Build menu. The label must allow for translations to be provided and an optional icon to be shown on the build menu and the toolbar.
Other than this icon there is no interface between operations and the toolbar, as the toolbar should work by activating the appropriate Build menu item and so does not need an interface to the operations.
The Build menu must be able to trigger operations which are:
internal to the Geany or plugin code, initially:
next error
previous error
show configuration dialog
programs to be executed external to Geany.
External operations must be able to configure the following attributes:
the command to be executed in a shell - a working directory where the command is to be executed - how the command output is handled:
output parsed by Geany to the Build message tab (re-named Compiler tab) and a regex must be configurable for that parsing (or fallback to coded parsing ?still needed?)
output to a terminal (VTE or the configured terminal)
output to Geany’s terminal (or lost if Geany is started fron a Gnome/KDE/Xfce etc menu)
a menu label if the command is stopable, the menu item will change to this label while the command is running and the icon will change to the standard stop icon. Activating the menu item again will attempt to stop the running command.
a sensitivity group, only one operation of a sensitivity group can run at any time, all menu items with operations in the same group are set insensitive while a command in the group is running. The menu item which triggered the operation will also be insensitive if the command is not stopable.
All commands whose output is to be parsed will automatically be in one sensitivity group so that only one parser stream is required at any one time.
The command and working directory fields will accept the following substitutions:
%c{…} - the text returned from a dialog box
%d - the full path of the directory of the current document
%e - the filename of the current document without extension
%f - the filename of the current document
%p - the project base path as configured in the open project
%s - the current file separator (i.e. %d%s%f = full path to the current document)
The substitutions %d, %e, %f will substitute nothing if there is no current named document. The substitution %p will substitute nothing if no project is open.
The dialog box generated by %c will have the menu label as the title, it will contain a text entry with the text inside the {} displayed above the entry. The dialog will have an Ok button which causes the text in the entry to replace the %c{..} and a Cancel button which will replace the %c{…} with nothing. The dialog will default to the last entry and remember previous entries. A missing {} will display no text.
The configuration of operations must come from multiple sources:
defaults
system configuration files (installed with Geany)
user configuration files
the Geany program or plugins
Each source must be able to provide configuration for a specific filetype and for all filetypes not specifically configured.
When more than one source has an operation configured for the same build menu item the one that will be used is chosen using a simple fixed priority order, from first choice to last:
configuration by Geany or a plugin for the filetype of the current document
configuration by Geany or a plugin for any filetype
user configuration for the filetype of the current document
user configuration for any filetype
system configuration for the filetype of the current document
system configuration for any filetype
default values
The first source with a configuration present will provide all values, if a value is not set for an attribute in a configuration then a blank string, off or the first of a list will be used as appropraite to the type of attribute..
The build menu must be able to be organised in to several groups of items with separators between them. Grouping similar operations provides a better user experience in a menu which has the potential to contain widely differing operations. The number of groups and the number of operations in them must be configurable but a maximum must be set at startup. The default and minimum will be 5 sections sized from the top of the menu 3, 4, 2, 2, 1.
The default menu layout is:
current file related operations section, language dependent e.g. for the C language:
Compile current file
Link current file
multi file related operations section, language independent:
Make
Make Custom Target
Make Object
error navigation operations section:
Next error
Previous error
execution related operations section, language independent:
Execute current file
Configuration operations section:
Show configuration dialog
Other than the number of sections and their sizes, all configuration shall be available from the GUI.
Only one dialog shall be used for the whole menu. The dialog shall indicate the form that the menu will take after the changes are applied.
The dialog shall have more than one level of detail so that it will not be overwhelming on first use.
The dialog must be able to edit the configuration for user and project sources for both the filetype of the current document and the filetype independent settings. To prevent the filetype changing the dialog may be modal.
At full detail the dialog must be able to show other configuration sources that may influence the operation that a menu item will perform (eg system or default), however these cannot be changed by the dialog.
Process id per is per sensitivity group
Sensitivity flag for internals to set, gives feedback to update_menu when Geany/plugins want some special sensitivity behaviour.
Each menu item with a %c has a separate dialog memory.
Operation structure should be opaque with getter/setter. The setter should trigger gui update if needed and therefore should be multi-field. Updating all fields that are to change at once allows consistency checking. Updating one field at a time may result in inconsistent states between field updates, (ie update one field creates an inconsistent state until another field is updated to match) so it is difficult to know when it is safe to to check consistency and when it is safe to update the GUI. Also reduces number of potential GUI updates.