PureBASIC v5.61

A close look at the different ways the PureBASIC IDE can save source file configurations.

Table of Contents

• IDE Settings
  • Retriving The IDE Settings
    • Code Example
• The Three Cfg-Modes
  • Source-Cfg Mode
  • File-Cfg Mode
  • Folder-Cfg Mode
• External Links

In "Preferences » Editor » Save Settings to:" you can specify where the IDE should save and load the compiler options of a source file.

There are four options available, with three different ways to handle how compiler options are saved/loaded:

• The end of the Source file — settings are saved as a comments block at the end of each source file.
• The file <filename>.pb.cfg — for each source file, a corresponding <filename>.pb.cfg file is created. The file is a PureBASIC preference file.
• A common file project.cfg for every directory — a single project.cfg preference file is created within a folder, the settings of each source file are grouped in a Preference Group named as the source file.
• Don't save anything

For the sake of brevity, in these pages we'll refer to them as "cfg-modes" (configuration modes):

• source-cfg mode
• file-cfg mode
• folder-cfg mode

The cgf-mode settings are saved in the PureBASIC IDE preferences file ("PureBasic.prefs"), under the "SaveSettingsMode" key ("[Global]" group/section):

;  PureBasic IDE Preference File
; 
; 
[Global]
SaveSettingsMode = 2

The possible values for the "SaveSettingsMode" key are in the range 0-2, mirroring the order of the dropdown's options:

The user configuration for "Editor » Save Settings to:" can be easily retrived using the [Prefernce] library. From within a tool invoked from the IDE, the full path to the PureBASIC preferences file (on the user's machine) can be accessed by reading the environment variable PB_TOOL_Preferences.

Here is an example on how an external tool can retrive the settings (must be compiled to binary and launched as an external tool from the IDE, otherwise the PB_TOOL_Preferences env var won't be available):

; PureBASIC 5.61 | by Tristano Ajmone | Public Domain
; ==============================================================================
;                  Read IDE Preferences for "SaveSettingsMode"                  
; ==============================================================================
; Example: get the user's PB IDE settings for "Editor -> Save Settings to:" from
; a custom external tool (must be launched from the IDE as tool).

Enumeration
  ; Possible values for "SaveSettingsMode" key in "PureBasic.prefs":
  #CFG_SOURCE ; = 0 | The end of the Source file 
  #CFG_FILE   ; = 1 | The file "<filename>.pb.cfg"
  #CFG_FOLDER ; = 2 | A common file "project.cfg" for every directory
  #CFG_NONE   ; = 3 | Don't save anything
EndEnumeration
#CFG_NOT_FOUND = -1 ; In case the Key is not found (shouldn't happen)

; PB_TOOL_Preferences (env var): Full path and filename of the IDE's Preference file
If OpenPreferences(GetEnvironmentVariable("PB_TOOL_Preferences"))
  PreferenceGroup("Global")
  Select ReadPreferenceInteger("SaveSettingsMode", #CFG_NOT_FOUND)
    Case #CFG_NOT_FOUND
      MessageRequester("WARNING", "Setting not found.")
      End
    Case #CFG_SOURCE
      Result$ = "The end of the Source file"
    Case #CFG_FILE
      Result$ = "The file <filename>.pb.cfg"
    Case #CFG_FOLDER
      Result$ = "A common file project.cfg For every directory"
    Case #CFG_NONE
      Result$ = "Don't save anything"
  EndSelect
  ClosePreferences()
Else
  MessageRequester("ERROR!", "Unable to open the PB IDE preferences file.",
                   #PB_MessageRequester_Error)
  End
EndIf
MessageRequester("RESULT", "The IDE is configured to save source settings to:" +
                           #CRLF$ + Result$)

All three cfg-modes use the same Key = Value approach, they just differ in the way they store them. For detailed references on how the settings shown in the IDE are mapped to file, see the dedicated Wiki page:

• Compiler Options Mapping

The file-cfg and folder-cfg modes create PureBASIC preference files, and they can be read using the Preference library. Prefrences files are like a Windows INI file.

The source-cfg mode stores the key-value pairs as commented lines within the source file. A custom approach is required to read preferences stored in this mode, as the Preference library can't read comments.

Settings saved in this mode are gathered in a single comments block at the end of the source file. The PureBASIC IDE hides them from view in the editor, so you'll need to open the source file with another plain text editor in order to view them.

A settings comments-block looks like this:

End ; <= Last line of code
; IDE Options = PureBasic 5.61 (Windows - x64)
; CursorPosition = 2
; EnableAsm
; EnableXP

TIP — A quick way to check if a source file contains settings at its end is to look for the IDE Options key, which is always present in any type of saved settings. This key-value pair indicates the PB IDE version used to edit the source file.

A "<filename>.pb.cfg" file is just a preference file, like those managed by the PureBASIC's Preference library. Since in this mode each configuration file is associated to a single source file, no Preference Groups are used.

For source files with extensions "*.pbi" and "*.pbf" (ie: include- and form-files) the corresponding configuration files will be "<filename>.pbi.cfg" and "<filename>.pbf.cfg", respectively.

The contents of a *.pb.cfg file looks like this:

IDE Options = PureBasic 5.61 (Windows - x64)
CursorPosition = 2
EnableAsm
EnableXP

The "project.cfg" is just a preference file, like the "<filename>.pb.cfg" of the file-cfg mode, except that it contains the settings of multiple source files. Each source file's settings are grouped in a Preference Group (aka section, in INI file terminology) named as the source file.

When parsing a "project.cfg" file, the PreferenceGroup(filename$) command allows to select the settings of the desired source file.

Here is an example of a "project.cfg" storing the configuration of two source files ("helloworld.pb" and "fibonacci example.pb"):

[helloworld.pb]
  IDE Options = PureBasic 5.61 (Windows - x64)
  CursorPosition = 2
  EnableXP
  EnableUser
  UseIcon = pb5.ico
[fibonacci example.pb]
  IDE Options = PureBasic 5.61 (Windows - x64)
  ExecutableFormat = Console
  CursorPosition = 1
  Compiler = PureBasic 5.61 (Windows - x86)

PureBASIC Documentation:

• Customizing the IDE
• Preference

Wikipedia:

• INI file