[wxWidgets.git] / install / unix / INSTALL

* General
----------

The Unix variants of wxWindows use GNU configure. If you have problems 
with your make use GNU make instead.

Read my homepage at 

  http://www.freiburg.linux.de/~wxxt
  
for newest information.

* GUI libraries
-----------------------

wxWindows requires a GUI toolkit to be installed. Does that make
sense? So far only the GTK is supported, but we hope to provide
the choice between GTK, Qt, Motif/Lesstif in the not so distant 
future.

You can get the newest version of the GTK from the GTK homepage
at
  http://www.gtk.org
  
The newest versin of Qt can be downloaded for free from the Trolltec's 
site at
  http://www.troll.no

Lesstif can be downloaded from their site
at
  http://www.lesstif.org

If you want to develop using Motif, you need to buy it, unless it comes
with your operating system such as all commercial Unices, as well as
RedHat's, SuSe's and probably other's Linux Motif editions.

* Additional libraries
-----------------------

There will be a few more features of wxWindows, which will 
require further libraries (on some platforms). These
features will be optional. I hope to teach configure
to check that out automatically.

Thread support:

  Requires pthreads under Linux with glibc 2. pthreads are
  always present on such systems, so just compile, unless
  you have RedHat 5.0, which has a broken combination of
  glibc 2 and X. In this case, you have to run configure
  with "--without-threads".
  
  Requires PCthreads under Linux with libc 5. If you
  haven't installed pcthreads, there will be no thread
  support in wxWindows, but the library will compile.
  
  Requires Posix threads on commercial Unix system,
  which are always present. Just compile.
  
  On SGI Irix we first look for sprocs, then pthreads and
  use the last one found.
  
Python scripting language support:

  Requires Python. Soon to come.
  
* Other things to do
-----------------------------

wxGTK and wxMotif/wxLesstif require the built-in
ImLib/GdkImlib to be configured. For that purpose
copy the two files from /misc/imlib to your
home directory and rename "imrc" -> ".imrc".
You may also edit imrc by hand as you like. 
The palette file is required when using
wxWindows in 256-colour mode.

If you want to use wxWindows's ODBC support, you'll have
to create a .odbc.ini file. The readme file in 
~/src/iodbc tells you what to do.


* Create your configuration
-----------------------------

This must be done in /install/unix

Usage:
	./configure options

If you want to use system's C and C++ compiler,
set environment variables CC and CCC as

	% setenv CC cc
	% setenv CCC CC
	% ./configure options

Using the SGI native compilers, it is recommended that you
also set CFLAGS and CXXFLAGS before running configure. These 
should be set to :

CFLAGS="-mips3 -n32" 
CXXFLAGS="-mips3 -n32"

This is essential if you want to use the resultant binaries 
on any other machine than the one it was compiled on. If you 
have a 64bit machine (Octane) you should also do this to ensure 
you don't accidently build the libraries as 64bit (which is 
untested).

The SGI native compiler support has only been tested on Irix 6.5.

to see all the options please use:

	./configure --help

The basic philosophy is that if you want to use different
configurations, like a debug and a release version, 
or use the same source tree on different systems,
you have only to change the environment variable OSTYPE.
(Sadly this variable is not set by default on some systems
in some shells - on SGI's for example). So you will have to 
set it there. This variable HAS to be set before starting 
configure, so that it knows which system it tries to 
configure for.

Configure will complain if the system variable OSTYPE has 
not been defined. And Make in some circumstances as well...


* General options
-------------------

Obviously, you have to choose a toolkit. You must do this by
running configure with either of

        --with-gtk               Use the GIMP ToolKit (GTK)
	
	--with-qt                Use Qt from TrollTec
	
	--with-motif             Use either Motif or Lesstif
	                         Configure will look for both. 

The following options handle the kind of library you want to build.

	--without-threads       Compile without thread support.

	--with-shared           Create shared libraries.

	--without-optimise	Do not optimise the code.

	--with-profile          Add profiling info to the object 
				files. Currently broken, I think.
				
	--with-mem_tracing      Add built-in memory tracing. 
	                        This doesn't work well with gcc.
				
	--with-dmalloc          Use the dmalloc memory debugger.
	                        Read more at www.letters.com/dmalloc/
				
	--with-debug_info	Add debug info to object files and
	                        executables.

	--with-debug_flag	Define __DEBUG__ and __WXDEBUG__ when
	                        compiling.

* Feature Options
-------------------

When using the Windows version of wxWindows, it is possible
to edit the file /include/wx/msw/setup.h in order to enable
or disable some features of wxWindows so that the resulting
binaries get smaller.

As I don't yet care for binary size and target mainly at
producing a shared library, wxWindows's configure system auto-
matically enables all features, as long as they are already
implemented.

* Compiling
-------------

The following must be done in the base directory (e.g. ~/wxGTK
or ~/wxWin)

First you have to create all makefiles in all subdirectories:

	make Makefiles

Dependencies are generated automatically using

	make depend
	
(For some reason, this doesn't seem to work completely.)

Now the makefiles are created you can compile everything is as simple
as typing:

	make

make yourself some coffee, as it will try to compile
ALL the files in this distribution.

if you want to be more selective:

	make src	will build only the base libraries
	make utils	will build the utils
	make samples	will build the samples
	make other	will build the other samples
	make user	will build the files in the directory other

Depending on the configuration of some files, the libraries
and binaries will be placed in different directories.
The "global" binaries and libraries will be placed in:

	bin/$(OSTYPE) and
	lib/$(OSTYPE) respectively

"local" binaries and libraries will be placed in:

	(basedir of that application)/$(OSTYPE).

This is also the place where all the object-files will go.

If you want to conserve disk space by removing unnecessary
object-files:

	 make clean_obj

will do the work for you.

* Creating a new Project
--------------------------

I propose to put all contributed programs in the directory
"~/wxWin/user", with a directory of its own.

This directory then should include the following files:

Makefile        (You can copy this one from any application in samples
                 probably you will not need to edit this one. There is
                 only one case where you might be interested in changing
                 this file, but about that see later.)
Makefile.in	(This is the base application-Makefile template, from
                 which the actual Makefile for each system is created.
                 More about this later)

put ALL your source code along with all the other stuff you need for
your application in this directory (subdirectories are welcome).

** Something about Makefiles
------------------------------

On general principle it should only contain ONE line, which is as follows:

	include ../../src/unix/setup/general/makeapp

this will include all the necessary definitions for creating the applications

the only case where you might want to add another line is the following:
this version of configure also supports creation of source archives of the
application for easy distribution and updates to newer version of wxWindows.
    For this purpose all files in the application-directory will be put into
a gziped tar-file in the full notation user/<your application>/*
if you want to include some other files that you want "more visible", like
a README.<yourApp> or a shell script for easy 
compilation/installation/distribution, then you have to add a variable

	DISTRIBUTE_ADDITIONAL=<your files>

to the Makefile.
So it would look like this:

	DISTRIBUTE_ADDITIONAL=README.TheApp
	include ../../src/unix/setup/general/makeapp

As we have already talked about distribution the command to create a 
distribution is:

	make distrib

NOTE: If you are in the base directory of wxWindows it will create 
distribution packages for wxWindows as well as for all packages in the
user directory.
    So if you want to create only packages for the files in user,
then go to the directory other and type:

	make distrib

or if you only want one application to be created then
enter the specific directory and type there:
make distrib

All the distribution files will be put in the directory
distrib at the base of the wxWindows-tree (where also configure
and template.mak can be found).

** Something about Makefile.in
--------------------------------

As you have already seen with Makefile, configure makes a lot of use
if the include statement in make to keep the Makefiles as simple as 
possible.

So basically there are only variables to define and then a include command.
Exception to this rule is if you have special rules for some stuff...
These rules should go AFTER the include statement!!!

so the general header looks like this:

	# wxWindows base directory
	WXBASEDIR=@WXBASEDIR@
	# set the OS type for compilation
	OS=@OS@
	# compile a library only
	RULE=bin

and the general footer will look like this:

	# include the definitions now
	include ../../../template.mak

the key variable is RULE, which defines what make should create
in this directory.

here are some examples:

  RULE	  description              
  ===========================================================================
  bin	  creates a local binary (for a global binary prefix bin with g)
  	  additional variables needed:
  		BIN_TARGET	this gives the name of your application
  		BIN_OBJ		this gives the object files needed to
  				link the application
  	  optional variables are:
  		BIN_SRC		this gives the list of c/c++ files for
  				which dependencies will be checked.
  				(This can be achieved with: make depend)
  		BIN_LINK	this gives commands for additional
  				libraries needed to link the application
  ---------------------------------------------------------------------------
  bin2	  creates two local binaries (for global binaries prefix bin2 with g)
  	  in addition to the variables specified above you MUST also
  	  provide the same variables with BIN2_ instead of BIN_
  ---------------------------------------------------------------------------
  lib	  creates a local library (for a global binary prefix bin with g)
  	  additional variables needed:
  		LIB_TARGET	this gives the name of your library
  		LIB_OBJ		this gives the object files needed for
  				the library to be build.
  	  optional variables are:
  		LIB_SRC		this gives the list of c/c++ files for
  				which dependencies will be checked.
  	  libbin and libgbin are also possible and will need in addition
  	  the variables from bin
  ---------------------------------------------------------------------------
  gslib	  is similar to lib, but it creates a shared library if the system
  	  supports it.
  	  additional variables needed:
  		LIB_MAJOR	major number of the shared library
  		LIB_MINOR	minor number of the shared library
  ---------------------------------------------------------------------------
  other additional variables:

  	  ADD_COMPILE	   define additional includes/defines that
  			   are needed to compile the object files
  			   (if you need to reference some directory
  			   utils - like wxGrid -, then please 
  			   reference them with the variables defined
  			   in template.mak - e.g.: $(SRCDIR),$(UTILS),
  			   $(SAMPLES),$(OTHERS))

  	  NEEDED_DEFINES   lists all the defines that HAVE to be set in
  			   /include/wx/setup.h to compile correctly.

	  SRC_DIR	   lists all directories that are needed to
			   compile. (i.e: lists all the directories,
			   where there are source-files.) But it is 
			   also needed to clean an object and for 
			   machines, for which make does not support 
			   VPATH

currently there are the following compiling rules provided:
object files are created for the following file extensions:
.c .cc .cpp

Please have a closer look at the Makefiles in this distribution.

* Platforms configure is working with
---------------------------------------

Please report build succes on any machine. Especially non-
Linux operating systems (which I don't have).

Original author of the autoconf system for wxxt-1.66 and for this INSTALL
file:

	Martin Sperl	sperl@dsn.ast.univie.ac.at
	
Ported to wxGTK 0.1:

	Wolfram Gloger  wmglo@dent.med.uni-muenchen.de

Thanks alot to both of them.

In the hope that it will be useful,

        Robert Roebling roebling@sun2.ruf.uni-freiburg.de
Commit	Line	Data
a1a2adef RR	1	* General
	2	----------
	3
	4	The Unix variants of wxWindows use GNU configure. If you have problems
	5	with your make use GNU make instead.
	6
cd53f341 RR	7	Read my homepage at
	8
	9	http://www.freiburg.linux.de/~wxxt
	10
	11	for newest information.
	12
a1a2adef RR	13	* GUI libraries
	14	-----------------------
	15
	16	wxWindows requires a GUI toolkit to be installed. Does that make
	17	sense? So far only the GTK is supported, but we hope to provide
	18	the choice between GTK, Qt, Motif/Lesstif in the not so distant
	19	future.
	20
	21	You can get the newest version of the GTK from the GTK homepage
	22	at
	23	http://www.gtk.org
	24
	25	The newest versin of Qt can be downloaded for free from the Trolltec's
	26	site at
	27	http://www.troll.no
	28
	29	Lesstif can be downloaded from their site
	30	at
	31	http://www.lesstif.org
	32
	33	If you want to develop using Motif, you need to buy it, unless it comes
	34	with your operating system such as all commercial Unices, as well as
	35	RedHat's, SuSe's and probably other's Linux Motif editions.
	36
	37	* Additional libraries
	38	-----------------------
	39
	40	There will be a few more features of wxWindows, which will
	41	require further libraries (on some platforms). These
	42	features will be optional. I hope to teach configure
	43	to check that out automatically.
	44
	45	Thread support:
	46
	47	Requires pthreads under Linux with glibc 2. pthreads are
	48	always present on such systems, so just compile, unless
	49	you have RedHat 5.0, which has a broken combination of
	50	glibc 2 and X. In this case, you have to run configure
	51	with "--without-threads".
	52
	53	Requires PCthreads under Linux with libc 5. If you
	54	haven't installed pcthreads, there will be no thread
	55	support in wxWindows, but the library will compile.
	56
	57	Requires Posix threads on commercial Unix system,
	58	which are always present. Just compile.
	59
c67daf87 UR	60	On SGI Irix we first look for sprocs, then pthreads and
c67daf87 UR	61	use the last one found.
a1a2adef RR	62
	63	Python scripting language support:
	64
	65	Requires Python. Soon to come.
	66
	67	* Other things to do
	68	-----------------------------
	69
	70	wxGTK and wxMotif/wxLesstif require the built-in
	71	ImLib/GdkImlib to be configured. For that purpose
	72	copy the two files from /misc/imlib to your
cd53f341 RR	73	home directory and rename "imrc" -> ".imrc".
	74	You may also edit imrc by hand as you like.
	75	The palette file is required when using
a1a2adef RR	76	wxWindows in 256-colour mode.
	77
	78	If you want to use wxWindows's ODBC support, you'll have
	79	to create a .odbc.ini file. The readme file in
	80	~/src/iodbc tells you what to do.
	81
	82
	83	* Create your configuration
	84	-----------------------------
	85
	86	This must be done in /install/unix
	87
	88	Usage:
	89	./configure options
	90
	91	If you want to use system's C and C++ compiler,
	92	set environment variables CC and CCC as
	93
	94	% setenv CC cc
	95	% setenv CCC CC
	96	% ./configure options
	97
c67daf87 UR	98	Using the SGI native compilers, it is recommended that you
	99	also set CFLAGS and CXXFLAGS before running configure. These
	100	should be set to :
	101
	102	CFLAGS="-mips3 -n32"
	103	CXXFLAGS="-mips3 -n32"
	104
	105	This is essential if you want to use the resultant binaries
	106	on any other machine than the one it was compiled on. If you
	107	have a 64bit machine (Octane) you should also do this to ensure
	108	you don't accidently build the libraries as 64bit (which is
	109	untested).
	110
	111	The SGI native compiler support has only been tested on Irix 6.5.
	112
a1a2adef RR	113	to see all the options please use:
	114
	115	./configure --help
	116
	117	The basic philosophy is that if you want to use different
	118	configurations, like a debug and a release version,
	119	or use the same source tree on different systems,
	120	you have only to change the environment variable OSTYPE.
	121	(Sadly this variable is not set by default on some systems
	122	in some shells - on SGI's for example). So you will have to
	123	set it there. This variable HAS to be set before starting
	124	configure, so that it knows which system it tries to
	125	configure for.
	126
	127	Configure will complain if the system variable OSTYPE has
	128	not been defined. And Make in some circumstances as well...
	129
c67daf87	130
a1a2adef RR	131	* General options
	132	-------------------
	133
	134	Obviously, you have to choose a toolkit. You must do this by
	135	running configure with either of
	136
	137	--with-gtk Use the GIMP ToolKit (GTK)
	138
	139	--with-qt Use Qt from TrollTec
	140
	141	--with-motif Use either Motif or Lesstif
	142	Configure will look for both.
	143
	144	The following options handle the kind of library you want to build.
	145
cd53f341 RR	146	--without-threads Compile without thread support.
cd53f341 RR	147
a1a2adef RR	148	--with-shared Create shared libraries.
	149
	150	--without-optimise Do not optimise the code.
	151
ff7b1510 RR	152	--with-profile Add profiling info to the object
ff7b1510 RR	153	files. Currently broken, I think.
a1a2adef	154
ff7b1510 RR	155	--with-mem_tracing Add built-in memory tracing.
ff7b1510 RR	156	This doesn't work well with gcc.
a1a2adef	157
ff7b1510 RR	158	--with-dmalloc Use the dmalloc memory debugger.
	159	Read more at www.letters.com/dmalloc/
	160
	161	--with-debug_info Add debug info to object files and
	162	executables.
a1a2adef RR	163
	164	--with-debug_flag Define __DEBUG__ and __WXDEBUG__ when
	165	compiling.
	166
	167	* Feature Options
	168	-------------------
	169
	170	When using the Windows version of wxWindows, it is possible
	171	to edit the file /include/wx/msw/setup.h in order to enable
	172	or disable some features of wxWindows so that the resulting
	173	binaries get smaller.
	174
	175	As I don't yet care for binary size and target mainly at
	176	producing a shared library, wxWindows's configure system auto-
	177	matically enables all features, as long as they are already
	178	implemented.
	179
	180	* Compiling
	181	-------------
	182
	183	The following must be done in the base directory (e.g. ~/wxGTK
	184	or ~/wxWin)
	185
	186	First you have to create all makefiles in all subdirectories:
	187
	188	make Makefiles
	189
	190	Dependencies are generated automatically using
	191
	192	make depend
	193
cd53f341	194	(For some reason, this doesn't seem to work completely.)
a1a2adef RR	195
	196	Now the makefiles are created you can compile everything is as simple
	197	as typing:
	198
	199	make
	200
	201	make yourself some coffee, as it will try to compile
	202	ALL the files in this distribution.
	203
	204	if you want to be more selective:
	205
	206	make src will build only the base libraries
	207	make utils will build the utils
	208	make samples will build the samples
	209	make other will build the other samples
	210	make user will build the files in the directory other
	211
	212	Depending on the configuration of some files, the libraries
	213	and binaries will be placed in different directories.
	214	The "global" binaries and libraries will be placed in:
	215
	216	bin/$(OSTYPE) and
	217	lib/$(OSTYPE) respectively
	218
	219	"local" binaries and libraries will be placed in:
	220
	221	(basedir of that application)/$(OSTYPE).
	222
	223	This is also the place where all the object-files will go.
	224
	225	If you want to conserve disk space by removing unnecessary
	226	object-files:
	227
	228	make clean_obj
	229
	230	will do the work for you.
	231
	232	* Creating a new Project
	233	--------------------------
	234
	235	I propose to put all contributed programs in the directory
	236	"~/wxWin/user", with a directory of its own.
	237
	238	This directory then should include the following files:
	239
	240	Makefile (You can copy this one from any application in samples
	241	probably you will not need to edit this one. There is
	242	only one case where you might be interested in changing
	243	this file, but about that see later.)
	244	Makefile.in (This is the base application-Makefile template, from
	245	which the actual Makefile for each system is created.
	246	More about this later)
	247
	248	put ALL your source code along with all the other stuff you need for
	249	your application in this directory (subdirectories are welcome).
	250
	251	** Something about Makefiles
	252	------------------------------
	253
	254	On general principle it should only contain ONE line, which is as follows:
	255
	256	include ../../src/unix/setup/general/makeapp
	257
	258	this will include all the necessary definitions for creating the applications
259
260	the only case where you might want to add another line is the following:
261	this version of configure also supports creation of source archives of the
262	application for easy distribution and updates to newer version of wxWindows.
263	For this purpose all files in the application-directory will be put into
264	a gziped tar-file in the full notation user/<your application>/*
265	if you want to include some other files that you want "more visible", like
266	a README.<yourApp> or a shell script for easy
267	compilation/installation/distribution, then you have to add a variable
268
269	DISTRIBUTE_ADDITIONAL=<your files>
270
271	to the Makefile.
272	So it would look like this:
273
274	DISTRIBUTE_ADDITIONAL=README.TheApp
275	include ../../src/unix/setup/general/makeapp
276
277	As we have already talked about distribution the command to create a
278	distribution is:
279
280	make distrib
281
282	NOTE: If you are in the base directory of wxWindows it will create
283	distribution packages for wxWindows as well as for all packages in the
284	user directory.
285	So if you want to create only packages for the files in user,
286	then go to the directory other and type:
287
288	make distrib
289
290	or if you only want one application to be created then
291	enter the specific directory and type there:
292	make distrib
293
294	All the distribution files will be put in the directory
295	distrib at the base of the wxWindows-tree (where also configure
296	and template.mak can be found).
297
298	** Something about Makefile.in
299	--------------------------------
300
301	As you have already seen with Makefile, configure makes a lot of use
302	if the include statement in make to keep the Makefiles as simple as
303	possible.
304
305	So basically there are only variables to define and then a include command.
306	Exception to this rule is if you have special rules for some stuff...
307	These rules should go AFTER the include statement!!!
308
309	so the general header looks like this:
310
311	# wxWindows base directory
312	WXBASEDIR=@WXBASEDIR@
313	# set the OS type for compilation
314	OS=@OS@
315	# compile a library only
316	RULE=bin
317
318	and the general footer will look like this:
319
320	# include the definitions now
321	include ../../../template.mak
322
323	the key variable is RULE, which defines what make should create
324	in this directory.
325
326	here are some examples:
327
328	RULE description
329	===========================================================================
330	bin creates a local binary (for a global binary prefix bin with g)
331	additional variables needed:
332	BIN_TARGET this gives the name of your application
333	BIN_OBJ this gives the object files needed to
334	link the application
335	optional variables are:
336	BIN_SRC this gives the list of c/c++ files for
337	which dependencies will be checked.
338	(This can be achieved with: make depend)
339	BIN_LINK this gives commands for additional
340	libraries needed to link the application
341	---------------------------------------------------------------------------
342	bin2 creates two local binaries (for global binaries prefix bin2 with g)
343	in addition to the variables specified above you MUST also
344	provide the same variables with BIN2_ instead of BIN_
345	---------------------------------------------------------------------------
346	lib creates a local library (for a global binary prefix bin with g)
347	additional variables needed:
348	LIB_TARGET this gives the name of your library
349	LIB_OBJ this gives the object files needed for
350	the library to be build.
351	optional variables are:
352	LIB_SRC this gives the list of c/c++ files for
353	which dependencies will be checked.
354	libbin and libgbin are also possible and will need in addition
355	the variables from bin
356	---------------------------------------------------------------------------
357	gslib is similar to lib, but it creates a shared library if the system
358	supports it.
359	additional variables needed:
360	LIB_MAJOR major number of the shared library
361	LIB_MINOR minor number of the shared library
362	---------------------------------------------------------------------------
363	other additional variables:
364
365	ADD_COMPILE define additional includes/defines that
366	are needed to compile the object files
367	(if you need to reference some directory
368	utils - like wxGrid -, then please
369	reference them with the variables defined
370	in template.mak - e.g.: $(SRCDIR),$(UTILS),
371	$(SAMPLES),$(OTHERS))
372
373	NEEDED_DEFINES lists all the defines that HAVE to be set in
374	/include/wx/setup.h to compile correctly.
375
376	SRC_DIR lists all directories that are needed to
377	compile. (i.e: lists all the directories,
378	where there are source-files.) But it is
379	also needed to clean an object and for
380	machines, for which make does not support
381	VPATH
382
383	currently there are the following compiling rules provided:
384	object files are created for the following file extensions:
385	.c .cc .cpp
386
387	Please have a closer look at the Makefiles in this distribution.
388
389	* Platforms configure is working with
390	---------------------------------------
391
392	Please report build succes on any machine. Especially non-
393	Linux operating systems (which I don't have).
394
395	Original author of the autoconf system for wxxt-1.66 and for this INSTALL
396	file:
397
398	Martin Sperl sperl@dsn.ast.univie.ac.at
399
400	Ported to wxGTK 0.1:
401
402	Wolfram Gloger wmglo@dent.med.uni-muenchen.de
403
404	Thanks alot to both of them.
405
406	In the hope that it will be useful,
407
408	Robert Roebling roebling@sun2.ruf.uni-freiburg.de
409
410