Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Next revision		Previous revision
howtos:configurebuildmenu [2011/05/31 21:39] – move build system howto into howtos namespace enricohowtos:configurebuildmenu [2023/01/21 02:15] (current) – Correct build_menu to build-menu elextr
Line 1: Line 1:
-====== User Guide to configuring the Geany Build Menu ======+<WRAP 55em> 
 +====== User Guide to configuring the Build Menu ======
 Lex Trotman Lex Trotman
 Version 0.1 for Geany 0.19 and up Version 0.1 for Geany 0.19 and up
Line 9: Line 10:
 command needs to be run.  Some of the commands used are: command needs to be run.  Some of the commands used are:
  
-  * Simply running the program using an interpreter, eg Python code, or viewing HTML, where the command depends on the language being used.+  * Simply running the program using an interpreter, e.g. Python code, or viewing HTML, where the command depends on the language being used.
   * Compiling a source file and running the result, or building a document, where again the command depends on the language in use.   * Compiling a source file and running the result, or building a document, where again the command depends on the language in use.
   * Compiling and linking several source files and running/viewing the result   * Compiling and linking several source files and running/viewing the result
-  * Complex processes involving multiple source files, installation etc.+  * Complex processes involving multiple source files, installation, etc.
  
 Where multiple files are involved it is usual to use some sort of build tool,  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 +make, CMake, JHbuild, BJam, Ant, SCons, WAF, Fabricate, etc.  These tools 
 usually have their own configuration and the commands to activate them do not  usually have their own configuration and the commands to activate them do not 
 depend on the language the source files use. depend on the language the source files use.
  
-It is also rare that a programmer works on only one thing at a time, most of +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  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  go at one time.  These may need different tool sets, even for the same 
Line 35: Line 36:
 The approach of limiting the tool sets is appropriate for development  The approach of limiting the tool sets is appropriate for development 
 environments which concentrate on limited languages, the original model of  environments which concentrate on limited languages, the original model of 
-IDEs like Eclipse and Netbeans which heavily integrated the Java workflow.+IDEs like Eclipse and NetBeans which heavily integrated the Java workflow.
  
-However Geany supports a wide range of platforms and programming and  +However, Geany supports a wide range of platforms, programming, and  
-documentation languages so it is more appropriate that it takes the approach +documentation languages, so it is more appropriate that it takes the approach 
 of providing flexibility. of providing flexibility.
  
Line 47: Line 48:
 ===== Using the Build System, the Build Menu ===== ===== Using the Build System, the Build Menu =====
  
-Geany supports a wide range of user experience, from beginners to experts, +Geany supports a wide range of user experiences, from beginners to experts, and 
 from occasional users to continuous users.  So it is important that its  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  flexibility is presented to the user in a simple, intuitive manner.  This is 
 provided by the Build menu. provided by the Build menu.
  
-image of menu here+{{:howtos:images:build-menu.png?direct&300|Build Menu}}
  
 The menu is broken into sections that roughly follow the usual workflow for  The menu is broken into sections that roughly follow the usual workflow for 
 software/document development. software/document development.
  
-  - 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). +  - The top section generally provides menu items for working with the file you are currently working on, e.g. 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). 
-  - 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.+  - The second section generally provides menu items that do not depend on the specific file, usually they are for working on groups of files, e.g., running a builder program.
   - The third section helps with navigation to the places that the tools found errors in your source so you can correct them.   - The third section helps with navigation to the places that the tools found errors in your source so you can correct them.
   - 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.   - 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.
-  - The final section opens a dialog to assist in configuration (see Configuring the GUI below)+  - The final section opens a dialog to assist in configuration (see Configuring with the GUI below)
  
 This structure has been used by Geany for some time and has proven easy to use  This structure has been used by Geany for some time and has proven easy to use 
Line 72: Line 73:
 allow clicking on the message in the compile window to cause the editor to go  allow clicking on the message in the compile window to cause the editor to go 
 to that file and line. to that file and line.
 +
 +For increased flexibility the second item in the filetype independent section pops up a dialog and any text entered will be appended to the command that the menu item runs.  Previous text entered in the current session is available on the combo-box list.  This allows the same command to be run with differing parameters without having to configure each option separately.
  
 ===== Implementation, how flexibility is achieved ===== ===== Implementation, how flexibility is achieved =====
Line 79: Line 82:
 to the menu. to the menu.
  
-This is achieved using a technique that is common in software, ordering the +This is achieved using a technique that is common in software systems, ordering the 
 sources of information from most general to most specific and having more  sources of information from most general to most specific and having more 
-specific settings override less specific ones.  Examples of its use that you  +specific settings override less specific ones.  Examples of this approach that you  
-may be familiar with include object oriented languages where functions  +may be familiar with include, object oriented languages where functions  
-redefined on derived (ie more specific) types override the same function of +redefined on derived (i.e. more specific) types override the same function of 
 the (more general) base type, or cascading style sheets for HTML where more  the (more general) base type, or cascading style sheets for HTML where more 
-specifc and later settings override less specific/earlier one.+specific and later settings override a less specific/earlier one.
  
 This overriding occurs independently for each position in the build menu, so  This overriding occurs independently for each position in the build menu, so 
Line 95: Line 98:
  
   - default settings coded in Geany   - default settings coded in Geany
-  - settings in system the installed filetype file for the type of file selected in the editor+  - settings in the system, that is the installed filetype file for the type of file selected in the editor
   - settings from the user preferences file   - settings from the user preferences file
-  - settings from the user configured filetype file for the type of file selected in the editor+  - settings from a user configured filetype file for the type of file selected in the editor
   - settings independent of filetype from the open project file   - settings independent of filetype from the open project file
   - settings for a specific filetype for the type of file selected in the editor which come from the open project file    - settings for a specific filetype for the type of file selected in the editor which come from the open project file 
  
-Remember the setting from the source lowest in the list "wins", ie that is +Remember the setting from the source lowest in the list "wins", i.e. that is 
 what is used in the particular menu item, and each menu item is determined  what is used in the particular menu item, and each menu item is determined 
 individually.   individually.  
Line 116: Line 119:
 This simple paradigm handles most of the use cases outlined in the introduction. This simple paradigm handles most of the use cases outlined in the introduction.
  
-===== Configuring with the GUI, the easy way =====+===== Configuring with the User Interface, the easy way =====
  
 Geany provides GUI configuration dialogs for some of the build system  Geany provides GUI configuration dialogs for some of the build system 
Line 129: Line 132:
  
   - one for editing user preference settings, activated by the "Set Build Commands" menu item, and   - one for editing user preference settings, activated by the "Set Build Commands" menu item, and
-  - one for editing project preferences settings, it is a tab in the ''Project->Properties'' dialog and is only available when a project is open.+  - one for editing project preferences settings, it is the build tab in the ''Project->Properties'' dialog and is only available when a project is open.
  
 Both dialogs are arranged the same: Both dialogs are arranged the same:
  
-image of dialog here+{{:howtos:images:set-build-commands.png?direct&500|Set Build Commands Dialog}}
  
-The dialog shows the three configurable sections of the build menu and the +{{:howtos:images:project-properties.png?direct&500|Project properties Dialog Build Tab}} 
 + 
 +This dialogs show 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. items in them in the same order as they are shown on the finished menu.
  
 The dialog shows only the configurable sections of the build menu, section  The dialog shows only the configurable sections of the build menu, section 
 three (the navigate error items) and section five (the set build commands)  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.+cannot be configured and are not shown to avoid the dialog becoming too big.
  
-Like the menu the dialog shows the commands for menu items in section one that +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. relate to the filetype of the file currently selected in the editor.
  
Line 148: Line 153:
 is closed. is closed.
  
-The three columns show:+The three columns in the dialog show:
  
   - the label to be shown on the menu,   - the label to be shown on the menu,
Line 183: Line 188:
   * **%p** - replaced by the absolute path of the base directory of the currently open project.   * **%p** - replaced by the absolute path of the base directory of the currently open project.
  
-More than one substitution can be made so for instance **%d\%e.exe** could be +More than one substitution can be made so for instance **%d\%e.exe** would be 
 used for the absolute filename of an executable on a windows system. used for the absolute filename of an executable on a windows system.
  
Line 189: Line 194:
 will default to the same directory as **%d**. will default to the same directory as **%d**.
  
-Since the commands run by the first two menu sections have the output parsed  +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  +for error messages and when found the relevant lines in the file(s) are marked with red wavy underlines and the line in the Compiler output window is shown red to indicate that it has been recognised as an error.  Clicking on the red error line will take you to that line in the file in the editing window (opening the file if it isn't already open).  
-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 +Each of the first two sections has a regular expression that can  
 +customise the parse.  This is a Perl-compatible regular expression (PCRE) where  
 +the first two match groups provide the filename (either absolute or relative) and the line number.  These 
 can occur in any order, a match group containing only digits is taken as the  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 +line number and the other is taken as the filename.  If no regular 
 expression is specified for a menu section then a hard coded default parser  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  that matches many of the common error message formats will be used for the 
 menu items in that section. menu items in that section.
  
-Changes are not saved until you click ok.+Changes to these dialogs are not saved until you click OK.
  
-Remember that these comamnds can be set in the project preferences where they +Remember that these commands can be set in the project preferences where they 
 will be applicable only when the project is open.  These settings will  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  override settings in the user preferences dialog.  If this is the case the 
Line 211: Line 218:
  
 When there is a setting that can be overridden by editing it in this dialog  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 +(e.g. 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  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  settings being overridden are copied to the dialog and so will become normal 
Line 222: Line 229:
 the manual now. the manual now.
  
-As the implementation section above explained there are six sources of build +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  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  not edit the system filetype files.  These are overwritten each time you 
 upgrade Geany and you will lose your customisations. upgrade Geany and you will lose your customisations.
  
-Also the project filetype dependent settings and prject filetype independent +Also the project filetype dependent settings and project filetype independent 
 settings are both stored in the project configuration (the .geany) file, so  settings are both stored in the project configuration (the .geany) file, so 
 in fact there are only three places to edit: in fact there are only three places to edit:
Line 235: Line 242:
   - the project file **project_name**.geany which can be stored in the project tree or outside it as you chose.   - the project file **project_name**.geany which can be stored in the project tree or outside it as you chose.
  
-Within these files only the contents of the [build_menu] section will be +Within these files only the contents of the [build-menu] section will be 
 discussed, but first a mention of the [build_settings] section.   discussed, but first a mention of the [build_settings] section.  
  
Line 241: Line 248:
  
 The [build_settings] section is the section where build settings were  The [build_settings] section is the section where build settings were 
-stored pre-Geany 0.19.  So that the system filetypes files didn't have to +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  all be updated at once and to remain backward compatible with older user 
 configurations, the settings in the [build_settings] section are loaded  configurations, the settings in the [build_settings] section are loaded 
 it the menu item they are defining is not already defined by a  it the menu item they are defining is not already defined by a 
-[build_menu] section entry in the same file. This has worked so well +[build-menu] section entry in the same file. This has worked so well 
 that at the time of writing almost no system filetypes files have been  that at the time of writing almost no system filetypes files have been 
 converted. converted.
  
 Geany 0.19 and later will only write changes made in the build GUI to the  Geany 0.19 and later will only write changes made in the build GUI to the 
-[build_menu] section and will not touch the [build_settings] section.  +[build-menu] section and will not touch the [build_settings] section.  
 Because of the restricted changes that can be made in the GUI this should  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  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. hand editing you probably should not have both sections in the same file.
  
-==== [build_menu] ====+==== [build-menu] ====
  
 As noted before, filetype dependent settings are only considered if the file  As noted before, filetype dependent settings are only considered if the file 
Line 267: Line 276:
 dependent items, filetype independent items and execute items. dependent items, filetype independent items and execute items.
  
-Unlike editing with the GUI, when configuring by hand, despite the names,  +Unlike editing with the GUI, when configuring by hand, this division is purely convention, despite the names there is no restriction on which section 
-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  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  configure menu items in the filetype independent section of the menu and 
Line 277: Line 285:
 Consider a Ruby programmer, it might be appropriate to configure the Ruby  Consider a Ruby programmer, it might be appropriate to configure the Ruby 
 filetype to replace the Make commands in the filetype independent section of  filetype to replace the Make commands in the filetype independent section of 
-the Build menu with Rake commands, while still having Make available for +the Build menu with Rake commands, while still leaving Make available for 
 other languages. other languages.
  
Line 295: Line 303:
 users, so don't do it. users, so don't do it.
  
-Entries in the [build_menu] section of configuration files all have the +Entries in the [build-menu] section of configuration files all have the 
 same format: same format:
  
Line 327: Line 335:
  
 To allow entries for multiple filetypes to be stored in the one project  To allow entries for multiple filetypes to be stored in the one project 
-file, the entries can be prefixed by the filetype name, eg+file, the entries are prefixed by the filetype name, e.g.
  
   CFT_01_LB = Compile   CFT_01_LB = Compile
Line 343: Line 351:
  
 There is no reason that you cannot have multiple project files for the one  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.  +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 +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  friends to compile the project and "secret-project-x-windows.geany" that 
 contained the commands to compile with the windows tools.  contained the commands to compile with the windows tools. 
  
-Since you can only get one set of commands or the other instead of them side +Since you can only get one set of commands or the other depending on which project file you opened instead of having two sets of commands side 
 by side in the same menu there is no chance of hitting the wrong one. by side in the same menu there is no chance of hitting the wrong one.
  
Line 362: Line 370:
 used a project. used a project.
  
-The following image shows the project configuration dialog with some likely  +When doing this remember that the second filetype independent command pops up a dialog and appends text the user enters to the command.
-option sets.+
  
-include image here+</WRAP>
  
 {{tag>howto configure build 0.19 0.20}} {{tag>howto configure build 0.19 0.20}}
  

Trace:

Print/export