Building wxMGL Port

From WxWiki
Jump to: navigation, search

What is wxMGL?

wxMGL is a port of wxWidgets using the MGL library available from SciTech as the underlying graphics backend. wxMGL draws its widgets using the wxUniversal widget set which is now part of wxWidgets.

MGL itself runs on a variety of platforms including Windows, Linux, DOS, OS/2, QNX, SMX, RT-Target and other embedded operating systems.

Wxwiki wxMGL scr1.jpg

Setup Your Development Environment

We will discuss building process on the concrete example. Let’s choose DOS as the target platform and compile using DJGPP, which is a port of the GNU C/C++ compiler and GNU development tools to 32-bit, protected-mode environment under MS-DOS and compatible systems. First of all we’ll need the machine with DOS installed or DOS bootable disk (floppy, CD). This can be MS-DOS 7.10 with LFN support; also any other related system such as PC-DOS, DR-DOS and FreeDOS should be fine. Please see “Hardware and software requirements for DJGPP” to get more information. CWSDPMI is used to provide DPMI services for DJGPP.

Actually building wxMGL in pure DOS maybe is not the best choice due to the different reasons (slow compiling, without enough free conventional memory there can occur “memory exhaustion” problems, etc.). So it’s highly recommended to use VMware Workstation 6.0 or higher, running Windows 98 SE guest OS, as the development system and DOS as the environment for running already built wxMGL applications. If there is no possibility to use VMware you can install Windows 98 SE on the real machine and simply reboot in MS-DOS mode to check wxMGL programs or run them on Windows 98 directly. But there is something worth mentioning when dealing with Windows 98. If you're running the program at Ring 3, it will not work without SDDHELP.VXD or PMHELP.VXD loaded, which can be obtained together with SNAP/MGL sources. To run your program at Ring 0 you can use CWSDPR0.EXE from CWSDPMI binary distribution, e.g. rename CWSDPR0.EXE to CWSDPMI.EXE in %DJGPP%\BIN, where %DJGPP% is the path to djgpp install directory (about djgpp installation see below). Also note that MGL is the low-level library and Scitech’s drivers work directly with hardware. So it’s better to run built wxMGL applications on the real machine in spite of that they may work on the VMware in some cases.

From this moment assume that we have computer with some host OS installed and running VMware Workstation 6.0 with Windows 98 SE guest OS. To copy files from host OS to VMware guest OS:

  • Just drag and drop needed files and/or folders. This will work at least with both host and guest OS being from Windows family (e.g. host – Windows XP Pro SP2, guest – Windows 98 SE).
    VMware Tools have to be installed in order to use this feature.
  • Use CD-ROM or floppy which can be physical or virtual. In the latter case you’ll need CD ISO or floppy IMA image, respectively.
  • Transfer via network.
  • Install Windows 98SE USB Mass Storage Device Drivers Version 3.x from here and use USB flash drive.

Please refer to VMware documentation for more details on how to work with this application.

Building for DOS

It’s hard to believe that this nice GUI application runs on pure DOS, isn’t it?

Wxwiki wxMGL scr2.jpg

Ok, let's try to build it by ourselves.

  • Install DJGPP. General information is contained in DJGPP FAQ list. Please see the chapter 4 “Where and What to Download?” for comprehensive installation instructions. Also consider using the DJGPP zip-picker feature which will guide you through the process. Note that the preferred version of gcc/gpp to use is 3.2.3. Here are the steps you typically have to perform:

1. Download the following:

unzip32.exe (to unpack the zip files),
v2/copying.dj (DJGPP Copyright info),
v2/djdev203.zip (DJGPP Basic Development Kit),
v2/faq230b.zip (Frequently Asked Questions),
v2/readme.1st (Installation instructions),
v2gnu/bnu217b.zip (Basic assembler, linker),
v2gnu/gcc323b.zip (Basic GCC compiler),
v2gnu/gdb611b.zip (GNU debugger),
v2gnu/gpp323b.zip (C++ compiler),
v2gnu/mak3791b.zip (Make – processes makefiles),
v2gnu/txi412b.zip (Info file viewer),
v2misc/csdpmi5b.zip (DPMI server).

You can obtain these packages from DJ Delorie’s ftp. If this link is broken please visit DJ Delorie’s Web server to find available mirrors.

2. Also download some UNIX utilities:

v2gnu/bsh204br2.zip (bash shell),
v2gnu/fil41b.zip (file utilities such as mv, rm, chmod, etc.),
v2gnu/fnd4233br3.zip (find),
v2gnu/grep253b.zip (grep),
v2gnu/lss418b.zip (less),
v2gnu/sed415b.zip (sed).

3. Use djgpp's unzip32.exe.

Copy it somewhere in your path (e.g. into C:\WINDOWS) and unpack all the zips you downloaded into the C:\DJGPP folder. Unzip them all to the same place but not into separate folders. The directory structure inside each zip file should be preserved, so you end up with files like c:\djgpp\bin\gcc.exe and c:\djgpp\include\stdio.h. For example:

C:\>mkdir djgpp
C:\>cd djgpp
C:\DJGPP>unzip32 d:\tmp\djdev203.zip
C:\DJGPP>unzip32 d:\tmp\faq230b.zip
C:\DJGPP>unzip32 d:\tmp\bnu217b.zip
C:\DJGPP>unzip32 d:\tmp\gcc323b.zip
C:\DJGPP>unzip32 d:\tmp\gdb611b.zip
C:\DJGPP>unzip32 d:\tmp\gpp323b.zip
C:\DJGPP>unzip32 d:\tmp\mak3791b.zip
C:\DJGPP>unzip32 d:\tmp\txi412b.zip
C:\DJGPP>unzip32 d:\tmp\csdpmi5b.zip
C:\DJGPP>unzip32 d:\tmp\utils\bsh204br2.zip
C:\DJGPP>unzip32 d:\tmp\utils\fil41b.zip
C:\DJGPP>unzip32 d:\tmp\utils\fnd4233br3.zip
C:\DJGPP>unzip32 d:\tmp\utils\grep253b.zip
C:\DJGPP>unzip32 d:\tmp\utils\lss418b.zip
C:\DJGPP>unzip32 d:\tmp\utils\sed415b.zip

When properly installed, you should have a c:\djgpp\bin directory, and in it should be at least gcc.exe, as.exe, and stubify.exe. If all the files are in c:\djgpp with no subdirectories, or you see directories like c:\djgpp\djdev203\, you need to delete everything and try a different unzip program.

4. Open the Start menu.

Pick Programs -> Accessories -> System Tools -> System Information. Then, in the Tools menu, pick System Configuration; there is a tab there that you can use to edit your Autoexec.bat to include the following lines:

set PATH=C:\DJGPP\BIN;%PATH%
set DJGPP=C:\DJGPP\DJGPP.ENV

Note that the PATH statement should follow any other PATH statements, or you may edit an existing one.

You'll need to restart your computer for these changes to take effect.

Rather than edit your autoexec files and/or global environment, you may wish to create a djgpp shortcut instead. To do this, create a c:\djgpp\djgpp.bat that has lines like this:

@echo off
set PATH=c:\djgpp\bin;%PATH%
set DJGPP=c:\djgpp\djgpp.env
cd c:\mystuff

5. Write simple C++ program to check the compiler:

C:\mystuff>edit simple.cpp

// simple.cpp

#include <iostream>

int main()
{
    std::cout << “Hi, DJGPP! :-)” << std::endl;
    return 0;
}

C:\mystuff>gpp simple.cpp -g -Wall -o simple.exe
C:\mystuff>simple
Hi, DJGPP! :-)

C:\mystuff>
  • Install SNAP/MGL. Here is the step by step instruction. Please refer to the documentation provided with sources to get more help.

1. Download the following packages from SciTech’s ftp:

snap_sdk_3.1-r23-docs.zip
snap_sdk_3.1-r23-drivers.zip
snap_sdk_3.1-r23-os2.zip
snap_sdk_3.1-r23-pdf.zip
snap_sdk_3.1-r23-src.zip
snap_sdk_3.1-r23-util.zip
snap_sdk_3.1-r23-win32.zip
mgl_6.0-r23-docs.zip
mgl_6.0-r23-drivers.zip
mgl_6.0-r23-font.zip
mgl_6.0-r23-pdf.zip
mgl_6.0-r23-src.zip
mgl_6.0-r23-ttf1.zip
mgl_6.0-r23-ttf2.zip

2. Unpack obtained packages with unzip32.exe into the C:\SCITECH folder.

Preserve the directory structure inside each zip file, i.e. don't unzip archives each into the separate folders. For example:

C:\>mkdir scitech
C:\>cd scitech
C:\SCITECH>unzip32 d:\tmp\snap_sdk_3.1-r23-docs.zip
C:\SCITECH>unzip32 d:\tmp\snap_sdk_3.1-r23-drivers.zip
C:\SCITECH>unzip32 d:\tmp\snap_sdk_3.1-r23-os2.zip
C:\SCITECH>unzip32 d:\tmp\snap_sdk_3.1-r23-pdf.zip
C:\SCITECH>unzip32 d:\tmp\snap_sdk_3.1-r23-src.zip
C:\SCITECH>unzip32 d:\tmp\snap_sdk_3.1-r23-util.zip
C:\SCITECH>unzip32 d:\tmp\snap_sdk_3.1-r23-win32.zip
C:\SCITECH>unzip32 d:\tmp\mgl_6.0-r23-docs.zip
C:\SCITECH>unzip32 d:\tmp\mgl_6.0-r23-drivers.zip
C:\SCITECH>unzip32 d:\tmp\mgl_6.0-r23-font.zip
C:\SCITECH>unzip32 d:\tmp\mgl_6.0-r23-pdf.zip
C:\SCITECH>unzip32 d:\tmp\mgl_6.0-r23-src.zip
C:\SCITECH>unzip32 d:\tmp\mgl_6.0-r23-ttf1.zip
C:\SCITECH>unzip32 d:\tmp\mgl_6.0-r23-ttf2.zip

3. In the C:\SCITECH\start.bat replace the string “call C:\SCITECH\bin-win32\OW10-W32.BAT” with the “call C:\SCITECH\bin-win32\GCC2-DOS.BAT” one.

4. In the C:\SCITECH\bin-win32\set-vars.bat correct the string “SET DJ_PATH=c:\c\djgpp” to point where you installed DJGPP, e.g. “SET DJ_PATH=c:\djgpp”.

5. Open the Start menu.

Expand Programs -> Drag and drop MS-DOS Prompt with right button to the desktop -> Select Create Shortcut(s) Here from the context menu -> Right click on MS-DOS Prompt shortcut -> Select Properties -> Open Memory tab -> Set Initial environment to 4096 -> Click OK

6. Open MS-DOS box by double click on the newly created shortcut.

It’s a good idea to use the debug version of the library for development. So type the following in the prompt:

C:\WINDOWS>set CHECKED=1
C:\WINDOWS>cd c:\scitech
C:\SCITECH>start.bat
Checked debug build enabled.
DJGPP 2.02 32-bit DOS compilation environment set up (DPMI).
C:\SCITECH\examples\mgl>cd c:\scitech\src
C:\SCITECH\src>dmake build

If building process was successful the c:\SCITECH\lib\debug\dos32\dj2\ folder should contain nine libraries:

libgconsole.a
libglut.a
libgm.a
libmgl.a
libmglcpp.a
libmvis.a
libn_ga.a
libpm.a
libtech.a

7. Now you can build MGL samples to check the library:

C:\SCITECH\src>cd ..\examples\mgl\samples
C:\SCITECH\examples\mgl\samples>dmake

Note that it’s better to execute the samples on the real machine and not on the VMware.

8. Prior to run built samples do the following.

Copy (all into one folder) SciTech’s bitmaps, cursors, drivers, fonts and icons folders to your testing machine. Boot in DOS. Assume DJGPP has been installed as well or you have at least cwsdpmi.exe and cp.exe (from UNIX utilities) in the path. Also set the MGL_ROOT environment variable to point to SciTech install folder and the SNAP_PATH one to point where SciTech’s device drivers are located; otherwise you’ll get the error, e.g. “Unable to load SNAP device driver!” or some other fault. For example type in the prompt:

C:\>mkdir scitech
C:\>cd scitech
C:\SCITECH>cp -r d:\tmp\scitech\bitmaps .
C:\SCITECH>cp -r d:\tmp\scitech\cursors .
C:\SCITECH>cp -r d:\tmp\scitech\drivers .
C:\SCITECH>cp -r d:\tmp\scitech\fonts .
C:\SCITECH>cp -r d:\tmp\scitech\icons .
C:\SCITECH>set MGL_ROOT=c:\scitech
C:\SCITECH>set SNAP_PATH=%MGL_ROOT%\drivers\x86
C:\SCITECH>d:\tmp\scitech\samples\palette

Wxwiki wxMGL scr3.jpg

If you execute the samples on Windows 98 and still experience problems please consider the information stated earlier.

  • Install Cygwin. General information and FAQ list can be found on Cygwin official site. You’ll need Cygwin Basic installation. Download stand-alone package from here.

1. Execute cygwinBasic.exe and extract files.

2. Launch setup.exe if it does not start up automatically.

3. Click Next

4. Select Install from Local Directory and click Next

5. Keep the default of C:\cygwin for the Select Root Install Directory.

Keep the default All Users,
Change the Default Text File Type to DOS (If you select UNIX instead of DOS, then you will likely have Cygwin CR/NL problems) and then click Next.

6. Keep the default for Local Package Directory and click Next.

7. Click Next once again to install the packages.

8. Select Create Desktop Icon and Add to Start Menu according to your preferences and then click Finish.

9. Remove the temporary directory with extracted files.

  • Build wxMGL port of wxWidgets. Here is the example of steps to perform:

1. Download wxWidgets-2.8.8.zip from here

2. It is not recommended to have long file names in wxWidgets top build directory path because there can occur some errors when configuring in Cygwin. So the following steps should be fine:

C:\>unzip32 d:\tmp\wxWidgets-2.8.8.zip
C:\>mv wxWidgets-2.8.8 wx288
C:\>cd wx288
C:\wx288>mkdir bldmgld
C:\wx288>cd bldmgld

3. Replace c:\wx288\include\wx\mgl\bitmap.h and c:\wx288\src\mgl\bitmap.cpp with the patched ones.

4. You have to run configure script at first. Type in the prompt:

C:\wx288\bldmgld>set MGL_ROOT=c:\scitech
C:\wx288\bldmgld>c:\cygwin\cygwin
[email protected] ~
$ cd /cygdrive/c/wx288/bldmgld
[email protected] /cygdrive/c/wx288/bldmgld
$ ../configure --with-mgl --enable-universal --with-expat=no --enable-monolithic 
               --enable-optimise --enable-debug --disable-shared --disable-unicode 
               --disable-dynlib --disable-dynamicloader --disable-threads 
               --disable-clipboard --without-libtiff --disable-std_iostreams 
               --disable-stdpaths --disable-printarch --disable-postscript 
               --disable-dependency-tracking --build=i686-pc-msdosdjgpp 
               --host=i686-pc-msdosdjgpp --target=i686-pc-msdosdjgpp

After configuration is done you should see something like this:

Wxwiki wxMGL scr4.jpg

Leave Cygwin session:

[email protected] /cygdrive/c/wx288/bldmgld
$ exit
logout
C:\cygwin\bin>cd c:\wx288\bldmgld
C:\wx288\bldmgld>edit Makefile

Find the string “wx_top_builddir = /cygdrive/c/wx288/bldmgld”, correct it to “wx_top_builddir = /wx288/bldmgld” one, save changes and then run make:

C:\wx288\bldmgld>make

5. If there were no errors you can try to build some of the sample applications:

C:\wx288\bldmgld>cd samples\minimal
C:\wx288\bldmgld\samples\minimal>edit Makefile

Remove “/cygdrive/c” prefix from the wx_top_builddir path, save changes and then run make:

C:\wx288\bldmgld\samples\minimal>make

If you see that make.exe issues the error message after compiling and linking phases check the minimal directory contents. Executable file should have been created anyway. Probably there is still something in Makefile that needs to be corrected.

Now it’s possible to run wxMGL application on the real machine with DOS booted. Assume that SciTech’s MGL runtime is correctly installed on your testing machine. Make sure that the MGL_ROOT and SNAP_PATH environment variables are set and point to the correct locations. You’ll need to copy DPMI server, e.g. CWSDPMI.EXE, somewhere in your path as well. Also if your system has more than 2,5 GB of RAM installed EMM386.EXE may handle XMS incorrectly (this happens, for example, on MS-DOS 7.10). In this case installing QEMM97 may help or load only HIMEM.SYS without using EMM386.EXE. Please note that you have to install DJGPP too in order to be able to inspect call frame backtrace using symify or (even better) gdb in case of crash. See the next section for more details.

Current Status of wxMGL Port in wxWidgets

Unfortunately wxMGL is completely unstable now. So don’t be surprised if the crash does not take long to appear. The reason is that wxMGL is not actively supported any longer (the same is true concerning MGL itself). wxTeam confirmed that fact but also made the remark:

In any case, most of the problems with MGL are probably problems with generic wxUniv code, i.e. also affect wxX11 and wxDFB ports and so may be fixed in the future.”

Targeting Other Platforms

As we mentioned earlier the SciTech Software's MGL API, SciTech's graphics portability layer, supports Windows, Linux, DOS, OS/2, QNX, SMX, RT-Target and other embedded operating systems. Further we’ll discuss how to build wxMGL for some of them.

Building for Linux

In this example we use Linux Mandriva (2.6.22.9-desktop-lmdv) with native GNU C/C++ 4.2.2 compiler installed.

Wxwiki wxMGL scr5.jpg

  • Install SNAP/MGL. Here is the step by step instruction. Please refer to the documentation provided with sources to get more help.

1. Download the following packages from SciTech’s ftp:

snap_sdk_3.1-r23-docs.tar.gz
snap_sdk_3.1-r23-drivers.tar.gz
snap_sdk_3.1-r23-linux.tar.gz
snap_sdk_3.1-r23-pdf.tar.gz
snap_sdk_3.1-r23-src.tar.gz
snap_sdk_3.1-r23-util.tar.gz
mgl_6.0-r23-docs.tar.gz
mgl_6.0-r23-drivers.tar.gz
mgl_6.0-r23-font.tar.gz
mgl_6.0-r23-pdf.tar.gz
mgl_6.0-r23-src.tar.gz
mgl_6.0-r23-ttf1.tar.gz
mgl_6.0-r23-ttf2.tar.gz

2. Unpack obtained packages into the ~/scitech folder.

Preserve the directory structure inside each gzipped file, i.e. don't extract archives each into the separate folders. For example:

$ cd ~
$ mkdir scitech
$ cd scitech
$ tar xzfv /media/cdrom/snap_sdk_3.1-r23-docs.tar.gz
$ tar xzfv /media/cdrom/snap_sdk_3.1-r23-drivers.tar.gz
$ tar xzfv /media/cdrom/snap_sdk_3.1-r23-linux.tar.gz
$ tar xzfv /media/cdrom/snap_sdk_3.1-r23-pdf.tar.gz
$ tar xzfv /media/cdrom/snap_sdk_3.1-r23-src.tar.gz
$ tar xzfv /media/cdrom/snap_sdk_3.1-r23-util.tar.gz
$ tar xzfv /media/cdrom/mgl_6.0-r23-docs.tar.gz
$ tar xzfv /media/cdrom/mgl_6.0-r23-drivers.tar.gz
$ tar xzfv /media/cdrom/mgl_6.0-r23-font.tar.gz
$ tar xzfv /media/cdrom/mgl_6.0-r23-pdf.tar.gz
$ tar xzfv /media/cdrom/mgl_6.0-r23-src.tar.gz
$ tar xzfv /media/cdrom/mgl_6.0-r23-ttf1.tar.gz
$ tar xzfv /media/cdrom/mgl_6.0-r23-ttf2.tar.gz

3. If you use gcc/gpp newer than 3.2.3 (e.g. 4.2.2 or higher) apply the patches to the ~/scitech/include/tcl/array.hpp and ~/scitech/include/tcl/hashtab.hpp headers.

Also ensure that you have backward directory containing such headers as

algo.h   list.h
algobase.h   map.h
alloc.h   multimap.h
backward_warning.h   multiset.h
bvector.h   new.h
complex.h   ostream.h
defalloc.h   pair.h
deque.h   queue.h
fstream.h   rope.h
function.h   set.h
hashtable.h   slist.h
hash_map.h   stack.h
hash_set.h   stream.h
heap.h   streambuf.h
iomanip.h   strstream
iostream.h   tempbuf.h
istream.h   tree.h
iterator.h                        vector.h

in gcc/gpp include search path since SciTech’s sources depend on some of these old headers. You can find them for example in gcc-4.2.2/libstdc++-v3/include/backward directory contained in gcc-g++-4.2.2.tar.bz2 which is available from here or from one of the GNU mirrors.

4. Set permissions, configure the environment and build the library:

$ chmod –R 777 ../scitech
$ export CHECKED=1
$ . ./start.linux
Checked debug build enabled.
GCC Linux compilation environment set up (x86)
$ cd ~/scitech/src
$ dmake build

If building process was successful the ~/scitech/lib/debug/linux/gcc/x86/a and ~/scitech/lib/debug/linux/gcc/x86/so folders should contain the following libraries:
libgconsole.a
libglut.a
libgm.a
libmgl.a
libmglcpp.a
libmvis.a
libn_ga.a
libpm.a
libtech.a
libpm.so.5.0.0

5. It’s a good idea to build and run SciTech’s MGL samples to ensure that we have working library and drivers:

$ cd ~/scitech/examples/mgl/samples
$ dmake 

Prior to run the samples you have to switch user to root. Also check that MGL_ROOT (SciTech’s install directory), SNAP_PATH (Scitech’s device drivers) and LD_LIBRARY_PATH (shared libraries search path) environment variables are set correctly.

$ su root
# export MGL_ROOT=/home/wx/scitech
# export SNAP_PATH=$MGL_ROOT/drivers/x86
# export LD_LIBRARY_PATH=$MGL_ROOT/lib/debug/linux/gcc/x86/so:$LD_LIBRARY_PATH
# export PATH=$MGL_ROOT/examples/mgl/samples:$PATH
# stretch.exe

Wxwiki wxMGL scr6.jpg

  • Build wxMGL port of wxWidgets. Here is the example of steps to perform:

1. Download wxWidgets-2.8.8.tar.gz from here

2. Unpack and create the directory for wxMGL debug build:

$ cd ~ 
$ tar xzfv /media/cdrom/wxWidgets-2.8.8.tar.gz
$ cd wxWidgets-2.8.8
$ chmod -R 777 ../wxWidgets-2.8.8
$ mkdir buildmgld
$ cd buildmgld

3. Replace wxWidgets-2.8.8/include/wx/mgl/bitmap.h and wxWidgets-2.8.8/src/mgl/bitmap.cpp with the patched ones.

4. In the wxWidgets-2.8.8/src/mgl/utils.cpp comment the definition of wxGetFreeMemory() function because it is already defined in the wxWidgets-2.8.8/src/unix/utilsunx.cpp

5. Set MGL_ROOT environment variable and run configure. For example:

$ export MGL_ROOT=~/scitech
$ ../configure --with-mgl --enable-universal --enable-debug --enable-monolithic --disable-shared 
  --build=i586-mandriva-linux-gnu --host=i586-mandriva-linux-gnu --target=i586-mandriva-linux-gnu

6. After configuration is done run make and optionally make install (with root privileges):

$ make
$ su root
# make install
# exit

7. Now you can build the sample application:

$ cd ~/wxWidgets-2.8.8/buildmgld/samples/minimal
$ make

Prior to run the sample switch user to root and make sure that MGL_ROOT and SNAP_PATH environment variables are set correctly:

$ su root
# export MGL_ROOT=/home/wx/scitech
# export SNAP_PATH=$MGL_ROOT/drivers/x86
# export PATH=/home/wx/wxWidgets-2.8.8/buildmgld/samples/minimal:$PATH
# minimal

References

  1. Cygwin official site
  2. DJ Delorie's Web server
  3. SciTech's MGL home page
  4. Unix Linux Forums - DOS and 4GB of RAM
  5. VMware official site
  6. wxWidgets home page