                      HWGUI - Harbour GUI library

Installation instructions
~~~~~~~~~~~~~~~~~~~~~~~~~

Contents:
=========

1.)   Windows
1.1)  Special instructions for MinGW64 (x86_64)
1.2)  Helpful tools for HWGUI developer
1.3)  Special instructions for Microsoft Visual C, Edition 2022
2.)   Linux
2.1)  Troubleshooting missing include file <sys/io.h>
2.2)  Build
3.)   Resources
4.)   Special build instructions
4.1)  For Borland C (BCC) on Windows
5. )  Additional instructions for Windows 11

Appendix 1: List of packages for Ubuntu Linux and LinuxMINT
Appendix 2: Additional instructions and information for other LINUX distributions.
Appendix 3: Information for port to GTK3


History:

2025-06-01   DF7BE  Raspberry Pi installation, troubleshooting missing include file sys/io.h
2025-02-07   DF7BE  Last undocumented state
 
 
   1.) Windows

   Installation procedure is very simple.

   There are few bat files to build HwGUI with C compiler of your choice:

   make_b32.bat   - Borland C
   make_pc.bat    - Pelles C
   make_vc.bat    - Microsoft Visual C
   make_w32.bat   - Open Watcom C
   makemngw.bat   - Mingw (32bit, special instructions follow above)
   makemngw64.bat - Mingw (64bit, special instructions follow above)

   Read special build instructions for every compiler in files of directory:
   samples\dev\compiler\<compiler>\...

   Attention !
   We recommend to build Harbour, HWGUI and your application with
   same C compiler, because generated C source by hbmk2 utility could be otherwise incompatible.
   
   Special instruction for Harbour compile with MinGW:
   In the latest versions of Harbour the compile
   of sqlite3 components must be omitted,
   if not installed on the system.
   Before make, set an environment variable to skip this
   step:
    set HB_WITH_SQLITE3=no 
   This should prevent sqlite from building.
   An then type
    make

   You need to set the environment variable HB_PATH, which must contain a path
   to your Harbour directory. This can be done in your Windows environment or
   by adding a line to appropriate bat file:

      SET HB_PATH=c:\harbour

   You find some sample bat files for setting environment variable
   in directory "samples\dev\env".
   
   Harbour install instruction are found in "README.md" in the
   Harbour main directory.

   Then run the selected bat file and you'll get hwgui.lib, hwguimt.lib ( hwgui.lib for
   multithread mode ),  procmisc.lib, hbxml.lib and hwgdebug.lib in lib/ directory.

   With Harbour you can also build libraries, using hbmk2 utility, just write:

      hbmk2 hwgui.hbp procmisc.hbp hbxml.hbp hwgdebug.hbp

   In contrib/ directory you'll find similar .bat and .hbp files for hwg_qhtm, hbactivex
   and hwg_extctrl libraries.

       To build samples you need to run appropriate .bat files, fixing environment
       variables there.
       Bld.bat should be executed with prg file name as a parameter:

       bld a


    Cross develop environment on Windows for GTK:
     (For target *NIX operating systems)

     For building an GTK version for test-
     and develop purposes you can create a
     GTK based version of HWGUI in parallel.
     Details in file
      samples\dev\MingW-GTK\Readme.txt
     Be care of the Warning mentioned in this file
     and dependent source files.


    For MacOS, special installation instructions in extra file
    "install-macos.txt". 


   1.1) Special instructions for MinGW64 (x86_64):

    You can install the 64bit version of MinGW in parallel with the 32 bit release.
    You must only use the special environment settings and compile scripts for
    decision of target 32 or 64 bit.

    - Install MinGW for 64bit in directory C:\MinGW64.
    - Extract Harbour in own directory "C:\harbour64\core-master"
    - Set adapted environment as witten in script (samples\dev\path\pfad64.bat)
      for all the next steps. Modify to your own needs.
    - Build Harbour in base directory by typing "make"
    - Build HWGUI :
       makemngw64.bat
      There are lots of warnings displayed, ingore them.
      We will fix them as soon as possiblle.
    - Build a sample program (a.prg or dbview.prg) with
      build script "bldmingw64.bat".
    - Use bldmingw64.bat as template for building your HWGUI application.

    Attention !
    Not all functions of the 32 bit build are available on MinGW64.
    For details read instructions in file "samples\dev\MinGW64\MinGW64.txt"


    1.2) Helpful tools for HWGUI developer
         (All open source for Windows)

        - 7Zip
           A useful archiver, supports ZIP and UNIX/LINUX formats tar and tar.gz and many more 
           https://www.7-zip.de/  
        - Notepad++
           A good editor for developers with syntax highlightning
           https://notepad-plus-plus.org/
           Supports UTF-8, Windows, UNIX/LINUX and MacOS line endings.
        - WinMerge
           A powerful diff an merge tool
           https://winmerge.org/
        - Greenfish icon editor
           http://greenfishsoftware.org/gfie.php  (also for LINUX) 

   
   1.3) Special instructions for Microsoft Visual C, Edition 2022
        (installed with setup program) 
   
        Harbour compile:
        My default installation location is:
        C:\harbour-msc\core-master
        (for extracting the Harbour archive)
        
        Open a command windows "cmd.exe" an change to 
        the directory above:
  
        Set the environment by:
        "C:\Program Files\Microsoft Visual Studio\2022\Community\VC\Auxiliary\Build\vcvarsall.bat" x86
        Output:
        [vcvarsall.bat] Environment initialized for: 'x86'
        Start build process by:
        win-make 
      
      

   1.4) Not supported windows compiler:
 
       At this time the Harbour build fails using the
       the compiler in this list, so no HWGUI can be build afterwards.
       Please be patient, if the compiler are supported
       by the Harbour community.

       - Open Whatcom Common
       - Pelles C
       - Digital Mars C   


   2.) Linux

   For installation on Linux you need some prerequisites,
   they are listed at the bottom of these instructions.
   
   2.1) Troubleshooting missing include file <sys/io.h>

   Before you start the build process of HWGUI,
   check the existance of include file,
   by following the instructions above.
   
   If you see the following error message
   building HWGUI or a HWGUI sample program:

    /usr/local/include/stdio.h:6:10: fatal error: sys/stdio.h: No such file or directory
          | #include <sys/stdio.h>
          |
            ^~~~~~~~~~~~~
  
   here a workaround is possible.
   The shell script "missingioh.sh"
   will do that for you.
   
   Reason:
   This include file is part of old versions of GLIBC and is now removed.
   Instead, the file <unistd.h> must be included.
   The file is requested by GTK2, otherwise the
   source code of GTK2 must be modified.
   
   It checks the existance of sys/io.h,
   if not, it copies the unistd.h as io.h
   into the HWGUI directory include/sys,
   so no modification of HWGUI build scripts
   are necessary.
   
   Before running the script, check if the
   substitute include file is available:
   ls /usr/include/unistd.h
     /usr/include/unistd.h
   If not, on some *NIX sytems the location may be
   /usr/local/include/unistd.h

   So modify the entry in the script 
   for setting the shell variable SYS_INCLUDEDIR=
   to your own needs.

   Start the script by typing
   ./missingioh.sh
   in the main directory of HWGUI.
   
   There is no problem to start the script again and again,
   the message is then:
   OK: Nothing to do !

   2.2)  Build

   Sources for the Linux GTK version are located in the source/gtk/ directory.
   In the base directory is a shell file make_gtk.sh, which is intended for building HwGUI Linux
   libraries. The environment variable HB_ROOT is set there, based on the 
   assumption, that HwGUI directory is within the Harbour directory. If no,
   you need to write the correct path to your Harbour directory, for example:

      export HB_ROOT=/home/me/harbour

   Then just run the script
     ./make_gtk.sh -hb
   and four libraries must appear in the lib/ directory:

      libhbxml.a
      libhwgui.a
      libhwgdebug.a
      libprocmisc.a

   For xHarbour platform set first parameter to "-xhb".

   You will find few samples in samples/gtk_samples directory and a shell file 
    ./build.sh <prg file>.
   The environment variable HB_ROOT is set there, based on the assumption, that
   HwGUI directory is within the Harbour directory. If no, you need to write the
   correct path to your Harbour directory.
   Some samples in the directory samples are ready for LINUX/GTK, look into the Readme.txt file.

   As alternative method use the hbmk2 utility, it works also at it's best.
   Start the script "./make_hbmk.sh" to run the HWGUI build with hbmk2.

   Build instructions for GTK3:
   See also "Appendix 3"
    chmod 755 make_gtk3.sh
    ./make_gtk3.sh

   Ignore the lot's of compiler warnings and notes.

   Then go to the sample directory and look into the file
   "Readme.txt"
   to get instructions for build sample programs and
   get template snippets to build your own HWGUI application.


   3) Common instructions to build samples, utils and your application
      (for all operating systems)

   For MacOS you find special installation instructions in file
   "install-macos.txt"   

   Easier way to build HWGUI applications is to use the "hbmk2" utility of Harbour.
   Write an *.hbp file and run for example:
   hbmk2 myapp.hbp

   You find samples of *.hbp files in the utils and samples directory.  

   Other way is to create list of all modules in the main program with "SET PROCDURE TO ..."
   (be care of case sensitivity on UNIX/LINUX)
   and write a bat or shell script with only one active line (for example on Windows): 
    hbmk2 <main.prg> <main.rc> -I%HWGUI_INSTALL%\include -L%HWGUI_INSTALL%\lib -lhwgui -lprocmisc -lhbxml -lhwgdebug -gui
   (-gui option only for windows necessary, for LINUX add options -d__LINUX__ -d__GTK__ , no *.rc files )

    All simple "all build":
    (for use with hbmk2 utility):

    cd samples
    hbmk2 allhbp.hbp  

   Builds on one call:
    - HWGUI basic libraries
    - Contrib libraries (directory "contrib")
    - Utilities (directory "utils")
    - Sample programs (directory "samples" and "samples/gtk_samples", depends on OS)


   3.) Resources
   Resources means forms, images and icons in GUI applications.
   They could be loaded directly from an single image or resource file (*.rc)
   and compiled directly into the exe file.
   If loading a lot of image files at run time, you must deliver them all with your
   setup script. This is uncomfortable. You can use the Windows resource
   compiler utility (HWGUI supports this), but for multi platform programs
   you must avoid the resource compiler. With MinGW the source compiler is "windres.exe".
   The resource compiler is not available on GTK/LINUX !
   But there are alternatives:
   1.) The Binary Container,
   2.) Hex value resources,
   3.) HWGUI designer for forms.
   Read more about this topic in file
   "utils/bincnt/Readme.txt".
   Creating and editing forms use the HWGUI utility "Designer"
   in directory "utils/designer".

   4.) Special build instructions

   4.1) For Borland C (BCC) on Windows

   The build process runs silent.
   After compile, look into logfile
   "make_b32.log"
   and search for error messages, if the
   build of HWGUI is not successful.
   Ignore lots of warnings.

   The following libraries must be built:
     hbxml.lib
     hwgdebug.lib
     hwgui.lib
     hwguimt.lib
     procmisc.lib



    5) Additional instructions for Windows 11

    On Windows 11, all HWGUI applications run as well.
    The default terminal is now the "Windows Power Shell",
    it cannot execute *.bat jobs.
    To get the command line terminal, search in the system dialog for
    "cmd.exe" and start it. If running, pin it at the task bar for
    quick call.

    A new feature of Windows 11 is a scalable view. The
    default value is 150 %. This could be to high for bigger
    dialog windows. If a dialog window has no space on the desktop, go to
    the system settings and reduce it to 125 or 100 %.

    In the Power shell you can run Harbour console applications direct,
    but in most cases you need to setup the lines to 25 and the columns to 80.




 Appendix 1: List of packages for Ubuntu Linux and LinuxMINT
 -----------------------------------------------------------

 Instructions for more LINUX distributions see "Appendix 2".
 For GTK3 see "Appendix 3".

  Install packages as system administrator:

  LinuxMINT:
  ~~~~~~~~~~

   sudo apt-get install build-essential linux-headers-generic dkms
   sudo apt-get install libgtk2.0-dev
   sudo apt install wmctrl  *1)
 
   Optional installations:
   The default text editor:
     sudo apt-get install gedit 

   DKMS extensions:	 
   git clone https://github.com/tomaspinho/rtl8821ce
   cd rtl8821ce
   chmod +x dkms-install.sh 
   chmod +x dkms-remove.sh
   sudo ./dkms-install.sh   # needs some time
   sudo modprobe -v 8821ce

   Ubuntu 18:
   ~~~~~~~~~~

   sudo apt-get install linux-headers-generic
   sudo apt-get install libgtk2.0-dev
   sudo apt install wmctrl  *1)

   Ubuntu 20.04.2.0 LTS:
   ~~~~~~~~~~~~~~~~~~~~~

   sudo apt-get install linux-headers-generic
   sudo apt-get update -y

   For installation of GTK2 package you need the installation media, confirm
   mount with <ENTER> key during installation:
   sudo apt-get install -y libgtk2.0-dev

   sudo apt install wmctrl  *1)

   If the following message after start of HWGUI application appeared:
       Failed to load module "canberra-gtk-module"
   install packages:
       sudo apt-get install libcanberra-gtk-module libcanberra-gtk3-module



   Optional for all distributions (resolve dependencies), install them, if needed:
    sudo apt-get install libxmu-dev libxaw7-dev libxt-dev

  For higher security and easier development we recommend a "non root" installation
  of Harbour and HWGUI (You can ever use the newest code snapshot of Harbour and HWGUI).


  To avoid the Gtk-WARNING "Unable to locate theme engine in module_path: "adwaita":
    sudo apt-get install gnome-themes-standard

   *1) This is necessary for set focus on progress bars, see sample program
       "samples/gtk_samples/progbars.prg".


    Knoppix by Klaus Knopper:
    ~~~~~~~~~~~~~~~~~~~~~~~~~

    Knoppix does not support GTK2.
    So be patient, the port of HWGUI to GTK3
    will start as soon as possible.
    Harbour is compilable without any trouble.
    All development packages are installed with
    the regular system installation.



  1.) You need some entries in the .profile in the home directory of the desired
      userid (sample):

   # --- Harbour and HWGUI --
   HARBOUR_INSTALL=$HOME/Harbour/core-master
   export HARBOUR_INSTALL
   HWGUI_INSTALL=$HOME/hwgui
   PATH=$PATH:$HARBOUR_INSTALL/bin/linux/gcc:$HWGUI_INSTALL/bin
   export PATH
   LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$HARBOUR_INSTALL/lib/linux/gcc
   export LD_LIBRARY_PATH
   #

   Modify the path entries to your own needs.

   Login to this userid new after modification, so that the
   entries become valid.


   2.) Build Harbour
   Get the recent code snapshot and build Harbour following the installation instructions.
   If Harbour was build complete, it is ready for HWGUI.
   Some error messages appeared because of missing dependencies, ignore them.
   Take care of them, if referenced Harbour extensions are used by your application.    


   3.) Build HWGUI following instructions above.

   Now you should be able to build your application. 

   On Ubuntu 20.04.2.0 LTS some warnings like
   "‘GTimeVal’ is deprecated:"
   appeared, but dont care of them.


Appendix 2:
-----------

Additional instructions and information for other LINUX distributions.

Raspberry Pi 400
----------------

See extra installation instructions in text file:
Install_RaspberryPi.txt


Ubuntu 22.04 LTS (5.15.0-27-generic), AMD 64 by 16th May 2022.
--------------------------------------------------------------
(DF7BE)

Because of different benaviour of make 4.3 here the additional instructions:

Contents of .profile:

# --- Harbour and HWGUI --
   HARBOUR_INSTALL=/home/cltest/Harbour/core-master
   HWGUI_INSTALL=$HOME/svnwork/hwgui-code/hwgui
   PATH=$PATH:$HARBOUR_INSTALL/bin/linux/gcc:$HWGUI_INSTALL/bin
   export PATH
   LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$HARBOUR_INSTALL/lib/linux/gcc
   export LD_LIBRARY_PATH
   HB_COMPILER=gcc
   export HB_COMPILER
   HB_INSTALL_PREFIX=$HARBOUR_INSTALL
   export HB_INSTALL_PREFIX
#

- Use full path for HARBOUR_INSTALL
- New variables HB_COMPILER and HB_INSTALL_PREFIX.

(solve trouble with autodetect).

Complete list of installed packages:

sudo apt-get install make
sudo apt-get install linux-headers-generic
sudo apt-get update -y
sudo apt install wmctrl 
sudo apt-get install libcanberra-gtk-module libcanberra-gtk3-module 
sudo apt-get install libxmu-dev libxaw7-dev libxt-dev
sudo apt-get install gpm
sudo apt-get install libgpm-dev
sudo apt-get install glslang-dev
sudo apt-get install xorg-dev
sudo apt-get install libncurses-dev
sudo apt-get install libslang2-dev
sudo apt-get install libx11-dev
sudo apt-get install libjpeg-dev
sudo apt-get install libpcre3-dev
sudo apt-get install libtiff-dev
sudo apt-get install liballegro4.2-dev
sudo apt-get install libcairo2-dev
sudo apt-get install libcups2-dev
sudo apt-get install libcurl4-gnutls-dev
sudo apt-get install firebird-dev 
sudo apt-get install libfreeimage-dev
sudo apt-get install libgs-dev
sudo apt-get install libmagic-dev
sudo apt-get install unixodbc-dev
sudo apt-get install libpq-dev
sudo apt-get install libcurl4-openssl-dev
sudo apt-get install libgtk2.0-dev

!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
Urgent instructions (2022-06-21)
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

Some obscure behavior detected, 
for example freezed program after start a
function from menu.

These are bugs in the operation system.

Forever update your system to the recent version !!


Appendix 3:
-----------

Information for port to GTK3

Now the port to GTK3 is under construction !!!!

The first steps are done, but
there is to do some work.

On Ubuntu, you need to install the GTK3 developper package:
sudo apt-get install libgtk-3-dev

Look into the recent state of GTK3 migration in text file

doc/GTK3.txt

DF7BE, December 2022


* =============== EOF of install.txt ====================


