Building From Source

wx.NET is available as a file distribution (cf.

Components Of The File Distribution) or via CVS from http://www.sourceforge.net/projects/wxnet. If you received a branch of the source code by CVS or you are not satidfied by the compiled binaries in the file distribution, you will have to compile the project binaries from source.

Overview

Building wx.NET is a four-step process:
  1. Install the .NET framework or the mono system (Installing the .NET framework or equivalents).
  2. Install one of the supported C/C++ compilers and linkers (Install one of the supported C/C++ development systems).
  3. Configure, compile, and install core wxWidgets and any optional contrib libraries (Building wxWidgets).
  4. Configure and compile wx.NET.

All of this can get a bit tedious if done by hand, especially since both wxWidgets and wx.NET are fairly configurable and have multiple build steps themselves.

So we've developed this documentation and a "wrapper" build system to make life easier for newbies and advanced users alike. The build system lives under the Build directory. This system is totally optional: if you like you can configure/compile/install wxWidgets on your own and also configure/compile wx.NET directly using GnuMake programs.

This manual will focus on Windows platforms and Linux. wx.NET can run on MaxOs X but since I do not have any experiences with this platform, I cannot support it. However, all version up to 0.8.0 have also been compiled for Macs.

Installing the .NET framework or equivalents

Windows

On Windows you have the choice among two supported implementations of the .NET framework: Microsoft's original implementation ("http://msdn.microsoft.com/netframework/") and the mono project (http://www.go-mono.com/). Previous versions also supported the PNET / DotGnu (http://www.gnu.org/projects/dotgnu/) implementation. The use of this implementation is no longer supported.

The Windows implementation is typically already a part of the operating system. However, installation packages are available from the web. Please be sure to have at least version .NET 2.0 installed, since wx.NET uses generics.

Both systems are available as installation programs or MSI packages and you should use these packages since the wx.Net.Build (Use of the wx.BuildSystem system) system uses registry entries to determine the directories, that contain the "mono" programs (the registry folder HKLM/Software/Novel/Mono should contain valid entries).

If you plan to use the solution files and VS project files, you should install either the free Visual Studio Express Edition (http://msdn.microsoft.com/vstudio/express), or one of the Visual Studio products that you have to pay for, or monodevelop, the development environment of the mono project.

Linux

The number of alternatives for Linux is somehow limited: You have the opportunity to go mono. Most Linux distributions offer precompiled packages. However, these packages usually do not provide the most current version.

Alternatively, you may get a source code release from the web site of the project and compile it.

In any case: The mono interpreter mono and the compiler gmcs shall be in the path of directly executable programs (PATH variable).

Install one of the supported C/C++ development systems

Windows

I tested two development frameworks for the C/C++ code of library wx-c.dll: Microsoft's platform SDK v6.1 (available for free from http://www.microsoft.com/ and the MinGW port of the GCC compiler on Windows (http://www.mingw.org/). If you plan to use the make files, you also have to MSys package - the minimal make system - also from the MinGW site. If you plan to use the wx-c.sln solution file, you have to get the VC Express Edition from http://msdn.microsoft.com/vstudio/express.

Please use the official installation packages. The wx.Net.Build system will use registry entries to find out the place where Microsoft's platform SDK has been installed. The wx.Net.Build system will expect MinGW to reside at C:/MinGW/bin. However, you can change this assumption assigning a path to environment variable GCC_BINPATH (Use of the wx.BuildSystem system).

Linux

All means to build wx.NET that are part of this package referring to Linux use the GNU C/C++ compiler GCC. GCC is part of all Linux distributions and must be in the path of executable programs (the PATH variabel).

Building wxWidgets

The current distribution of wx.NET uses the current productive version of wxWidgets: 2.8. You also have to build the STC (styled text control) library in the contrib directory. The current code base does not compile with version 2.9 - the future 3.0 release of wxWidgets that currently is under development.

Please do not forget to have a look at the wx/setup.h file. Make sure, that wxUSE_UNICODE is defined if you use Unicode string encoding (which I strongly recommend).

Windows

wxWidgets comes with several means to build the libraries. I use the make files makefile.vc (the Visual Studio Compiler) and makefile.gcc (the MinGW GCC compiler and the MSys system) in the build subdirectory of the project. You have to edit the configuration files config.vc and config.gcc respectively. However, you definitely should consult wxWidgets' documentation on building the system before you decide how to do this.

In config.gcc, I only have to care about variable BUILD to choose among release and debug mode, since I install MinGW in the standard directory C: . Additionally, you should assign 1 to variable UNICODE. Everything interfacing the .NET Framework should support unicode. Then, you have to call a port of GNU make (e.g. the mingw32-make.exe program).

c:/wxWidgets-2.6.11/build/msw> /MinGW/mingw32-make.exe -f makefile.gcc

In config.vc I acivate UNICODE and use of USE_GDIPLUS. Then, you have to start the "CMD shell" optimized for using the platform edition. Call Microsoft's make-tool nmake:

c:/wxWidgets-2.6.11/build/msw> nmake.exe -f makefile.vc

Please do not forget to execute also the Make-scripts in contrib that build the STC library.

The wx.Net.Build system will expect wxWidgets to reside in the standard folders C:/wxWidgets-2.8.10 or C:/wxWidgets-2.8.11. You may override this assigning a path to environment variable WXWIN.

Linux

Building wxWidgets under Linux is quite easy. Unzip the wxGTK source distribution, change directory to the root directory of this ditribution and call
> ./configure --enable-unicode
> make
> sudo make install
Change to contrib/src/stc. Again run
> make
> sudo make install
The commands introduced by sudo require root priviliges. If you are not a sudoer, you may also use su to create a root shell and then call make install.

Finally, I only have to report problems using version 2.8.10 in release mode on a 64 bit architecture. Version 2.8.11 works fine on my machines.

Use of the wx.BuildSystem system

The wx.BuildSystem consists of .NET wrappers for build tools like compilers and linkers and of project definitions that define the libraries and programs that shall be built. The programs and libraries of the wx.NET project are defined in program wx.Net.Build.exe. This program uses the generic part of the build system implemented in assembly wx.BuildSystem.dll. The program works for Windows and Linux.

You have to use the command shell:

> wx.Net.Build.exe /log:wxnetbuild

The build program will try to find all supported build tools that you have installed on your machine. Then, the system will create a schedule based on the available build tools. Finally, this schedule will be executed. The abovementioned command line tells the build system to produce a lig file wxnetbuild.log in XML syntax. This is an option. If more than one tool is available to build a particular target and the first tool fails, the build program will automatically try the next available tool. The tools will be recognized correctly if installed following the advices from the section Install one of the supported C/C++ development systems and Installing the .NET framework or equivalents.

On Windows, the build program will try the VC Express and Microsoft Platform SDK tools first before using the MinGW tools - if both tools are available. Analogously, the MS .NET framework will be used used before starting Mono. You can override this using options +MONO or +GNU to prefer the Mono tools and/or the GNU tools. On Linux, the system supports only GNU GCC and Mono.

Further informtations on options are available with

> wx.Net.Build.exe /help

The build program may fail to identify the available tools if you did not use the standard procedure for installation or you use tool sets like Visual Standard Edition or Visual Professional Edition that have not been tested. This description only covers tools that are available for free. You may also want to build the system on a not directly supported OS. For instance, wxWidgets supports native Mac OS X controls - however, I do not own a Mac, thus the build system does not support this platform.

If you experience any problems with the automatic build system, you have the option to use the BOO scripts for build wx.NET following the instructions from Using BOO scripts to build. Two scripts are part of the file distribution: wx.Net.Build.Windows.boo to build on Windows and wx.Net.Build.Linux.boo to build on Linux machines. However, you may create your own BOO script using the build system that refers to all tools that are installed on your system.

> wx.Net.Build.exe /boo:MyBuildScript.boo

A final remark on the support for building file releases: As pointed out in Components Of The File Distribution, the native DLLs or ELF libraries contain version information in their file name. This means, that all references to the DLLs in the .NET assembly wx.NET.dll must be changed - they have to load function from - let's say - wx-c-0-9-0-1.dll instead from wx-c.dll. The build program wx.Net.Build.exe supports these operations since the program contains a build project for building file distributions. However, you have to provide a version number in order to make this work. Assign a string like "0.9.0.1" to environment variable BUILD_VERSION before starting the build program or start the build program in the following way to create a file distribution:

> wx.Net.Build.exe /set:BUILD_VERSION=0.9.0.1
This will build all projects defined on the original sources and all libraries and programs on modified sources, that are part of the file release 0.9.0.1. You can find the latter programs in sub directory WXNET_TOP/Bin/release-0-9-0-1.

Using BOO scripts to build

wx.NET comes with 2 BOO scripts to build libraries, assembles, and sample programs: wx.Net.Build.Windows.boo to build on Windows and wx.Net.Build.Linux.boo to build on Linux machines. As mentioned in Use of the wx.BuildSystem system, you can also create these files on your own. The purpose of these scripts is to provide you with means to configure the build process at your will. Therefore, the code is organized in a form that makes changes to the code as easy s possible. The generated code falls into sections as follows (but you will have to edit most probably only the first section).

The declaration section

This sections contains the declaration of BOO variables for options and file names. This is the section that users of the build system will edit to adopt the build system to specific needs.

This section contains several subsections. the first section will import some required namespaces and declare features of some projects. Features define symbols that are used for conditional compilation. The features here define optional parts of the wx.NET system: The styled text control (STC) and the interface to the display:

# BOO script to build the wx.Buildsystem projects from assembly
# wx.Net.Build, Version=0.9.0.0, Culture=neutral, PublicKeyToken=c5f483f7e93d2714.
# This program has been generated automatically by the wx.BuildSystem
# (c) 2010 Harald Meyer auf'm Hofe.
#
# The following lines will declare variables to configure the tools
# that are used to build the system. You may change these declarations
# if you know what you are doing.
import System.Text
import System.IO
import System.Diagnostics
# Features of project wx.NET: The managed part of the wx.NET implementation.
Features_wx_NET=[]
Features_wx_NET.Add("WXNET_DISPLAY") # Display Access: Enables class wx.Display
Features_wx_NET.Add("WXNET_STYLEDTEXTCTRL") # Styled Text Control: Enables namespace wx.StyledText

In the following, the base path will be defined, that will be used to complete all local paths in the build program. Additionally, the build mode (rebuild or reuse of existing build results) and the target directory containing all internal build projects will be declared here.

# This is the root path of the project.
wxNetBase='c:\\sf\\wx.NET\\Bin'
System.IO.Directory.SetCurrentDirectory(wxNetBase)
#
# If true, then any target will be rebuild. If false, many build actions
# will only rebuild targets if prerequisites are newer.
Rebuild=false
#
# This is the directory containing all non-target files that will be created on building the targets.
BuildDir='Build\\Debug'

The following sections will provide definitions of files and options for each avaiable tool. The following listing presents the section defining options for the CSC.EXE C# compiler of Microsoft's .NET framework.

#################################################################
# These are the declarations of tool csc.exe of family MSNET:
# c:\WINDOWS\Microsoft.NET\Framework\v3.5\csc.exe: The C# compiler of the MS .NET framework.
# This variable is the path to the CSC compiler that will be used.
MS_CSC="c:\\WINDOWS\\Microsoft.NET\\Framework\\v3.5\\csc.exe"
# This option defines whether to compile with debug information or not
MS_CSC_OPTIONS='/debug'
# This option turns on optimization
#MS_CSC_OPTIONS+=' /optimize'
# This option defines the warning level
MS_CSC_OPTIONS+=' /warn:3'
MS_CSC_OPTIONS+=' /fullpaths'
#MS_CSC_OPTIONS+=' /warnaserror' # treats warnings as errors
MS_CSC_OPTIONS+=' /define:__MS_CSC__' # identifies the compiler
MS_CSC_OPTIONS+=' /define:TRACE' # enables trace log
#################################################################

The final section defines so-called choice points. Since the build program uses all available build tools, there may be alternative paths to achieve certain targets. The workstation that created this BOO program has been fully equipped with VC Express and GNU MinGW to build C/C++ subsystems, VS Express and MONO to build C# subsystems. Thus, the user of the build system has the choice. The following choice points enable the user to make this choice.

#########################################################
# This section contains choice points- BOO variables that
# control which tools will be used. Assign one of the
# listed values to the choice points in order to select
# a particular tool. If this tool is not available, the
# program will automatically use an alternative.
CppDevelopmentSystem = "MS VC" # "MS VC" "GNU"
CSHARP_COMPILER = "csc.exe" # "csc.exe" "gmcs" "CSharpCodeProvider"

The section defining the build programs

The next section implements the wrapper functions that will be called to run the build tools. Users of the build system are not required to know them. However, the following sections shows the function calling the CSC.EXE compiler for all those that like to know how things work.

#########################################################
# The section containing declarations ends here.
# Please refrain from changing the code from this position on.
# The code below will provide definitions of build functions and
# will use this functions afterwards to produce the build targets.
# However, you may want to disable build tools here by replacing
# the body of the corrsponding function with "pass".
def TestForRebuild(targetFile as  string, *sourceFiles as (object)):
        if Rebuild: return true
        if not System.IO.File.Exists(targetFile): return true
        dTarget=System.IO.File.GetLastWriteTime(targetFile)
        inlinedSources=[]
        for sourceFile in sourceFiles:
                if sourceFile == null: continue
                if sourceFile isa System.Array:
                        for containedSource in cast(System.Array, sourceFile):
                                inlinedSources.Add(containedSource)
                else:
                        inlinedSources.Add(sourceFile)
        for inlinedSource in inlinedSources:
                dSource=System.IO.File.GetLastWriteTime(inlinedSource)
                if dTarget < dSource: return true
        return false
#
# These are the definitions of tool csc.exe of family MSNET:
# c:\WINDOWS\Microsoft.NET\Framework\v3.5\csc.exe: The C# compiler of the MS .NET framework.
def RunMsCsc(targettype as string, target as string, w32icon as string, signature as string, mainclass as string, references as (string), sources as (string), features):
        if not TestForRebuild(target, w32icon, signature, references, sources):
                print target,"is up to date"
                return
        print "MS csc.exe creates", target
        args=StreamWriter("${BuildDir}\\plain\\csc.txt")
        args.Write("/out:${target} /target:${targettype}")
        for feature in features:
                if feature=="X32":
                        args.Write(' /platform:x86')
                elif feature=="X64":
                        args.Write(' /platform:x64')
                else:
                        args.Write(' /define:')
                        args.Write(feature)
        for reference in references:
                args.Write(" /reference:\"${reference}\"")
        if signature != null:
                args.Write(" /keyfile:\"${signature}\"")
        if w32icon != null:
                args.Write(" /win32icon:\"${w32icon}\"")
        if mainclass != null:
                args.Write(" /main:${mainclass}")
        args.Write(' ')
        args.Write(MS_CSC_OPTIONS)
        for source in sources:
                args.Write(" \"${source}\"")
        args.Close()
        startinfo=System.Diagnostics.ProcessStartInfo()
        startinfo.FileName=MS_CSC
        startinfo.Arguments="@${BuildDir}\\plain\\csc.txt"
        startinfo.UseShellExecute=false
        p=System.Diagnostics.Process.Start(startinfo)
        p.WaitForExit()
        if p.ExitCode!=0:
                raise System.Exception("Build action failed.")

The section actually building the desired targets

The final section uses the wrapper functions defined in the previous section to actually build the build targets.

This is the code producing the controls.exe programm.

if CSHARP_COMPILER == "gmcs":
        print 'Executing gmcs'
        RunMonoGmcs("winexe", "${wxNetBase}\\controls.exe", ("../Samples/Controls\\Controls.cs", ), ("System.dll", "System.Drawing.dll", "${wxNetBase}\\wx.NET.dll", ), "c:\\sf\\wx.NET\\Src\\wx.NET\\mondrian.ico", "c:\\sf\\wx.NET\\Src\\wx.NET\\keys.snk", null, [])
elif CSHARP_COMPILER == "CSharpCodeProvider":
        print 'Executing CSharpCodeProvider'
        print "Caught exception creating code for action CSharpCodeProvider."
        print "BOO code creation is not supported by action wx.Build.Net.CSharpCodeProvider."
else: # CSHARP_COMPILER == "csc.exe"
        print 'Executing csc.exe'
        RunMsCsc('winexe', "${wxNetBase}\\controls.exe", "c:\\sf\\wx.NET\\Src\\wx.NET\\mondrian.ico", "c:\\sf\\wx.NET\\Src\\wx.NET\\keys.snk", null, ("System.dll", "System.Drawing.dll", "${wxNetBase}\\wx.NET.dll"), ("../Samples/Controls\\Controls.cs",), [])

Using Solution Files To Build wx.NET

wx.NET comes with 2 solution files wx-c.sln and wx.NET.sln in directory WXNET_TOP . The first one builds the wx-c.dll using the MS VC Express Edition (or Standard or Professional Editions). The latter builds the wx.NET.dll assembly and all sample programs and can eb used with either VS Net Express Edition or MonoDevelop. These files are also useful to run debuggers - in order to have a look inside.

Premake Overview

Previous releases suggested the use of the premake meta-make system. wx.NET is still shipped with the premake program files but these files are no longer maintained and may not be up to date.

Premake is a program to create configuration files for multiple build systems from a single platform-independent configuration file. In our case, Makefiles for systems with a UN*X-like shell environment (Linux, MacOS X) and Visual Studio.NET 2005 (VS.NET) solution/project files for Microsoft Windows.

Premake configuration files are named premake.lua and can be found throughout the source tree. We've included pre-built premake binaries for Linux, Mac, and Windows in the build system. You don't have to compile Premake or even know how it works unless you want to bypass the build system.

More information about wx.NET's Premake configuration files can be found in the Premake appendix. Detailed Build Instructions

Premake Appendix

Premake configuration files are written in the Lua scripting language, hence the .lua extension on each file. Under the top of the source tree you'll find the following:
premake.lua Builds the wx-c C++ wrapper library and the wx.NET.dll assembly
Src/wx-c/premake.lua, Src/wx-c/premake-funcs.lua Builds the wx-c wrapper
Src/wx.NET/premake.lua Builds wx.NET.dll
Utils/premake.lua Builds all utilities
Utils/ * /Src/premake.lua There are premake files for each utility
Samples/premake.lua Builds all samples
Samples/ * /premake.lua There are premake files for each sample

Manual Use of Premake

If you need to edit the Premake configuration files or experiment with Premake, you'll probably want to make sure the premake binary is in your PATH. Using the pre-built premake binaries bundled with the wx.NET source is a safe option: On my Linux build system I've created a symlink in /usr/local/bin:

$ ln -s /usr/local/src/wx.NET-CVS/wx.NET/Build/Linux/premake /usr/local/bin

Remember that this is not necessary to use the build system.

Premake has a number of options which control what type of build file(s) are created, what compiler to use, etc. In addition, Premake configuration files can accept their own custom options. This is used extensively by the wx.NET.dll and wx-c premake files. To see a list of both standard and custom options just type:

$ premake --help

The most important options are --target, which is used to specify the type of project build files to create:

$ premake [ options ] --target xxx

The standard set of options for Premake 2.0 Beta 6 follow:

Premake 3.2, a build script generator
Copyright (C) 2002-2006 Jason Perkins and the Premake Project
Lua 5.0.3 Copyright (C) 1994-2006 Tecgraf, PUC-Rio

 --file name       Process the specified premake script file

 --clean           Remove all binaries and build scripts
 --verbose       Generate verbose makefiles (where applicable)

 --cc name         Choose a C/C++ compiler, if supported by target; one of:
      gcc       GNU gcc compiler
      dmc       Digital Mars C/C+ compiler (experimental)

 --dotnet name     Choose a .NET compiler set, if supported by target; one of:
      ms        Microsoft (csc)
      mono      Mono (mcs)
      mono2     Mono .NET 2.0 (gmcs)
      pnet      Portable.NET (cscc)

 --os name         Generate files for different operating system; one of:
      bsd       OpenBSD, NetBSD, or FreeBSD
      linux     Linux
      macosx    MacOS X
      windows   Microsoft Windows

 --target name     Generate input files for the specified toolset; one of:
      cb-gcc    Code::Blocks Studio with GCC
      gnu       GNU Makefile for POSIX, MinGW, and Cygwin
      monodev   MonoDevelop
      sharpdev  ICSharpCode SharpDevelop
      vs6       Microsoft Visual Studio 6
      vs2002    Microsoft Visual Studio 2002
      vs2003    Microsoft Visual Studio 2003
      vs2005    Microsoft Visual Studio 2005 (includes Express editions)

 --help            Display this information
 --version         Display version information

Manual of the wx.NET   (c) 2003-2011 the wx.NET project at   Get wx.NET at SourceForge.net. Fast, secure and Free Open Source software downloads