This page gives some essential instructions about building pgModeler from source, installing, and running it on all supported platforms. Please, read it carefully and avoid skipping any steps below even if you're an experienced user in compiling softwares from the source. If you stumble on any problem just ask for help at Github issues page by posting as many as possible details about it so the correct support can be provided. Finally, if you find any error in this document, please report it so the proper fixes can be applied. All suggestions or constructive criticisms to make the building steps easier to understand are welcome!

  • Requirements overview

    On all supported platforms, the first requirement is the Qt framework. The LTS (Long Term Support) modality is recommended but any stable version can be used just make sure to use a version not lower than 5.9.x. Bear in mind that failing to observe this first requirement in most cases will cause the compilation to fail due to incompatibilities between the pgModeler's source code and the Qt framework, or even the deployment steps below may not be enough to make the software work after a successful build.

    Second, you will need a PostgreSQL installation. In this document we are using the RDBMS in its version 12, so note that the location of headers and libraries in the settings below may vary depending on the version of the database system you've chosen.

    Finally, you will need to download a fresh copy of pgModeler's source code. See the source download form for more details about retrieving the source code. Once retrieved the source code, you have to extract it (in case of using a tarball) and run all the commands in the below sections from the root folder.


    Important notes

    1) Some Linux distros already deliver Qt framework runtime libraries and development packages, but in some few cases, the system installs Qt 4 and Qt 5 causing incompatibilities during the execution of the compilation procedures, so in order to make this step-by-step as simple as possible make sure to be using Qt 5 on all building commands below.

    2) Due to the constant improvements in the Qt framework some deprecation warnings may be displayed during the building process. These warnings are harmless in 99% of the time but if the build is aborted due to errors that may point out some incompatibility, please, report it as soon as possible so a patch can be applied to pgModeler's source.

  • Platform specific requirements

    Qt framework: the majority of Linux distros the Qt framework is provided by their package repositories, just make sure to install the runtime libraries and development packages. For that procedures, please refer to your preferred distro's docs for more information about the installation of the framework. To check if Qt is correctly installed run the command in the line (1) below in the console. If the result is similar to the lines (2) and (3) then Qt framework is already installed. In case of an error is returned you need to check the installation.

    1: qmake -version
    2: QMake version 3.1
    3: Using Qt version 5.12.0 in /usr/lib64


    GCC or Clang compiler: pgModeler is coded in it's most using the C++ language. Make sure to have installed at least GCC 4.8+ or LLVM 3.4+ to enable the full language support.

    XML2 library: generally the runtime files are already installed but the needed headers are absent in most cases. Make sure to access your distro's software management and install the development packages for XML2 which bundles the source code and libraries for compilation purposes. To check if the library is correctly installed run the command in the line (1) below in the console. If the result is similar to the line (2) then libxml2 is already installed. In case of an error is returned you need to check the installation.

    1: pkg-­config libxml-­2.0 --cflags --libs
    2: ­-I/usr/include/libxml2 ­-lxml2


    PostgreSQL client library: the communication between pgModeler and a database server is made through the PostgreSQL client interface called libpq. The library installation details are retrieved via pkg­-config command during compile time so to check if everything is okay run the command on line (1) in the console. If the result is similar to the line (2) then library is correctly installed. In case of an error is returned you need to check the installation.

    1: pkg­-config libpq --cflags --libs
    2: ­I/usr/include ­L/usr/lib64/libpq.so

    To make the compilation easier on Windows systems we recommend the use of MSYS2 which consists in a software distro and building platform which facilitates the installation of the needed packages and their dependencies including Qt framework and PostgreSQL. First, install MSYS2 64 bits and open the MSYS2 MinGW 64-bit available under MSYS2 group at Windows' start menu.

    Then run the following commands in the correct order. Lines (1) and (2) are intentionally duplicated and need to be executed if you're running MSYS2 for the first time. To avoid typos copy the lines below and paste them on the console:

    1: pacman -Suy
    2: pacman -Suy
    3: pacman -S base-devel mingw-w64-x86_64-make mingw-w64-x86_64-gcc mingw-w64-x86_64-postgresql mingw-w64-x86_64-qt5

    Qt framework: since macOS doesn't come with this toolkit installed by default, download and install it from the official project's web site.

    Xcode: the development toolkit for macOS and the minimum requirement is the version 4.4 but it's recommended to use the latest version available because, depending on the Qt version, the compilation will fail mainly due to incomplete language support.

    XML2 library: if you have installed Xcode correctly the needed headers and libraries are installed as well. You'll just need to change a few lines in the building script (see the next section).

    PostgreSQL client library: for practical reasons on macOS, the installers provided by EnterpriseDB are strongly recommended since they bundle all the needed headers and libraries.

  • Tweaking the building script

    If you are compiling pgModeler in Windows or macOS there is a preliminary step before run the main compilation command. You need to configure the location of the dependency headers and libraries by editing the file pgmodeler.pri. Assuming that you've already got the source code open the mentioned file in your favorite text editor and locate the following lines:

    windows {
      !defined(PGSQL_LIB, var): PGSQL_LIB = C:/msys64/mingw64/bin/libpq.dll
      !defined(PGSQL_INC, var): PGSQL_INC = C:/msys64/mingw64/include
      !defined(XML_INC, var): XML_INC = C:/msys64/mingw64/include/libxml2
      !defined(XML_LIB, var): XML_LIB = C:/msys64/mingw64/bin/libxml2-2.dll
      ...
    }
    
    macx {
      PGSQL_LIB = /Library/PostgreSQL/12/lib/libpq.dylib
      PGSQL_INC = /Library/PostgreSQL/12/include
      XML_INC = /Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/usr/include/libxml2
      XML_LIB = /usr/lib/libxml2.dylib
      ...
    }

    Make sure to edit only the section corresponding to your platform. You need to change the values of the variables PGSQL_LIB, PGSQL_INC, XML_INC and XML_LIB. These variables tell the compiler where to find the headers and libraries for libxml2 as well libpq. Update the values according to the location of the files or folders in your system. Save the file and proceed to the next step.

  • Building the software

    We are now able to run the main building process. This step differs a bit on each operating system and it is described below. All the commands must be executed inside the console and from the root of the pgModeler's source code folder. In Windows system remember to run the commands from the MSYS2 MinGW 64-bit console available under MSYS2 group at start menu.

    In the following procedures, to shorten the commands, we are assuming that $QT_ROOT is the full path to the Qt installation which varies from system to system, so remember to replace the variable with the real path according to your system. The variable $INSTALLATION_ROOT is the path where pgModeler should be installed after the building process is complete. Again, don't forget to replace the variables by the respective full path according to the running operating system.

    On macOS system, the installation root is always the path to the bundle created after running make install command: /Applications/pgmodeler.app. Currently, there's no support to change the installation folder on this operating system.


    1: $QT_ROOT/bin/qmake -r CONFIG+=release PREFIX=$INSTALLATION_ROOT BINDIR=$INSTALLATION_ROOT \
                             PRIVATEBINDIR=$INSTALLATION_ROOT PRIVATELIBDIR=$INSTALLATION_ROOT/lib pgmodeler.pro
    2: make
    3: make install
    
    1: qmake -r CONFIG+=release PREFIX=$INSTALLATION_ROOT pgmodeler.pro
    2: make
    3: make install
    4: cd $INSTALLATION_ROOT
    5: windeployqt pgmodeler.exe pgmodeler_ui.dll
    
    1: $QT_ROOT/bin/qmake -r CONFIG+=release pgmodeler.pro
    2: make
    3: make install
    4: $QT_ROOT/bin/macdeployqt $INSTALLATION_ROOT \
                                $INSTALLATION_ROOT/Contents/MacOS/pgmodeler-ch \
                                $INSTALLATION_ROOT/Contents/MacOS/pgmodeler-cli
    

  • Resolving dependencies

    After successfully compiling the source code and installing the binaries we need to copy some dependencies into the pgModeler's installation folder and run some commands to make the binaries locate them properly. As the previous section, in the steps below replace the variable $INSTALLATION_ROOT by the path were pgModeler is now installed. The variable $PGSQL_ROOT must be replaced by the full path to PostgreSQL's installation folder. The variable $PGMODELER_SOURCE must be replaced by the full path to pgModeler's source code directory, and $MSYS2_ROOT must be replaced by the full path to MSYS2 installation (only for Windows).


    1: cd $QT_ROOT/lib
    2: cp libQt5DBus.so.5 libQt5PrintSupport.so.5 libQt5Widgets.so.5 libQt5Network.so.5 libQt5Gui.so.5 \
          libQt5Core.so.5 libQt5XcbQpa.so.5 libQt5Svg.so.5 libicui18n.so.* libicuuc.so.* libicudata.so.* $INSTALLATION_ROOT/lib
    3: cd $QT_ROOT/plugins
    4: mkdir $INSTALLATION_ROOT/lib/qtplugins
    5: mkdir $INSTALLATION_ROOT/lib/qtplugins/imageformats
    6: mkdir $INSTALLATION_ROOT/lib/qtplugins/printsupport
    7: mkdir $INSTALLATION_ROOT/lib/qtplugins/platforms
    8: cp -r imageformats/libqgif.so imageformats/libqico.so imageformats/libqjpeg.so imageformats/libqsvg.so \
             imageformats/libqtga.so imageformats/libqtiff.so imageformats/libqwbmp.so $INSTALLATION_ROOT/lib/qtplugins/imageformats
    9: cp -r printsupport/libcupsprintersupport.so $INSTALLATION_ROOT/lib/qtplugins/printsupport
    10: cp -r platforms/libqxcb.so $INSTALLATION_ROOT/lib/qtplugins/platforms
    11: echo -e "[Paths]\nPrefix=.\nPlugins=lib/qtplugins\nLibraries=lib" > $INSTALLATION_ROOT/qt.conf
    12: cp $PGMODELER_SOURCE/start-pgmodeler.sh $PGMODELER_SOURCE/pgmodeler.vars $INSTALLATION_ROOT
    13: chmod +x $INSTALLATION_ROOT/start-pgmodeler.sh
    
    1: cd $MSYS2_ROOT/mingw64/bin/
    2: cp libicuin*.dll libicuuc*.dll libicudt*.dll libpcre2-16-0.dll libharfbuzz-0.dll \
          libpng16-16.dll libfreetype-6.dll libgraphite2.dll libglib-2.0-0.dll libpcre-1.dll \
          libbz2-1.dll libssl-1_1-x64.dll libcrypto-1_1-x64.dll libgcc_s_seh-1.dll \
          libstdc++-6.dll libwinpthread-1.dll zlib1.dll libpq.dll libxml2-2.dll liblzma-5.dll \
          libiconv-2.dll libintl-8.dll libbrotlidec.dll libbrotlicommon.dll $INSTALLATION_ROOT
    
    1: cp $PGSQL_ROOT/lib/libpq.5.dylib $PGSQL_ROOT/lib/libssl.1.* \
          $PGSQL_ROOT/lib/libcrypto.1.* $INSTALLATION_ROOT/Contents/Frameworks
    2: install_name_tool -change "@loader_path/../lib/libcrypto.1.1.dylib" "@loader_path/../Frameworks/libcrypto.1.1.dylib" $INSTALLATION_ROOT/Contents/Frameworks/libssl.1.1.dylib
    3: install_name_tool -change "@loader_path/../lib/libcrypto.1.1.dylib" "@loader_path/../Frameworks/libcrypto.1.1.dylib" $INSTALLATION_ROOT/Contents/Frameworks/libpq.5.dylib
    4: install_name_tool -change "@loader_path/../lib/libssl.1.1.dylib" "@loader_path/../Frameworks/libssl.1.1.dylib" $INSTALLATION_ROOT/Contents/Frameworks/libpq.5.dylib
    5: install_name_tool -change libpq.5.dylib "@loader_path/../Frameworks/libpq.5.dylib" $INSTALLATION_ROOT/Contents/Frameworks/libpgconnector.dylib
    

  • Running pgModeler

    Finally, pgModeler can be started. Just open the installation folder and double click the application pgmodeler.exe (Windows), pgmodeler (Linux) or pgmodeler.app (macOs) and have fun. On Linux, if the software didn't start after double clicking it then there's the need to change a few environment variables to make the tool run properly. As a facility there are two scripts that may be used to tweak environment variables without affect the whole system settings.

    The first file is the pgmodeler.vars which contains template configuration for the variables referenced by pgModeler during runtime. Open the file in your favorite text editor and change the variables according to the location of the referenced files or folders in your system (the script is well comment so all details are described in that file). Anyway, if you followed this document correctly there's no need to edit it. The second file is a startup script called start-pgmodeler.sh that just loads the environment variables and calls the main executable. Once all the settings are done open a terminal instance and run the startup script start-pgmodeler.sh from the installation folder.

    Enjoy!


  • Custom parameters

    This optional section describes how the build process can be customized in such way that the files are generated in different directories other than the default ones. This way pgModeler introduces eleven custom parameters that can be passed to qmake in order to configure the custom output folders. The use of custom build parameters is a good mechanism for package maintainers (in case of Linux distros) to create custom releases that better suits each system's requirements. The details of these parameters and how they can be used is shown in the table below. Note that if you modify the value of any custom parameter you'll need to reflect these changes on the building steps above.

    Parameter Description
    PREFIX The path to the root directory where the compiled files will be placed.
    BINDIR The path to the folder where executables accessible by the user will reside.
    CONFDIR The path to the folder where the pgModeler's template configuration folder conf will be installed.
    DOCDIR The path to the folder where the documentation related files are placed.
    LANGDIR The path to the folder where the UI translation folder lang resides.
    SAMPLESDIR The path to the folder where the sample models folder samples resides.
    SCHEMASDIR The path to the folder where the object's schemas folder schemas resides.
    SHAREDIR The path to the folder where shared files and resources must be placed. Generally, this is the root path where folders like langsamples and schemas will be placed.
    PRIVATEBINDIR The path to the folder where executables not directly accessible by the user will be placed (e.g. crash handler executable – pgmodeler-­ch).
    PRIVATELIBDIR The path to the folder where libraries not directly shared through the system will reside.
    PLUGINSDIR The path to the folder where third party plug­ins are installed.

    Now, to use one of these parameters run qmake as following:

    $QT_ROOT/bin/qmake pgmodeler.pro PREFIX=[PATH] BINDIR=[PATH] CONFDIR=[PATH]

    After running qmake command with the custom parameters a small summary is displayed so you can check if the configured variables really point out to the desired locations. From here, you can (re)build the application by following the building steps from previous sections so the changes in the custom parameters can take effect.

    ** pgModeler build details **
    
    PREFIX = /home/user/pgmodeler/build 
    BINDIR = /home/user/pgmodeler/build 
    PRIVATEBINDIR = /home/user/pgmodeler/build 
    PRIVATELIBDIR = /home/user/pgmodeler/build 
    PLUGINSDIR = /home/user/pgmodeler/build/plugins 
    SHAREDIR = /home/user/pgmodeler/build 
    CONFDIR = /home/user/pgmodeler/build/conf 
    DOCDIR = /home/user/pgmodeler/build 
    LANGDIR = /home/user/pgmodeler/build/lang 
    SAMPLESDIR = /home/user/pgmodeler/build/samples 
    SCHEMASDIR = /home/user/pgmodeler/build/schemas 
    
    * To change a variable value run qmake again setting the desired value e.g.:
    > qmake PREFIX+=/usr/local -­r pgmodeler.pro 
    
    * Proceed with build process by running: 
    > make && make install



    Did these steps help you to put the software to run? That's great! Now, how about give a little help to the project? :)

    pgModeler is brought to you thanks to a great effort to create and distribute a quality product. This project is reaching out to levels of maturity never imagined. All this is the result of joint work between its author and the Open source community. The software has a long way to go yet, and with your help, we'll keep maintaining a good job and bringing new improvements in each release. If you did like pgModeler and think it deserves a contribution, please make a donation via PayPal™. Note that donations don't grant access to binary packages.

    10.00 USD