Building From Source

Overview

Building wx.NET is a two-step process:

1. Configure, compile, and install core wxWidgets and any optional contrib libraries
2. 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, with directories for various supported platforms. 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 the premake system.

Note that on Windows the wrapper is less functional due to lack of UN*X shell scripting tools.

Premake Overview

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

Linux

Introduction

In this document I'll use WXNET_TOP to refer to the top-level wx.NET module directory; for example, /usr/local/src/wx.NET-CVS/wx.NET. The build system lives under WXNET_TOP/Build/Linux.

Install your .NET Package(s)

There are two open source .NET runtimes and development environments available:

• Mono - http://www.go-mono.com/
• DotGNU Portable.NET (aka PNET) - http://www.gnu.org/projects/dotgnu/

Mono is recommended on Linux. It is probably easiest to install a Mono RPM for your Linux distribution.

Please note, the premake does not support PNET correctly. Refer to the remarks below on using PNET. PNET also is special referring to the internally used character encoding. While Microsoft .NET follows Windows standard and uses UTF16 for internal string encoding and Mono follows Microsoft .NET standard, PNET relies to the common practice in the JAVA and Linux area and uses typically UTF8.

Acquire wxWidgets Source

As of this writing, wx.NET requires version 2.6.x of wxWidgets. There are a variety of ways you can build and install wxWidgets.

• Download release 2.6.x from http://www.wxwidgets.org/dl_gtk.htm#dev
• Untar the file wxGTK-2.6.x.tar.gz somewhere, where x is a minor release revision number such as 4.

Configure the Build

Inside of the WXNET_TOP/Build/Linux directory copy Defs.in.template to Defs.in. Open Defs.in in an editor. Defs.in is a mini-Makefile that contains a few definitions that drive the build process. It should be well documented so I won't discuss the various defines here.

You must change:

• WXW_SOURCE_DIR
• WXW_INSTALL_DIR

And you should probably review:

• WXNET_INSTALL_DIR
• DOTNET

The default for WXW_CONFIG and WXNET_CONFIG is probably good for now.

Build wxWidgets

Inside of a shell do the following:

$ cd WXNET_TOP/Build/Linux
$ make wxw

This will:

• Configure wxWidgets via it's configure script
• Build the wxWidgets core libraries and one contrib library (STC)
• Install the libraries and header files to WXW_INSTALL_DIR

The wxw build is actually broken into steps. To see a list of sub-builds you can perform, you can type make without any arguments:

$ make 

You can find the list of commands here.

The wxw target does not build the wxWidgets samples. If this is your first time using wxWidgets/wx.NET, I suggest building these as well:

$ make wxw-samples

Please see the samples section for details about the wxWidgets samples.

Build wx.NET

Inside of a shell do the following:

$ cd WXNET_TOP/Build/Linux
$ make wxnet

This will:

• Configure the build by running premake in various directories
• Build the wxWidgets C++ wrapper library, libwx-c.so
• Build the wx.NET .NET assembly, wx.NET.dll
• Build the wx.NET samples
• Build the wx.NET utilities

Upon successful build libraries and assemblies are all placed in a common "bin" folder, WXNET_TOP/Bin.

You can also "install" wx.NET to another directory on your Linux box. This is a great way to archive different builds of wx.NET or test on another host. The install will be done to the directory defined by WXNET_INSTALL_DIR, which should be something like /usr/local/wxnet or /wxnet-0.8.3. Just don't use something like /usr or /usr/local.

To start the install type:

$ make wxnet-install

See Install Package for a description of what gets installed. And note that the install step is optional. You do not have to do it to run the samples or even develop using wx.NET.

Using PNET

PNET is special in two aspects:

• PNET uses standard GCC options instead of calling conventions borrowed from Microsoft's .NET compiler.
• PNET uses UTF8 instead of UTF16 for internal string encodings.

The build procedure for wx-c is exactly the same as for mono, but wx.NET.dll will be made differently. Assuming, that you are currently in the main directory of the project, change directory to the ./Src/wx.NET and run the cscc.exe compiler directly:

>cscc -DWXNET_INTERNAL_USE_UTF8 -DWXNET_DISPLAY -DWXNET_STYLEDTEXTCTRL\
 -lSystem.dll -lSystem.Drawing -shared -o ../../Bin/wx.PNet.dll\
 *.cs 

You will have to compile and link the samples accordingly. Example: The help viewer in ./Utils/HelpView.

>cscc -DWXNET_INTERNAL_USE_UTF8 -DWXNET_DISPLAY -DWXNET_STYLEDTEXTCTRL\
 -lSystem.dll -lSystem.Drawing -L../../Bin -l wx.NET -o ../../Bin/helpview.exe\
 *.cs 

Try Out the Samples

Run the Sample-Launcher.sh shell script from the top-level source or install folder. This will start a sample browser using the .NET runtime you defined in Defs.in. Please review the Samples section for a list of any outstanding bugs or issues.

You can also launch samples directly via the wxnet-run script:

$ cd WXNET_TOP/Bin
$ ./wxnet-run sample.exe

Please review the Samples section for a list of any outstanding bugs or issues.

Linux

Linux

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:

• Build/Linux/premake
• Build/MacOSX/premake
• Build/Windows/premake.exe

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

---