
Installation instructions HWGUI for MacOS / GTK2
------------------------------------------------
install-macos.txt

$Id: install-macos.txt 3743 2025-05-07 00:09:49Z josequintas $

By DF7BE

History:
(Date format is YYYY-MM-DD)

2025-03-15   DF7BE   Install "wmctrl" needed for progress bars
2024-08-18   DF7BE   First creation

Contents:

1. Preface
2. Installation steps
3. Hints for programmers
4. Some helpful internet links

1. Preface
----------

MacOS by Apple is not official supported by the Harbour project,
but the "xcode" development environment allows
to run Harbour and HWGUI applications on MacOS.
An extra set of make scripts are added to HWGUI,
but a selection macro for this OS is "{darwin}",
it can  be set in *.hbp files for hbmk2 utility,
details in the following chapters.

Some little modification in the HWGUI source code is done.

The MacOS kernel is derived from Darwin, so LINUX scripts
and commands are running also here.


2. Installation steps
---------------------

Installation instructions, tested under
MacOS Sonoma 14.5
Dual-Core Intel i3, 1.1GHz

at 2024-08-18 (YYYY-MM-DD).

For editing text files you need a suitable text editor,
the "TextEdit" coming with the system is only for some formats
(Rich-Text, HTML, ...)
For more info see chapter "2. Hints for programmers".

    1.) Launch terminal:
        must be found in Applications/Utilities,
        search for "Terminal":
        Finder, menu item "Go" (Gehe zu) and
        "Utilities" (Dienstprogramme),
        key "command" + "U"
        Start the Terminal and
        fix the Terminal at the dock, if running.
        (german: "Im Dock behalten")


    2.) Install the "xcode" development environment:
        xcode-select --install
        When extra window appeared, press the "Install" button
        in this extra window.
        Check the compiler by entering:
        gcc --version


    3.) Install Harbour from Source:
        - Download the newest code snapshot as ZIP
        - Extract the Harbour archive,
          most done automatically.
        - become root user by
          sudo su
          ==> Enter your password.
        - cd into base directory of Harbour
        - export HB_INSTALL_PREFIX=/usr/local
        - make install
        - leave root modus with "exit"
        - check:
          hbmk2 --version

       Path info:
       - All binaries are reachable by system PATH (/usr/local/bin)
       - Library path: /usr/local/lib/harbour
       - Include path: /usr/local/include/harbour


    4.) Install macports:


       Download package file for your OS, for example:
       MacPorts-2.9.3-14-Sonoma.pkg

      - become root with
        sudo su
      - installer -target / -pkg MacPorts-2.9.3-14-Sonoma.pkg
      - leave root by "exit"



    5.) Install GTK2

       - sudo /opt/local/bin/port install gtk2

         Answer question "Continue? [Y/n]:" with "y"
         (after display of all dependency packages to be installed)


    6.) Install pkgconfig

        - sudo /opt/local/bin/port install pkgconfig

        - Test flag display for GTK2:
         /opt/local/bin/pkg-config --cflags gtk+-2.0


    7.) Install XQuartz

        GTK2 supports only X11, so you need to install and
        start an X11 server:
        Download XQuartz from [6]
        for example XQuartz-2.8.5.pkg
        install by typing:
        sudo installer -target / -pkg XQuartz-2.8.5.pkg

        There must be started a background process.
        Test:
        start "xeyes" or "xclock" in the terminal.
        Be shure, that the X icon is visible in the dock
        (after every login). A running process is marked
        with little point under the icon.
        Adding a "&" after the program call command,
        the program starts in background and you can enter
        more commands.

    8.) Install "wmctrl" (Needed for PROGRESSBAR)

      Direct support for progressbar is WinAPI only.
      For LINUX and MacOS an external tool "wmctrl" is needed to
      draw progress bars, while program is busy running FOR ... NEXT or
      DO WHILE ... ENDDO loops.
      A multi platform sample program see directory
      samples/progressbar
      (TNX to Alain Aupaix).

      Command for installing "wmctrl" is:
          sudo port install wmctrl
      (installed from mac ports)


    9.) Compile HWGUI

        Installation destination is
        /Users/<userid>/hwgui/hwgui
        (at your home directory)

        - Create directory:
          mkdir hwgui
          and extract archive here.
        - rename hwgui-code-rnnnn... only to "hwgui"
        - set execute permission by
          chmod 755 make_macgtk2.sh
        - Start compilation by calling
          ./make_macgtk2.sh


    10.) Compile a sample program

        goto directory "samples"
        and start compiling of demobrowsearr.prg
        hbmk2 demobrowsearr.prg
        Ignore warning:
        ld: warning: ignoring duplicate libraries: '-lhbrdd', '-lhbrtl', '-lhbvm'

        Start sample programm:
        ./demobrowsearr


    11.) Compile your own application

        Use the file hbmk.hbm as a template to your file.hbp
        to create a hbp file for building your own application.
        Because the HPB macro "{mac}" does not exist,
        use following macros to divide to your used operating system:
        - {!win} ==> for LINUX and MacOS
        - {darwin}  ==> only MacOS
        - {win} ==> Windows only

        To divide code for MacOS for Harbour and HWGUI we suggest to use the following
        define for all .prg files:
        ___MACOSX___
        Add the following line in your *.hbp file:
        {darwin}-d___MACOSX___
        So say in your .prg:
        #ifdef ___MACOSX___

       Get more samples for programming your own HWGUI application
       in the subdirectory "samples" and at
       [3] Project "CLLOG".

       If you also use Harbour Console/Terminal programs,
       solve a problem on MacOS:
       Regularly the command
       hbmk2 helloworld.prg
       compiles the program on Windows and LINUX and it runs at its best.
       Doing this on MacOS, the program is compiled
       successful, but runnung it with
         ./helloworld       the start is faulted with the following error message:
        dyld[1767]: Library not loaded: libharbour.dylib
        Referenced from: <F7B1FE28-9F46-3B03-BBF2-CCB7EC56B210> /Users/afumacbook/svnwork/
         hwgui/hwgui-code/hwgui/samples/helloworld
         Reason: tried: 'libharbour.dylib' (no such file),
         '/System/Volumes/Preboot/Cryptexes/OSlibharbour.dylib' (no such file),
         'libharbour.dylib' (no such file),
         '/Users/afumacbook/svnwork/hwgui/hwgui-code/hwgui/samples/libharbour.dylib' (no such file),
         '/System/Volumes/Preboot/Cryptexes/OS/Users/afumacbook/svnwork/hwgui/hwgui-code/hwgui/samples/libharbour.dylib' (no such file),
         '/Users/afumacbook/svnwork/hwgui/hwgui-code/hwgui/samples/libharbour.dylib' (no such file)
          zsh: abort      ./helloworld
     Now compile this sample by
             ./hbmk.sh helloworld
      and it runs now.
      The script can also be used on LINUX, it
      has an OS autodetect function.

   12.) How to create desktop shortcuts for files and folders

        The term "desktop shortcut" is a more familiar term to Windows users,
        it is understand like an "alias" and is represented by a
        tiny file with the same icon as the parent file it links to.
        The parent file may be a program (EXE), a file or a folder.

        In brackets, you find the equivalent item name on systems with
        german language setting.

        Select the "Finder" icon which is the leftmost icon on the dock.

        Use the "Finder" to locate the folder,
        file, or application you'd like to create a
        shortcut for on the left side of the window.

        Select the program, file or folder to highlight it, by single mouse click.

        Go to the main menu bar, "Select File" (Ablage) ==> "Make Alias" (Alias erzeugen).

        Right-click on the file and select "Make Alias" (Alias erzeugen) from the menu.
        Right-Click on Folder to make alias.
        Der created alias for a file or program is named "<name> alias"
        and is located in this directory.

        Press keys Option + Command together as you drag the
        original item to another folder or the desktop (Schreibtisch)
        as a copy.
        Release the shortcut first and then the Option + Command keys
        to place the shortcut in the new location.
        Delete (in den Papierkorb legen) the original alias in the directory created.

        Select the shortcut with the "alias" suffix.
        Press Enter to rename it by removing the "alias" suffix,
        so the alias has the name of the file, program or directory.

        Drag the alias file to the desktop if it's in any other location.
        You can also copy and paste this to any location.

        Every shortcut has a small arrow on the bottom left corner as a marker,
        that is not a program, a normal file or directory.
        Be care of this fact, to verify not to delete or move the
        orignal !

        Shortcuts continue to work even if you change the location
        of the original file or folder. To view the location,
        right-click on the shortcut and select Show Original (Original zeigen).
        The Finder opens a new windows with the location of the original.

        The HWGUI programs using GTK2, they needs the X11-Server XQuartz
        for run. Also the icon of your program in not displayed.
        Start the program by double click on to the shortcut,
        but an intermediate terminal started in the background,
        before the HWGUI application is running.
        After termination of the HWGUI program,
        you must close the terminal manually.


1.2 GTK 3

 The port to GTK3 is not completed, there is some
 work to do.
 The Bugs appeared on LINUX and MacOS, so
 be patient.
 If you found a solution, please create a ticket
 on sourceforge.net and send us the modified code.
 (TNX).

 Please install all packages described in chapter above.

 - Install additional GTK3 by:

            sudo /opt/local/bin/port install gtk3

  - Recompile HWGUI:
     ./clean.sh
     ./make_macgtk3.sh

  - Check for GTK2 and GTK3:
        /opt/local/bin/pkg-config --cflags gtk+-2.0
        /opt/local/bin/pkg-config --cflags gtk+-3.0

   - Modify the *.hbp file of the sample program
    or your own application and compile it.

In "include/gtk.h" there a  lot of duplicate defined
items, so lots of warnings appeared.
Do not include it in your prg file,
this is already done.



2. Hints for programmers
------------------------

- Looking for a good editor to edit program code:
   Ask your preferred search engine entering:
   "macos good text editor for programmers"
   and you will get a lot of suggestions.
   I prefer "CotEditor", it is like "Notepad++"
   on Windows [4] and Open Source.
   But for Clipper/Harbour there is no syntax file
   available [5].

- Expand PATH
  Many of the new products are installed in another path.
  You can extend the path of the system as follows:
  - sudo bash
    vim /etc/paths
  - Insert line at the end:
    /opt/local/bin
    To do this, turn on the append mode with "A",
    and press <ENTER> for a new line.
    After entering the new line
    exit insert mode with the <ESC> key
    and save by
    wq!
  - Exit "root" mode with
    exit
  - Restart the computer for the change to take effect.

- Installing the Subversion command line client
   sudo /opt/local/bin/port install subversion
   Actions analogous to "7.) Install XQuartz",
   but afterwards the "dbus-daemon" can
   be deactivated, because it is not needed.
   Do this in "System settings" (Systemeinstellungen),
   "Common" (Allgemein), "Login items" (Anmeldeobjekte)
   Set 3 switches to "off".
   Check with
   svn --version
    whether the client starts.


- malloc.h is deprecated.
  Now stdlib.h must be used instead
  (is not more part of ISO C99 standard).

  Inserted in
   ==> source\gtk\inter.c
   ==> source\gtk\misc.c

  It depends of the Version of GCC,
  so set compiler switch -d__NOMALLOCH__,
  if needed.

  #ifdef __NOMALLOCH__
  #include <stdlib.h>
  #else
  #include <malloc.h>
  #endif

- This compiler define for C selects automatically code for MacOS
  #ifdef __APPLE__

- MacOS has no file like windows.h, so
  windows_mac.h must be included instead.

  #ifdef __APPLE__
  #include "windows_mac.h"
  #else
  #include <windows.h>
  #endif

  also for io.h:
  #ifdef __APPLE__
          #include <sys/uio.h>
          #include <unistd.h>
  #else
          #include <io.h>
  #endif

- Detection of operating system:
  the command uname and the Harbour function
  OS() returns on MacOS the value
    "Darwin".



3. Some helpful internet links
------------------------------

[1] "C auf dem Mac programmieren" (german, C programming on Mac):
    https://www.macuser.de/threads/c-auf-dem-mac-programmieren.868779/
    (18. July 2024)

[2] "How to Install Command Line Tools in Mac OS X (Without Xcode)":
    https://osxdaily.com/2014/02/12/install-command-line-tools-mac-os-x/
    (18. July 2024)

[3] Project "CLLOG" based on Harbour and HWGUI for MS-DOS, Windows and LINUX
    and now MacOS:
    https://sourceforge.net/projects/cllog/

[4] CotEditor on GitHub:
    https://github.com/coteditor/
    (20. July 2024)

[5] Additional Syntax Styles for CotEditor
    https://github.com/coteditor/CotEditor/wiki/Additional-Syntax-Styles
    (18. July 2024)

[6] Download X11 server "XQuatz" for MacOS
    https://www.xquartz.org/
    (20. July 2024)

[7] Download site for the MacPort packages
    https://guide.macports.org/chunked/installing.macports.html
    (18. July 2024)

=============== EOF of install-macos.txt ===================
