Windows - Building PTerm (Part 1)
Overview
This article outlines the detailed process of building PTerm 1) from sources. Use the navigation provided in the table of contents (on the right) to jump to the correct section.
Project Support
The Retro1 project supports an installer distribution for:
These are 64-bit application binaries only.
While instructions are provided here to build PTerm on any Linux-like platform, the project will not provide support beyond the two noted above.
Preparation
Gathering and verifying all of the prerequisite tooling, libraries and setting up the Development environment will save time.
-
-
Read about the installation options for
wxWidgets.
Study Build Configurations
DO NOT use the pre-built binaries.
-
-
-
-
Environment Variables Check
It is critical that, after installation of Visual Studio 2022, the following environment variables exist. You may need to reboot in order to ensure their presence:
VS170COMCOMNTOOLS=C:\Program Files\Microsoft Visual Studio\2022\Community\Common7\Tools
VS170COMNTOOLS=C:\Program Files\Microsoft Visual Studio\2022\Community\Common7\Tools
Repository Structure
This tutorial article relies on the the Hobbyist's prior understanding of the tools noted above. Before proceeding, understading the Development repository's structure is also a critical element in generating a successful build.
Folder PATH diagram for Development Environment
?:\MyDevelopmentRoot
+---libs (Build Libraries)
¦ +---libsndfile-1.2.2-win64
¦ +---SDL2-2.32.4
¦ +---wxWidgets-3.2.7
+---Pterm7
+---.idea (PyCharm Directory)
+---.venv (Python Virtual Environment)
¦ +---Lib
¦ +---Scripts
+---assets (PTerm Assets)
+---bin
¦ +---pterm (Linux App Binary)
¦ +---Pterm.app (MacOS Application)
+---docs (Application Documentation)
+---i18n (Unused)
¦ +---nl
+---installers (Windows Installers)
+---IST-loadfiles (PyCharm Directory)
+---microTUTOR (Disk Images and Documentation)
+---obj (Compiler Objects Directory non-windows)
+---prototypes (Templates for various builds)
+---PTDevUtils (Application Build Utilities)
+---pterm.codeblocks
+---Pterm.pmdoc (Pterm[6] Package Management MacOS)
+---Pterm7.MacOS (Pterm[7] Package Management MacOS)
+---redist (Application Redistributables)
¦ +---MtutorFloppys
+---setools (Software Engineering Tools)
+---src (Application Source)
+---tests (Automated Tests)
+---Win32 (Windows 32-bit Binaries)
¦ +---Debug
¦ ¦ +---PTerm7
¦ +---Release
¦ +---PTerm7
+---wxFormBuilder (Designer Files)
+---x64 (Windows 64-bit Binaries)
+---Debug
¦ +---PTerm7
+---Release
+---PTerm7
Install Python
Install Python Minimum version 3.12 using the Recommended Installer .
Ensure that you have the proper version by issuing the following command:
python --version
Python will respond with the following information
Python 3.x.y
Where: x
(minor version) is 12 or greater and y
is the patch level for that minor version
Once installation is complete, you must test the integrated build tool (a Python module called PTDevUtils) by issuing the following command:
set PYTHONUTF8=1
python -m PTDevUtils version
It is recommended that you set that environment variable PYTHONUTF8=1
in your user or system profile
That command should produce the following response if Python was correctly installed:
Package PTDevUtils
Command PTDevUtils
Version 1.0.1.0
Install InnoSetup
Library Setup
All wxWidgets
libraries are built “by hand” to ensure that the binaries are all consistent with the soon-to-be-compiled Pterm.
Structure Matters
All Visual Studio Project references are relative to the cloned repository root, therefore, the placement of the libs
directory is important. Many engineers may not have a deterministic location for their libraries, therefore we use the lib
directory, and the junction links within it, as a means of abstracting away the specifics within the Visual Studio solution file.
About This Library
This library is manually built because the respective release
and debug
versions of the libraries are linked into the respective release
and debug
executables.
Distribution of applications built on wxWidgets is a notoriously 'finicky' process so to minimize complexity in the Windows build, we use the statically-linked
versions of the libraries.
Setting up wxWidgets on windows is straightforward using the helper cmd file included below. Simply download this file, and drag/drop the wxWidgets-3.2.7
folder onto the .cmd
file and the build should proceed.
This file builds the STATIC and DYNAMIC link versions of the RELEASE and DEBUG versions of the wxWidgets libraries.
This Will Take Time
Between each phase, the test “minimal app” is displayed to ensure that everything is working properly before proceeding to the next steps. The next phase will not continue until the minimal app is closed.
Build_wxWidgets_vc_X64
- Build_wxWidgets_vc_X64.cmd
@echo Off
@setlocal ENABLEEXTENSIONS ENABLEDELAYEDEXPANSION
:: set _DRY_RUN=/N
set _MAKEFILE=makefile.vc
set _MAKE=nmake
set _ARCH=64
set _WXDLLS=\lib\vc_x64_dll
if "%1" == "" if NOT DEFINED WXWIN goto NoTargetSpecified
if NOT "%1" == "" SET WXWIN=%~1
if NOT EXIST "!WXWIN!\build\msw" goto InvalidTargetSpecified
set _WXVER=!WXWIN:*-=!
echo :: Scanning for wxVersion=!_WXVER!
:: Depending on the version, the structure of the test directory
:: names of the samples will change.
if "!_WXVER!" == "3.0.5" (
set _WXTESTU=vc_mswu_x64
set _WXTESTUD=vc_mswud_x64
set _WXTESTUDLL=vc_mswudll_x64
set _WXTESTUDDLL=vc_mswuddll_x64
set _WXUSEOPENGL=1
goto :VersionMatched
)
if "!_WXVER!" == "3.1.5" (
set _WXTESTU=vc_mswu_x64
set _WXTESTUD=vc_mswud_x64
set _WXTESTUDLL=vc_mswudll_x64
set _WXTESTUDDLL=vc_mswuddll_x64
set _WXUSEOPENGL=0
goto :VersionMatched
)
if "!_WXVER!" == "3.1.7" (
set _WXTESTU=vc_x64_mswu
set _WXTESTUD=vc_x64_mswud
set _WXTESTUDLL=vc_x64_mswudll
set _WXTESTUDDLL=vc_x64_mswuddll
set _WXUSEOPENGL=0
goto :VersionMatched
)
if "!_WXVER!" == "3.2.0" (
set _WXTESTU=vc_x64_mswu
set _WXTESTUD=vc_x64_mswud
set _WXTESTUDLL=vc_x64_mswudll
set _WXTESTUDDLL=vc_x64_mswuddll
set _WXUSEOPENGL=0
goto :VersionMatched
)
if "!_WXVER!" == "3.2.1" (
set _WXTESTU=vc_x64_mswu
set _WXTESTUD=vc_x64_mswud
set _WXTESTUDLL=vc_x64_mswudll
set _WXTESTUDDLL=vc_x64_mswuddll
set _WXUSEOPENGL=1
goto :VersionMatched
)
if "!_WXVER!" == "3.2.2.1" (
set _WXTESTU=vc_x64_mswu
set _WXTESTUD=vc_x64_mswud
set _WXTESTUDLL=vc_x64_mswudll
set _WXTESTUDDLL=vc_x64_mswuddll
set _WXUSEOPENGL=1
goto :VersionMatched
)
if "!_WXVER!" == "3.2.6" (
set _WXTESTU=vc_x64_mswu
set _WXTESTUD=vc_x64_mswud
set _WXTESTUDLL=vc_x64_mswudll
set _WXTESTUDDLL=vc_x64_mswuddll
set _WXUSEOPENGL=1
goto :VersionMatched
)
if "!_WXVER!" == "3.2.7" (
set _WXTESTU=vc_x64_mswu
set _WXTESTUD=vc_x64_mswud
set _WXTESTUDLL=vc_x64_mswudll
set _WXTESTUDDLL=vc_x64_mswuddll
set _WXUSEOPENGL=1
goto :VersionMatched
)
echo ::
echo :: The version number was unable to be detected
echo :: Expected directory name to be fully-qualified of the structure
echo ::
echo :: ^<Drive^>^:^<\path-to-lib^>\^<libraryName^>-^<version^> where:
echo :: ^<libraryName^> = wxWidgets
echo :: ^<version^> = ^(3.0.5 ^| 3.1.5 ^| 3.1.7 ^| 3.2.0 ^| 3.2.1 ^| 3.2.2.1 ^| 3.2.6 ^| 3.2.7 ^)
echo ::
goto FAIL
:VersionMatched
echo ::
echo :: Building wxWidgets !_WXVER! for Visual Studio 64-bit
echo ::
:: Building Visual Studio Version of wxWidgets
:: %1 = Top Level Directory
:: %2 = Switches
:: Uncomment for vs2019
:: cd /d "C:\Program Files (x86)\Microsoft Visual Studio\2019\Community\"
:: call "C:\Program Files (x86)\Microsoft Visual Studio\2019\Community\Common7\Tools\VsDevCmd.bat"
:: call "C:\Program Files (x86)\Microsoft Visual Studio\2019\Community\VC\Auxiliary\Build\vcvars64.bat"
:: Uncomment for vs2022
cd /d "C:\Program Files\Microsoft Visual Studio\2022\Community\"
call "C:\Program Files\Microsoft Visual Studio\2022\Community\Common7\Tools\VsDevCmd.bat"
call "C:\Program Files\Microsoft Visual Studio\2022\Community\VC\Auxiliary\Build\vcvars!_ARCH!.bat"
WHERE /Q !_MAKE!
if NOT !ERRORLEVEL! EQU 0 goto MissingMake
::
:: Now build up and test each of the 4 supported combinations
::
:: SHARED TYPE RUNTIME_LIBS Description TestDir Use OpenGL
:: ------ ------- ------------ -------------------- ------------ ----------------
Call :BuildAndTest 0 debug "static" "Static Debug" "!_WXTESTUD!" "!_WXUSEOPENGL!"
Call :BuildAndTest 0 release "static" "Static Release" "!_WXTESTU!" "!_WXUSEOPENGL!"
Call :BuildAndTest 1 debug "dynamic" "Shared/DLL Debug" "!_WXTESTUDDLL!" "!_WXUSEOPENGL!"
Call :BuildAndTest 1 release "dynamic" "Shared/DLL Release" "!_WXTESTUDLL!" "!_WXUSEOPENGL!"
Goto SUCCESS
:BuildAndTest
echo ::
echo :: Building %~4 Configuration with C^+^+17 Support
echo ::
cd /d !WXWIN!\build\MSW
set _MakeCommand=!_MAKE! !_DRY_RUN! -f !_MAKEFILE! SHARED=%~1 BUILD=%~2 CXXFLAGS="/std:c++17" USE_OPENGL=%~6 RUNTIME_LIBS="%~3" TARGET_CPU=X!_ARCH!
!_MakeCommand! setup_h
IF %ERRORLEVEL% NEQ 0 goto FAIL
!_MakeCommand!
IF %ERRORLEVEL% NEQ 0 goto FAIL
echo ::
echo :: Testing Minimal.EXE ^[%~4^]
echo :: Build / Test will continue when application exits
echo ::
setlocal ENABLEEXTENSIONS ENABLEDELAYEDEXPANSION
cd /d !WXWIN!\samples\minimal
!_MakeCommand! clean
!_MakeCommand!
cd /d !WXWIN!\samples\minimal\%5
if "%~1" == "0" goto SkipDLLs
path !WXWIN!!_WXDLLS!;%PATH%
:SkipDLLs
minimal.exe
endlocal
exit /b
:MissingMake
echo :: %~nx0 (Usage)
echo :: The required command ^[!_MAKE!^] does not exist.
echo ::
goto FAIL
:InvalidTargetSpecified
echo :: %~nx0 (Usage)
echo :: The Specified Target ^[!WXWIN!^] does not have a subpath of \build\msw or does not exist.
echo ::
goto FAIL
:NoTargetSpecified
echo :: %~nx0 (Usage)
echo :: There was no build target specified
echo ::
echo :: You may
echo :: (a) use this file as a "Drop Target" for the wxWidgets base directory
echo :: (b) Define the environment variable WXWIN to point to the wxWidgets base directory
echo ::
goto FAIL
:FAIL
echo :: Build failed, see above why.
echo :: ^[NOTE^] Running parallel jobs may cause occasional synchronization failures...
echo :: You should attempt to rebuild again until it's successful.
pause
goto FINISHED
:SUCCESS
:FINISHED
endlocal
echo :: (End Run %~nx0)
PAUSE
Once the build is complete, create a junction in the libs
directory using MKLINK
:
mklink /j
<PathToYourLibsDirectory>\libs\wxWidgets-3.2.7
<PathToDistribution>\wxWidgets-3.2.7
The link should now be created and confirmed:
Junction created for
<PathToYourLibsDirectory>\libs\wxWidgets-3.2.7 <<===>>
<PathToDistribution>\wxWidgets-3.2.7
libsndfile
Release Libraries Only
This library is used as-supplied and the release
versions of the libraries are linked into both release
and debug
executables.
NOTE: This library's .dll
file is included in the installer.
Unpack the official release from Release 1.2.2 on Github (file libsndfile-1.2.2-win64.zip
)5) into the DevLibs
directory. In this case, we use the project-supplied versions of the files.
Make a link to the distribution in the libs
folder:
mklink /j <PathToLibs>\libs\libsndfile-1.2.2-win64 <PathToDistribution>\libsndfile-1.2.2-win64
SDL2
Release Libraries Only
This library is used as-supplied and the release
versions of the libraries are linked into both release
and debug
executables.
NOTE: This library's .dll
file is included in the installer.
Unpack the official release binaries from Release 2.32.4 on Github (file SDL2-devel-2.32.4-VC.zip
) into the Devlibs
directory. We use the project-supplied versions of the files.
Make a link to the distribution in the libs
folder:
mklink /j <PathToLibs>\libs\SDL2-2.32.4 <PathToDistribution>\SDL2-2.32.4
Next Steps