GAMBAS BOOK 3.19.5

Paths in Gambas refer to:

• Regular files (regular file),
• directories,
• symbolic links,
• block-oriented devices (block device),
• character-oriented devices (char device),
• data links between processes according to the FIFO principle (named pipe) and
• communication endpoints (unix-socket).

You should always choose the file path specifications in such a way that a project P can always be executed without problems in the following three cases:

• (F1) The application P.gambas is executed in the IDE with F5 or via the menu bar (►).
• (F2) The application is started outside the IDE directly in the project directory or with `gbr3 path2projectP/P.gambas` or with `gbx3 path2projectP_directory` as a command in a console.
• (F3) The application is executed outside the IDE in any directory directly or with `gbr3 ./P.gambas`.

There are two types of paths in Gambas:

• absolute paths and
• relative paths.

Absolute paths begin with the characters / or ~. They are interpreted as in a shell. If a path begins with the tilde character ~ - followed by the character / - then the character ~ is replaced by the home directory of the current user.

Table 6.1.1.1 : Paths in Gambas

Never use absolute paths pointing to your project directory in your projects, as these paths will no longer exist when you create an executable *.gambas file! You must use relative paths instead.

Relative paths are paths that do not begin with the / or ~ character. They refer to files or directories located within the current project executable or component. Relative paths do not refer to files in the current working directory, as there is no concept of the current working directory in Gambas! You can use the static method File.IsRelative(sPath As String) to check whether the path sPath passed in the parameter is a relative path or not.

Following the Gambas documentation, the following applies: Files that are inside the project directory or in subfolders of it and are archived in an executable file *.gambas are readable - but write-protected. If you run your project in the IDE, project files could be modified using absolute paths. But don't do that! Once your project is run as an executable, these absolute paths no longer exist.

In response to a question on the Gambas mailing list about using relative paths, B. Minisini thus:

The current syntax of relative paths is: '../<path>' =⇒ access to a file located in the calling component, i.e. the component of the first method in the stack backtrace that is not in the same component than the current one ; the top-level component being the current project. '…/<path>' =⇒ access to a file located in the current project. ' /<component>/<path>' =⇒ access to a file located in the specified component, provided that, of course, the component has been loaded. Otherwise, './<path>' or just '<relative path>' =⇒ access to a file located in the current component. I hope it's more clear now. The './<component>/<path>' syntax may change before the 3.12 release. Maybe for something like '.[<component>]/<path>', or '..<component>/<path>', or something else.

These above statements about the syntax of relative paths have been tested in many projects. The results are summarised in the following sections and the examples presented as exemplarily.

It is assumed that in a (main) project P both a component C and a library L are included. Component C has the file c.ext in its project directory and library L has the file l.ext in its project directory:

            File p.ext
               |
            Project P
Component C            Library L
     |                       |
  File c.ext             File l.ext

Example A
Access from P to files in the project directory:

Public Sub Form_Open()
 
  Dim sImagePath As String
 
  FMain.Icon = Picture.Load(".../symbols/form_icon.png") ' ◀———— Consistently this .../- use Syntax!
  sImagePath = ".../images/hgb.png"
  piboxImage.Picture = Picture.Load(sImagePath)
  ...
 
End

Example B
Access from C to the (hidden) file `.project` in the project directory:

' Gambas class file
 
''' The C component class implements only 2 properties.
''' The class is used only to demonstrate access from a component to files in the main program.
 
Export
 
Property Read Version As String
Property Read Vendor As String
'------------------------------
Private $sVersion As String
Private $sVendor As String
Private $sContent As String
Private $aContent As String[]
 
Public Sub _new()
 
  Dim sRow As String
 
  If Exist("../.project") Then
     $sContent = File.Load("../.project") ' ◀———— ../-Syntax
     $aContent = Split($sContent, gb.NewLine)
     For Each sRow In $aContent
       If sRow Begins "Version" Then $sVersion = Scan(sRow, "*=*")[1]
       If sRow Begins "Vendor" Then $sVendor = Scan(sRow, "*=*")[1]
     Next
  Endif
 
End
 
Private Function Vendor_Read() As String
  Return $sVendor
End
 
Private Function Version_Read() As String
  Return $sVersion
End

Example C
Access from L to the file p.ext in P:

sContent = File.Load("../p.ext") ' ◀———— ../-Syntax

Example D - Access from P to the file c.ext in C
Example E - access from P to the file l.ext in L

For the last two cases, you should declare a private function in each of C and L in a module that provides the contents of c.ext and l.ext in a read-only property. A module is well suited in this case because you only need one instance of the static class.

In the following concrete example, the content of the help file help_mqt.txt in component C is provided in the module MHelp.module as a read-only property Help:

' Gambas module file
 
''' The MHelp module implements only one property: Help
 
Export
 
Property Read Help As String
 
Private Function Help_Read() As String
 
  If Exist("./help_mqt.txt") Then
     Return File.Load("./help_mqt.txt") ' ◀———— ./-Syntax
  Else
     Error.Raise("Help file not found!")
  Endif
 
End

In the download area you will find the two source code archives for component C and the main programme P.

Many control elements have the .Picture property, to which you can assign a suitable icon from Gambas' inventory, for example, with btnClose.Picture = Picture[“icon:/16/close”]. The pictures from the stock of Gambas (in /usr/lib) are in the file gb.form.stock.gambas. They are only available in this archive! If the Picture class recognises a path in gambas-specific format with “icon:/” at the beginning, then it searches in the compiled files and loads the picture from the archive using the Gambas interpreter's path resolution for relative paths.

You can use the following alternative assignments to use your own images - stored for example in the image directory `leds` in the project directory:

pboxOnOff.Picture = Picture.Load(".../leds/green16.png")
pboxOnOff.Picture = Picture["leds/green16.png"]

pboxOnOff.Picture = Picture[.../leds/green16.png"]

If you need suitable icons (coloured/grey) from the Gambas stock for your projects, you will find them in the source code of Gambas in the directory ../comp/src/gb.form.stock/gambas/32. You can then save these, for example, in a sub-folder /icons of the project directory.

If you load a Gambas library at runtime, then you can do this with Component.Load(“:gambasbook/mylibrary:2.1”), for example. The path specification in gambas-specific format starts with a colon, followed by the vendor name 'gambasbook', the character “/” and the name of the library 'mylibrary'. Another colon is followed by the version '2.1'. The interpreter looks for Gambas libraries in these paths: ~/.local/share/gambas3/lib/ or in /usr/lib/gambas3/.

If you include an external library in Gambas, then the path follows the syntax “NameOfExternalLibrary:VersionOfExternalLibrary” as used in the following two examples:

LIBRARY "libc:6"
EXTERN getgid() AS Integer

EXTERN getgid() AS Integer IN "libc:6"

To load a Gambas component, it is sufficient to specify the name of the component as the specific path:

Public Sub _new()
  Component.Load("gb.desktop")
' Print Component.IsLoaded("gb.desktop")
End

If you use a file or directory selection dialogue, then you should check carefully whether the full path or only the name is available as a result. For example, the IsDir(…) function always checks the full path.

For a file name in Gambas, all characters except the slash “/” and the null character (NUL or U+2400) are allowed.

On a data carrier, there is a Gambas project in a directory with a Gambas-specific directory structure. The project directory and its basic structure are created *automatically* when a project is created in the integrated development environment (IDE). The directory name of the generated project is the project name! If you open a project directory via your file browser and switch on the display of hidden files/directories, you will see not only some hidden files but also hidden directories that Gambas uses for control files as well as files and directories that you yourself have copied into the project directory or created there. Especially beginners are surprised how much the directory structure differs from the display in the browser of the IDE when you open a project in the IDE. To describe the difference, the following applies: A directory is called “physical” if it is on a data carrier and you can view it with the file browser. A directory, on the other hand, is of the type “logical” if the Gambas IDE attaches special importance to a particular physical directory. In the file browser you only see physical directories, in the Gambas IDE mainly logical ones (project (.hidden), sources (.src) and data). The logical directory “project” in the IDE corresponds to the physical directory .hidden. Files and directories that you have copied to or created in the physical project directory can be seen in the IDE in the logical directory “data”. Only directories and files from the “data” directory are included in the executable file *.gambas when compiling. However, there are also files - such as files of type *.class - that you do not see in the logical directory .src! However, you can open these files with F12 or via the corresponding button in the editor of the IDE. A detailed description can be found in chapter 2.6.0.7 Directory paths.

Note: Only files that you store in the hidden directory .hidden are displayed in the IDE in the directory “Project” and only files from this directory can be copied to a directory of your choice on the target computer when you create an installation package in the IDE. For a description, see https://www.gambas-buch.de/doku.php?id=k11:k11.10:start.

When you create an executable file in the IDE, the archive file *.gambas is automatically saved in the project directory. The file name of the archive is the same as the project name you entered in the dialogue when creating a new project. However, you can also freely select the name of the file and the storage location in the dialogue in the IDE.

Alternatively, you can also create the archive file in two steps:

hans@mint-183 ~ $ gbc3 -ag $HOME/GB3BUCH/6K_Stream/6.1_Pfade/BuchProgramm/PathProject
OK
hans@mint-183 ~ $ gba3 $HOME/GB3BUCH/6K_Stream/6.1_Pfade/BuchProgramm/PathProject

It is recommended not to rename the archive file later, because this can lead to unexpected page effects if you use the Application.Name property as an implementation detail.

If you create an executable file library_name.gambas from a project of type 'library', then the IDE will ensure that the library is automatically saved in the project directory and additionally also in the library base directory with the path

~/.local/share/gambas3/lib/<vendorname>/<projektname:version1.version2.gambas>.

The library such as ~/.local/share/gambas3/lib/gambasbook/libmath:2.3.gambas and its exported(!) classes and methods can thus be used in other projects.

If your project uses a self-developed Gambas library, the Gambas interpreter knows the paths to the library base directories in which to search. You have to explicitly add and confirm the appropriate library in each case in the project properties under 'Libraries'! This user-based path is actually quite practical, as you as a developer and/or tester can always use the latest version of the library. This means that you can use your test version without having to overwrite a possibly existing system-wide stable version. If you are using an external Gambas library, then the path should be either:

(case 1) ~/.local/share/gambas3/lib/$vendor or with.
(case 2) /usr/lib/gambas3/$vendor

start with.

The first case is when you install a library library_name.gambas as a simple user or you install a library from the Gambas farm.The second is when you install the library as root. In this case, the path applies system-wide. Note: If the project type was set to 'Library' in the project properties, the vendor name is mandatory. You should assign a suitable developer name (vendor name) to the value of Vendor in the project properties. If you do not enter a developer name there, Gambas automatically inserts '(unknown)' as the value for Vendor. This is a problematic procedure if you want to use the path to a library in a console, for example, because this error message appears: -bash: Syntax error on unexpected word '(' !