Browse Source

Update READMEs.

tags/v1.3.1000
Jonathan Moore Liles 9 years ago
parent
commit
f10ed5a30d
5 changed files with 21 additions and 1498 deletions
  1. +21
    -155
      README
  2. +0
    -111
      README.Cairo.txt
  3. +0
    -608
      README.MSWindows.txt
  4. +0
    -318
      README.OSX.txt
  5. +0
    -306
      README.Unix.txt

+ 21
- 155
README View File

@@ -1,167 +1,33 @@
README - Fast Light Tool Kit (FLTK) Version 1.3.0
-------------------------------------------------

WHAT IS FLTK?
# What is NTK? #

The Fast Light Tool Kit ("FLTK", pronounced "fulltick") is a
a cross-platform C++ GUI toolkit for UNIX(r)/Linux(r) (X11),
Microsoft(r) Windows(r), and MacOS(r) X. FLTK provides
modern GUI functionality without the bloat and supports 3D
graphics via OpenGL(r) and its built-in GLUT emulation. It
was originally developed by Mr. Bill Spitzak and is
currently maintained by a small group of developers across
the world with a central repository in the US.
NTK is a fork of FLTK 1.3.0 which adds graphics rendering via
Cairo, support for transparent/overlapping widgets, streamlining
of internals, and some new/improved widgets.

# LICENSING #

LICENSING
NTK has the same license as FLTK.

FLTK comes with complete free source code. FLTK is available
under the terms of the GNU Library General Public License.
Contrary to popular belief, it can be used in commercial
software! (Even Bill Gates could use it.)
# Documentation #

Currently, there is none (beyond the FLTK 1.3 docs)

ON-LINE DOCUMENTATION
# Building #

All of the documentation is in HTML in the subdirectory
"documentation". The "index.html" file should be your
starting point. PostScript(tm) and PDF versions of this
documentation is also available from the FLTK web site at:
NTK uses the 'waf' build system.
Type:
./waf configure --help
to see compilation options.

http://www.fltk.org/documentation.php
Building and installing generally goes like:

./waf configure
./waf
su -c './waf install'

BUILDING AND INSTALLING FLTK UNDER UNIX AND Mac OS X
# Usage #

In most cases you can just type "make". This will run
configure with the default (no) options and then compile
everything.

FLTK uses GNU autoconf to configure itself for your UNIX
platform. The main things that the configure script will
look for are the X11, OpenGL (or Mesa), and JPEG header and
library files. Make sure that they are in the standard
include/library locations. If they aren't you need to
define the CFLAGS, CXXFLAGS, and LDFLAGS environment
variables.

If you aren't using "gcc", "g++", "c++", or "CC" for your
C++ compiler, you'll also need to set the CXX environment
variable. Similarly, if you aren't using "gcc" or "cc" for
your C compiler you'll need to set the CC environment
variable.

You can run configure yourself to get the exact setup you
need. Type "./configure <options>". Options include:

--enable-cygwin - Enable the Cygwin libraries (WIN32)
--enable-debug - Enable debugging code & symbols
--disable-gl - Disable OpenGL support
--enable-shared - Enable generation of shared libraries
--enable-threads - Enable multithreading support
--enable-xdbe - Enable the X double-buffer extension
--enable-xft - Enable the Xft library (anti-aliased fonts)

--bindir=/path - Set the location for executables
[default = /usr/local/bin]
--libdir=/path - Set the location for libraries
[default = /usr/local/lib]
--includedir=/path - Set the location for include files.
[default = /usr/local/include]
--prefix=/dir - Set the directory prefix for files
[default = /usr/local]

When the configure script is done you can just run the
"make" command. This will build the library, FLUID tool, and
all of the test programs.

To install the library, become root and type "make
install". This will copy the "fluid" executable to
"bindir", the header files to "includedir", and the library
files to "libdir".
To install additional files and icons to be used by the main
desktop environments such as KDE, GNOME and XFCE, you will also
need to run "make install-desktop" as root.


BUILDING FLTK UNDER MICROSOFT WINDOWS

There are two ways to build FLTK under Microsoft Windows.
The first is to use the Visual C++ project files under the
"ide/" directory. See the file ide/README.IDE for more info.

The second method is to use a GNU-based development tool.
To build with the Cygwin or MinGW tools, use the supplied
configure script as specified in the UNIX section above:

sh configure ...options...


INTERNET RESOURCES

FLTK is available on the 'net in a bunch of locations:

- WWW: http://www.fltk.org/
http://www.fltk.org/str.php [for reporting bugs]
http://www.fltk.org/software.php [source code]

- FTP: http://ftp.easysw.com/pub/fltk
ftp://ftp.easysw.com/pub/fltk
ftp://ftp2.easysw.com/pub/fltk
ftp://ftp.funet.fi/pub/mirrors/ftp.easysw.com/pub/fltk
ftp://linux.mathematik.tu-darmstadt.de/pub/linux/mirrors/misc/fltk
ftp://gd.tuwien.ac.at/hci/fltk

- EMail: fltk@fltk.org [see instructions below]

To send a message to the FLTK mailing list ("fltk@fltk.org")
you must first join the list. Non-member submissions are
blocked to avoid problems with SPAM.

To join the FLTK mailing list, go the following web page:

http://lists.easysw.com/listinfo/fltk


REPORTING BUGS

To report a bug in FLTK, use the form at:

http://www.fltk.org/str.php

For general support and questions, please use the FLTK
mailing list at "fltk@fltk.org".


TRADEMARKS

Microsoft and Windows are registered trademarks of Microsoft
Corporation. UNIX is a registered trademark of the X/Open
Group, Inc. OpenGL is a registered trademark of Silicon
Graphics, Inc. Mac OS is a registered trademark of Apple
Computers, Inc.


COPYRIGHT

FLTK is copyright 1998-2011 by Bill Spitzak
(spitzak@users.sourceforge.net) and others,
see the CREDITS file for more info.

This library is free software; you can redistribute it
and/or modify it under the terms of the GNU Library General
Public License as published by the Free Software Foundation;
either version 2 of the License, or (at your option) any
later version.

This library is distributed in the hope that it will be
useful, but WITHOUT ANY WARRANTY; without even the implied
warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
PURPOSE. See the GNU Library General Public License for
more details.

You should have received a copy of the GNU Library General
Public License along with this library; if not, write to the
Free Software Foundation, Inc., 59 Temple Place, Suite 330,
Boston, MA 02111-1307 USA.
NTK uses pkg-config for publishing library information.

+ 0
- 111
README.Cairo.txt View File

@@ -1,111 +0,0 @@
README.Cairo.txt - 2010-10-25 - Cairo rendering support for FLTK
----------------------------------------------------------------



CONTENTS
==========

1 INTRODUCTION
2 CAIRO SUPPORT FOR FLTK 1.3
2.1 Configuration
2.2 Currently supported features
2.3 Future considerations
3 DOCUMENT HISTORY



iINTRODUCTION
===============

Cairo is a software library used to provide a vector graphics-based,
device-independent API for software developers. It is designed to provide
primitives for 2-dimensional drawing across a number of different
wbackends. Cairo is designed to use hardware acceleration when available.


CAIRO SUPPORT FOR FLTK 1.3
=============================

It is now possible to integrate cairo rendering in your fltk application
more easily and transparently.
In 1.3, we provide minimum support for Cairo,
In particular, no "total" cairo rendering layer support is achieved,
as in fltk2.


Configuration
---------------

All the changes are *inactive* as long as the new configuration
option --enable-cairo is not added to the configure command.
For non configure based platforms/ide, the FLTK_HAVE_CAIRO preprocess var.
has to be defined.
All configure based build files has now this feature integrated,
also vc2005 build files have 2 new build modes "Release Cairo" and
"Debug Cairo".
Others IDE's will be updated progressively.


Currently supported features
------------------------------

- Adding a new Fl_Cairo_Window class permitting transparent and easy
integration of a Cairo draw callback without the need to achieve subclassing.

- Adding a Fl::cairo_make_current(Fl_Window*) function only providing
transparently a cairo context to your custom Fl_Window derived class.
This function is intended to be used in your overloaded draw() method.

- Adding an optional cairo autolink context mode support (disabled by default)
which permits complete & automatic synchronization of OS dependent graphical
context and cairo contexts, thus furthering a valid cairo context anytime,
in any current window.
This feature should be only necessary in the following cases:
- Intensive and almost systematic use of cairo contexts in an fltk application
- Creation of a new cairo based scheme for fltk ...
- Other uses of cairo necessiting the flk internals instrumentation
to automatically making possible the use of a cairo context
in any fltk window.

- A new cairo demo that is available in the test subdirectory and has been
used as a testcase durings the multiplatform tests.

For more details, please have a look to the doxygen documentation,
in the Modules section.


Future considerations
-----------------------

From Bill:
First there is the FLTK_HAVE_CAIRO configuration option. This indicates that
any cairo calls are available. In this case you get something like this:

// static variable holding the last cairo context fltk set:
cairo_t* Fl::cr;

// Make cr draw in this window. This hides the ugly platform-dependent
// part of getting cairo going:
void Fl::cairo_make_current(Fl_Window*)

*** POST 1.3 potential cairo use:
// Set cr to something you made yourself. This lets you reuse functions
// that use cr, and also tells fltk that cr is not one of it's own and
// thus cannot be destroyed or reused for a different window:
void Fl::cairo_make_current(cairo_t*)

Second there is the FLTK_USE_CAIRO configuration option. This means that all
drawing is done using Cairo. In this case when a widget draw() method is
called, it is exactly as though cairo_make_current(window) has been done.
***

Note that it should be possible to compile so FLTK_HAVE_CAIRO works even if
FLTK_USE_CAIRO does not, and so that turning on FLTK_USE_CAIRO does not break any
programs written for FLTK_HAVE_CAIRO.


DOCUMENT HISTORY
==================

Dec 20 2010 - matt: restructured document

+ 0
- 608
README.MSWindows.txt View File

@@ -1,608 +0,0 @@
README.MSWindows.txt - 2010-10-25 - Building FLTK under Microsoft Windows
-------------------------------------------------------------------------



CONTENTS
==========

1 INTRODUCTION
2 HOW TO BUILD FLTK USING MinGW/Cygwin
2.1 The Tools
2.2 Recommended Command Line Build Environment
2.3 Prerequisites
2.4 Downloading and Unpacking
2.5 Configuring FLTK
2.6 Building FLTK
2.7 Testing FLTK
2.8 Installing FLTK
2.9 Creating new Projects
3 HOW TO BUILD FLTK USING VISUAL STUDIO 2008
3.1 Prerequisites
3.2 Downloading and Unpacking
3.3 Configuring FLTK
3.4 Building FLTK
3.5 Testing FLTK
3.6 Installing FLTK
3.7 Creating new Projects
4 HOW TO BUILD FLTK USING VISUAL STUDIO 2010
4.1 Prerequisites
4.2 Downloading and Unpacking
4.3 Configuring FLTK
4.4 Building FLTK
4.5 Testing FLTK
4.6 Installing FLTK
4.7 Creating new Projects
5 FREQUENTLY ASKED QUESTIONS
7 LINKS
6 DOCUMENT HISTORY


INTRODUCTION
==============

FLTK 1.3 and later is officially supported on Windows (2000,) 2003,
XP, and later. Older Windows versions are not officially supported,
but may still work. The main reason is that the OS version needs
to support UTF-8. FLTK 1.3 is known to work on Windows 7 and Vista.

FLTK currently supports the following development
environments on the Windows platform:

- Free Microsoft Visual C++ 2008 Express and Visual
C++ 2010 Express using the supplied workspace and
project files. Older and the commercial versions can
be used as well, if they can open the project files.
Be sure to get your service packs!

The project files can be found in the ide/ directory.
Please read ide/README.IDE for more info about this.

- GNU toolsets (Cygwin or MinGW) hosted on Windows.

CAUTION: Libraries built by any one of these environments can not be mixed
with object files from any other environment!


HOW TO BUILD FLTK USING MinGW and Cygwin
==========================================

This chapter of this document gives a brief overview of
compiling and using FLTK with the Cygwin and MinGW compiler
toolkits. Both toolkits provide a build environment based
around the GNU C/C++ compiler. Further information is
available from the FLTK website at http://www.fltk.org, such
as this Howto note: http://www.fltk.org/articles.php?L598

The Cygwin build environment supplies a library (the Cygwin
DLL) that is primarily intended to provide a number of
Unix-like POSIX facilities for programs being ported to the
Windows environment (Win32 or WinNT). Cygwin also supplies
a very Unix-like build environment for Windows, including
the "BASH" Bourne-compatible shell and all of the standard
Unix file utilities (ls, cat, grep, etc.).

Cygwin is developed by Cygnus (now part of RedHat, Inc).
Although provided for free download under the GPL,
distributing programs that require the Cygwin DLL under a
license other than the GPL requires a commercial license for
the Cygwin DLL. Native Windows programs that do not require
the Cygwin DLL (compiled and linked with the "-mno-cygwin"
option) may be released under any license freely.

Note: Since December 2009, there is a new gcc 4.x compiler
that doesn't support the -mno-cygwin option anymore. You
must use the older gcc-3 compiler instead.

An alternative is to install the new (since about Oct. 2010)
mingw cross tools that support newer gcc compilers for building
native Windows applications (like -mno-cygwin above).
Currently you would have to install mingw64-i686-gcc-g++ for
32-bit Windows applications (despite its name!), and/or
mingw64-x86_64-gcc-g++ for 64-bit applications. You may also
need to install the corresponding '-headers' packages as well.
Currently these tools support gcc 4.5.x or newer, but the
setup for FLTK is somewhat more complicated and not yet
completely supported automatically (you may need to edit
some lines in the generated makeinclude file).

The MinGW distribution (Minimalist GNU for Windows) provides
a similar toolset but geared solely towards native Windows
development without the Unix-like POSIX library. The lack of
any libraries under the GPL or any other restrictive license
means that programs built with the MinGW environment may
always be released under any license freely. MinGW also
supplies a Unix-like build environment for Windows,
including MSYS (a Bourne-compatible shell) and the standard
Unix file utilities (ls, cat, grep, etc.)

If you are not familiar with these GNU-like toolkits please
refer to the links section later in this note. In particular,
check out their license conditions carefully before use.


The Tools
-----------

There are currently three main configurations supported by
FLTK with the GNU tools:

1. Cygwin: Built using the Cygwin toolset and using the
Unix-like POSIX compatibility layer provided by the
Cygwin DLL.

2. Cygwin using the "-mno-cygwin" option: Built using
the Cygwin toolset but not using the Cygwin DLL.

3. MinGW: Built using the MinGW utilities, compiler and
tools. This is, in many aspects, analogous to the
Cygwin "-mno-cygwin" option. This is the recommended
one if you want to build native Windows programs only.


Recommended Command Line Build Environment
--------------------------------------------

Our recommendation is to:

1. Get the current Cygwin toolset.

This can either produce executables that do or do not
rely on the Cygwin DLL (check licensing) at your
choice.

2. Get the latest MinGW toolset. It is recommended that
you also get the MSYS shell and the msysDTK developer
toolset.

This will only produce normal Windows native
executables without any Unix or POSIX compatibility
layer.


See the links section below for more information.

Either option can generate windows-native executables and
option 1 can provide a Unix-like POSIX portability layer that
is reliant on a GPLed library.

See the later sections for detailed information about using
one of these configurations.


Prerequisites
---------------

In order to build FLTK from the command line, you need to install the MinGW
environment from www.mingw.org. The graphical installer "mingw-get-inst" can
be downloaded here for free:

http://www.mingw.org/wiki/Getting_Started

Launch the installer and follow the instructions. In the "Select Components"
dialog, add "C++ Compiler", "MSYS Basic System", and "MinGW Developer Toolkit".
Wait for the installer to finish.

After downloading and installing, you need to launch the MinGW Shell through
the Start menu.


Downloading and Unpacking
---------------------------

Download FLTK from here:

http://www.fltk.org/software.php

into your home folder. The default location as seen from MSWindows is similar
to

C:\MinGW\msys\1.0\home\matt\

If you are familiar with "subversion" and like to stay current with your
version, you will find the subversion access parameters at the bottom of
that page. Unpack FLTK into a convenient location. I like to have everything
in my dev directory:

cd
mkdir dev
cd dev
tar xvfz fltk-1.3.xxxx.tar.gz
cd fltk-1.3.xxxx


Configuring FLTK
------------------

Stay in your FLTK source-code directory. Type:

autoconf

Now configure your FLTK installation:

./configure

ADVANCED: type "./configure --help" to get a complete list of optional
configuration parameters. These should be pretty self-explanatory. Some
more details can be found in README.
:END_ADVANCED

The configuration script will check your machine for the required resources
which should all have been part of your MinGW installation. Review the
Configuration Summary, maybe take some notes.

ADVANCED: some versions of MinGW/Msys are broken and complain about a missing
--enable-auto-import. The solution is to upgrade to the current release. If
that is not possible, you can include the --enable-auto-import flag when
linking:
./configure <config flags> LDFLAGS=-Wl,--enable-auto-import
:END_ADVANCED


Building FLTK
---------------

Now this is easy. Stay in your FLTK source-code directory and type:

make

The entire FLTK toolkit including many test programs will be built for you.
No warnings should appear.

(actually, as of Oct 25 2010, quite a lot of warnings related to suggested
parentheses and others will appear, this is normal and will be fixed. The
linker will also spit out a bunch of warnings for every program linked. This
needs to be fixed. Lastly, there is no generator for man pages in a default
MinGW installation, but you can install man and groff to fix this.)


Testing FLTK
--------------

After a successful build, you can test FLTK's capabilities:

test/demo


Installing FLTK
-----------------

If you did not change any of the configuration settings, FLTK will be
installed in "/usr/local/include" and "/usr/local/lib" by typing

make install

It is possible to install FLTK in user space by changing the installation path
to a location within the user account by adding the "--prefix=PREFIX" parameter
to the "./configure" command.


Creating new Projects
-----------------------

FLTK provides a neat script named "fltk-config" that can provide all the flags
needed to build FLTK applications using the same flags that were used to build
the library itself. Running "fltk-config" without arguments will print a list
of options. The easiest call to compile an FLTK application from a single
source file is:

fltk-config --compile myProgram.cxx

"fltk-config" and "fluid" will be installed in "/usr/local/bin/" by default.
I recommend that you add it to the command search path.



HOW TO BUILD FLTK USING VISUAL STUDIO 2008
============================================


Prerequisites
---------------

In order to build FLTK from within VisualStudio 2008, you need to install the
VisualC developer environment from the Microsoft web site. The Express edition
is free of charge and sufficient to develop FLTK applications:

http://www.microsoft.com/express/Downloads/

You must make sure that at least VisualStudio 2008 Service Pack 1 is installed
or building FLTK on a multicore CPU will be very painful!


Downloading and Unpacking
---------------------------

Download FLTK from here:

http://www.fltk.org/software.php

If you are familiar with "subversion" and like to stay current with your
version, you will find the subversion access parameters at the bottom of
that page.

Unpack FLTK by using an appropriate unpacker and copy the new folder into a
convenient location. I have set up a "dev" folder in my home folder for all
my projects.


Configuring FLTK
------------------

Launch VisualStudio. Open the project file in

...\fltk-1.3.xxxx\ide\VisualC2008\fltk.sln

Choose "Debug" or "Release" mode from the "Solution Configurations" menu.


Building FLTK
---------------

Use the context menu of the "demo" project to "Set as StartUp Project". Then
select "Build Solution" from the "Build" menu or press F7 to build all
libraries.

VisualC 2008 has a bug that messes up building a Solution on multicore CPUs.
Make sure that Visual Studio 2008 Service Pack 1 is installed or, as a
workaround, set the "maximum number of parallel project builds" to 1 (Tools >
Options > Projects and Solutions > Build and Run > maximum number of parallel
project builds). Also, repeating the build command two or three times may
clear unresolved reference errors.


Testing FLTK
--------------

Select "Start Debugging" from the "Debug" menu or just press F5 to run the
Demo program. Use "Demo" to explore all test programs.


Installing FLTK
-----------------

The default location for VisualC 2008 libraries and headers is here:

C:\Program Files\Microsoft Visual Studio 9.0\VC\

It is possible to move the FLTK libraries, headers, and Fluid into the
respective subdirectories, so that they are available for future development
without adding link and include paths to the solution.

copy the entire FL directory into the include path

copy all .lib files from the fltk lib directory to the VC lib directory

copy fluid.exe in the fluid directory to the bin directory

I highly discourage using dll's (dynamically linking libraries) on MSWindows
because they will require an installation process and likely cause version
conflicts. Use the static .lib libraries instead.


Creating new Projects
-----------------------

This chapter assumes that libraries and headers are copied into

C:\Program Files\Microsoft Visual Studio 9.0\VC\

Create a new project of type "General", "Empty Project" and add a simple "C++"
file to it. The FLTK "hello" source code is a good base.

Now open the Project Properties dialog and add "Comctl32.lib" and all the FLTK
libraries that you want to use (at least "fltk.lib") to Additional Dependencies
(Configuration Properties > Linker > Additional Dependencies). In the same
dialog, add "WIN32" to the C++ Preprocessor Definitions (Configuration
Properties > C/C++ > Preprocessor > Preprocessor Definitions).

Compile and run your test program with F5.

You can also include .fl resources: add a new Header file to your project, but
let the name end in .fl. Right-click and select "Open with...". Add "fluid.exe"
from the "bin" directory and set it as the default editor.

To automatically compile .fl files, open the Properties editor and set the
Custom Build Steps to:

Command Line: fluid.exe -c $(InputPath)
Description: Compiling Fluid .fl file
Outputs: $(InputDir)$(InputName).cxx; $(InputDir)$(InputName).h

Now add the generated .cxx file to your project as well. Whenever the .fl file
is changed, the corresponding .cxx file will be recompiled.



HOW TO BUILD FLTK USING VISUAL STUDIO 2010
============================================


Prerequisites
---------------

In order to build FLTK from within VisualStudio 2010, you need to install the
VisualC developer environment from the Microsoft web site. The Express edition
is free of charge and sufficient to develop FLTK applications:

http://www.microsoft.com/express/Downloads/


Downloading and Unpacking
---------------------------

Download FLTK from here:

http://www.fltk.org/software.php

If you are familiar with "subversion" and like to stay current with your
version, you will find the subversion access parameters at the bottom of
that page.

Unpack FLTK by using an appropriate unpacker and copy the new folder into a
convenient location. I have set up a "dev" folder in my home folder for all
my projects.


Configuring FLTK
------------------

Launch VisualStudio. Open the project file in

.../fltk-1.3.xxxx/ide/VisualC2010/fltk.sln

Choose "Debug" or "Release" mode from the "Solution Configurations" menu.


Building FLTK
---------------

Use the context menu of the "demo" project to "Set as StartUp Project". Then
select "Build Solution" from the "Build" menu or press F7 to build all
libraries.


Testing FLTK
--------------

Select "Start Debugging" from the "Debug" menu or just press F5 to run the
Demo program. Use "Demo" to explore all test programs.


Installing FLTK
-----------------

The default location for VisualC 2010 libraries and headers is here:

C:\Program Files\Microsoft Visual Studio 10.0\VC\

It is possible to move the FLTK libraries, headers, and Fluid into the
respective subdirectories, so that they are available for future development
without adding link and include paths to the solution.

copy the entire FL directory into the include path

copy all .lib files from the fltk lib directory to the VC lib directory

copy fluid.exe in the fluid directory to the bin directory

I highly discourage using dll's (dynamically linking libraries) on MSWindows
because they will require an installation process and likely cause version
conflicts. Use the static .lib libraries instead.


Creating new Projects
-----------------------

This chapter assumes that libraries and headers are copied into

C:\Program Files\Microsoft Visual Studio 10.0\VC\

Create a new project of type "General", "Empty Project" and add a simple "C++"
file to it. The FLTK "hello" source code is a good base.

Now open the Project Properties dialog and add "Comctl32.lib" and all the FLTK
libraries that you want to use (at least "fltk.lib") to Additional Dependencies
(Configuration Properties > Linker > Additional Dependencies). In the same
dialog, add "WIN32" to the C++ Preprocessor Definitions (Configuration
Properties > C/C++ > Preprocessor > Preprocessor Definitions).

Compile and run your test program with F5.

You can also include .fl resources: add a new Header file to your project, but
let the name end in .fl. Right-click and select "Open with...". Add "fluid.exe"
from the "bin" directory and set it as the default editor.

To automatically compile .fl files, open the Properties editor and change the
Element Type to Custom Build and click Apply. Now set the
Custom Build Steps to:

Command Line: fluid.exe -c %(FullPath)
Description: Compiling Fluid .fl file
Outputs: $(InputDir)$(InputName).cxx; $(InputDir)$(InputName).h

Now add the generated .cxx file to your project as well. Whenever the .fl file
is changed, the corresponding .cxx file will be recompiled.



FREQUENTLY ASKED QUESTIONS
============================


Why does a console window appear when I run my program?
---------------------------------------------------------

Windows has a flag that determines whether an application
runs in the foreground with a console or in the background
without a console. Use the "-mwindows" option to make your
application run in the background and "-mconsole" to run in
the foreground.

Keep in mind that a windows application cannot send output
to stdout, even if you run it from an existing console
application.
(Note: A special case of this exists if running a MinGW
application from the command line of an MSYS shell, when an
application is able to write to stdout, even if compiled with
"-mwindows". The same applies to Cygwin.)


How do I get OpenGL to work?
------------------------------

Both builds should automatically support OpenGL.

The configuration file config.h has a number of settings
which control compile-time compilation. One such setting is
"HAVE_GL". This may be set to 0 to disable Open GL operation.
Changing the line in config.h to

#define HAVE_GL 1

will change this to compile and link in OpenGL.



LINKS
=======

The following links may be of use:

1. Main Cygwin homepage:

http://www.cygwin.com/

2. Main Mingw homepage:

http://www.mingw.org/

In particular look for the MinGW FAQ at this link for
a lot of useful Mingw-native development
documentation.


3. Check out the FLTK newsgroups at the FLTK homepage:

http://www.fltk.org/

Its archival search facilities are EXTREMELY useful
to check back through previous problems with this
sort of configuration before posting new questions.

4. GNU Compiler Collection (GCC) compiler homepage:

http://gcc.gnu.org/

5. OpenGL page - for OpenGL and GLUT libs

http://www.opengl.org/



DOCUMENT HISTORY
==================

Oct 25 2010 - matt: restructured entire document and verified instructions
Dec 20 2010 - matt: merged with README.win32
Dec 22 2010 - AlbrechtS: added newer Cygwin (cross/mingw-w64) options

+ 0
- 318
README.OSX.txt View File

@@ -1,318 +0,0 @@
README.OSX.txt - 2010-10-23 - Building FLTK under Apple OS X
------------------------------------------------------------



CONTENTS
==========

1 INTRODUCTION
2 HOW TO BUILD FLTK USING GCC
2.1 Prerequisites
2.2 Downloading and Unpacking
2.3 Configuring FLTK
2.4 Building FLTK
2.5 Testing FLTK
2.6 Installing FLTK
2.7 Creating new Projects
3 HOW TO BUILD FLTK USING XCODE3
3.1 Prerequisites
3.2 Downloading and Unpacking
3.3 Configuring FLTK
3.4 Building FLTK
3.5 Testing FLTK
3.6 Uninstalling previous versions of FLTK
3.7 Installing FLTK
3.8 Installing Little Helpers
3.9 Creating new Projects
4 DOCUMENT HISTORY


1 INTRODUCTION
=================

FLTK currently supports the following development environments on the Apple OS X
platform:

- gcc command line tools
- Xcode 3.x
CAUTION: gcc command line built libraries and Xcode created Frameworks should
not be mixed!


2 HOW TO BUILD FLTK USING GCC
================================


2.1 Prerequisites
--------------------

In order to build FLTK from the command line, you need to install the Xcode
developer environment from the Apple Inc. web site. The developer environment
can be downloaded from the Mac Dev Center for free:

http://developer.apple.com/technologies/xcode.html
After downloading and installing, you need to launch the Terminal. Terminal.app
is located in the "Utilities" folder inside the "Applications" folder. I like to
keep the Terminal in the Dock.


2.2 Downloading and Unpacking
--------------------------------

Download FLTK from here:

http://www.fltk.org/software.php

If you are familiar with "subversion" and like to stay current with your
version, you will find the subversion access parameters at the bottom of that
page. Unpack FLTK into a convinient location. I like to have everything in my
dev directory:

cd
mkdir dev
cd dev
mv ~/Downloads/fltk-1.3.xxxx.tar.gz .
tar xvfz fltk-1.3.xxxx.tar.gz
cd fltk-1.3.xxxx

2.3 Configuring FLTK
-----------------------

Stay in your FLTK source-code directory. Type:
autoconf

Now configure your FLTK installation:

./configure
ADVANCED: type "./configure --help" to get a complete list of optional
configurations parameters. These should be pretty self-explanatory. Some
more details can be found in README.

To create Universal Binaries, start "configure" with these flags:
./configure --with-archflags="-arch i386 -arch ppc -arch x86_64"
:END_ADVANCED

The configuration script will check your machine for the required resources
which should all have been part of your Xcode installation. Review the
Configuration Summary, maybe take some notes.


2.4 Building FLTK
--------------------

Now this is easy. Stay in your FLTK source-code directory and type:

make

The entire FLTK toolkit including many test programs will be built for you. No
warnings should appear, but "ranlib" may complain about a few modules having no
symbols. This is normal and can safely be ignored.


2.5 Testing FLTK
-------------------

After a successful build, you can test FLTK's capabilities:

test/demo


2.6 Installing FLTK
----------------------

If you did not change any of the configuration settings, FLTK will be installed
in "/usr/local/include" and "/usr/local/lib" by typing

sudo make install
It is possible to install FLTK without superuser privileges by changing the
installation path to a location within the user account by adding the
"--prefix=PREFIX" parameter to the "./configure" command.


2.7 Creating new Projects
----------------------------

FLTK provides a neat script named "fltk-config" that can provide all the flags
needed to build FLTK applications using the same flags that were used to build
the library itself. Architecture flags (e.g., -arch i386) used to build the
library, though, are not provided by the fltk-config script. This allows to
build universal libraries and to produce applications of any architecture
from them. Running "fltk-config" without arguments will print a list
of options. The easiest call to compile an FLTK application from a single source
file is:

fltk-config --compile myProgram.cxx

"fltk-config" and "fluid" will be installed in "/usr/local/bin/" by default. I
recommend that you add it to the command search path.



3 HOW TO BUILD FLTK USING XCODE3
===================================


3.1 Prerequisites
--------------------

In order to build FLTK from within Xcode, you need to install the Xcode
developer environment from the Apple Inc. web site. The developer environment
can be downloaded from the Mac Dev Center for free:

http://developer.apple.com/technologies/xcode.html

3.2 Downloading and Unpacking
--------------------------------

Download FLTK from here:

http://www.fltk.org/software.php

If you are familiar with "subversion" and like to stay current with your
version, you will find the subversion access parameters at the bottom of that
page. You can use the SCM system that is built into Xcode.

Unpack FLTK by double-clicking it and copy the new folder into a convenient
location. I have set up a "dev" folder in my home folder for all my projects.


3.3 Configuring FLTK
-----------------------

Launch Xcode. Open the project file in

.../fltk-1.3.xxxx/ide/Xcode3/FLTK.xcodeproj

Use the "Project" pulldown menu to change "Active Build Configuration" to
"Release". Change the "Active Architecture" as desired.

3.4 Building FLTK
--------------------

Use the "Project" pulldown menu to set the "Active Target" to "Demo".
Select "Build" from the "Build" menu to create all libraries and test applications.

All frameworks and apps will be located in "./ide/Xcode3/build/Release/".


3.5 Testing FLTK
-------------------

Select "Build and Run" from the "Build" menu to run the Demo program. Use "Demo"
to explore all test programs.


3.6 Uninstalling previous versions of FLTK
---------------------------------------------

Remove FLTK frameworks:

sudo rm -r /Library/Frameworks/fltk*.framework
Remove Fluid and possibly other utilities:

sudo rm -r /Developer/Applications/Utilities/FLTK/

3.7 Installing FLTK
----------------------

When distributing FLTK applications, the FLTK frameworks should be made part of
the application package. For development however, it is very convenient to have
the Release-mode Frameworks in a standard location.

For Xcode project template use, all FLTK frameworks should be copied from
"./ide/Xcode3/build/Release/" to "/Library/Frameworks/". The FLTK header files
for all FLTK frameworks will then be at "/Library/Frameworks/fltk.framework/
Headers/". Add this path to the header search path of your projects.

sudo rm -f -r /Library/Frameworks/fltk*
sudo cp -R ide/Xcode3/build/Release/fltk*.framework /Library/Frameworks/

Many FLTK applications will use Fluid, the FLTK User Interface builder, to
generate C++ source code from .fl resource files. Add Fluid to the developer
tools:

sudo mkdir /Developer/Applications/Utilities/FLTK/
sudo rm -f -r /Developer/Applications/Utilities/FLTK/Fluid.app
sudo cp -R ide/Xcode3/build/Release/Fluid.app /Developer/Applications/Utilities/FLTK/


3.8 Installing Little Helpers
--------------------------------


- Project Templates:

Project Templates are the quickest way to create a new FLTK application from
within Xcode. The included project builds an FLTK based Cocoa application
written in C++ with support for the Fluid UI designer, image reading, and
OpenGL. Unused FLTK sub-Frameworks can simply be removed from the project.
The template assumes that Release versions of the FLTK frameworks are installed
in /Library/Frameworks as described above.

First, we need to create the Template folder:

sudo mkdir -p /Library/Application\ Support/Developer/Shared/Xcode/Project\ Templates/

Next, we copy the project template over:

sudo cp -r ide/Xcode3/Project\ Templates/* /Library/Application\ Support/Developer/Shared/Xcode/Project\ Templates/

After restarting Xcode, the dialog for "File > New Project..." will offer an
FLTK 1.3 user template which is ready to compile.


- Fluid file handling

This section assumes that a Release version of Fluid is installed in
"/Developer/Applications/Utilities/FLTK/" as described above. It will install
a new file type which opens Fluid as an editor for files ending in ".fl".

First, we need to create the spec folder:

sudo mkdir -p /Library/Application\ Support/Developer/Shared/Xcode/Specifications/

Next, we copy the Fluid specification over:

sudo cp ide/Xcode3/fluid.pbfilespec /Library/Application\ Support/Developer/Shared/Xcode/Specifications/

Open Xcode preferences and select the File Types tab. Find the
"sourcecode.fluid" entry in "file > text > sourcecode" and set the external
editor to Fluid. When adding ".fl" files, set the File Type in the Info dialog
to "sourcecode.fluid" and Xcode will edit your file in Fluid when
double-clicking.


- More

TODO: Language Definition
TODO: Build Rules


3.9 Creating new Projects
----------------------------

If the little helpers above were installed, the menu "File > New Project..."
will pop up a dialog that offers a User Template named Fluid. Select it and
follow the instructions.



4 DOCUMENT HISTORY
=====================

Oct 29 2010 - matt: removed warnings
Oct 24 2010 - matt: restructured entire document and verified instructions
Dec 19 2010 - Manolo: corrected typos
Dec 29 2010 - Manolo: removed reference to AudioToolbox.framework that's no longer needed
Feb 24 2011 - Manolo: architecture flags are not propagated to the fltk-config script.

+ 0
- 306
README.Unix.txt View File

@@ -1,306 +0,0 @@
README.Unix.txt - 2010-11-14 - Building FLTK on Unix
-----------------------------------------------------



CONTENTS
==========

1 INTRODUCTION
2 PREREQUISITES
2.1 Ubuntu 10
2.2 Linux Mint 9
2.3 Fedora 13
2.4 * http://www2.mandriva.com/
2.5 * http://www.opensuse.org/en/
2.6 * http://www.debian.org/
2.7 * Mandrake?
2.8 * Sun?
2.9 * SGI?
2.10 * HPUX?
3 HOW TO BUILD FLTK USING GCC
3.1 Prerequisites
3.2 Downloading and Unpacking
3.3 Configuring FLTK
3.4 Building FLTK
3.5 Testing FLTK
3.6 Installing FLTK
3.7 Creating new Projects
4 CREATING A NEW PROJECT IN CODE::BLOCKS
5 DOCUMENT HISTORY

* TODO: we still need to write these chapters



1 INTRODUCTION
=================

FLTK currently supports the following development environments on vmost Unix
platforms:

- gcc command line tools
- Code::Blocks
- ...
The Symbol font and the Zapf Dingbats font do not work on X11. This is correct
behavior for UTF-8 platforms.



2 PREREQUISITES
==================


2.1 Ubuntu 10
----------------

Ubuntu Linux can be downloaded here:

http://www.ubuntu.com/
If you have not done so yet, download and install Ubuntu.

Open a shell and install some software:

sudo apt-get install g++
sudo apt-get install gdb
sudo apt-get install subversion
sudo apt-get install autoconf
sudo apt-get install libx11-dev
sudo apt-get install libglu1-mesa-dev
These two are optional, but highly recommended:
sudo apt-get install libasound2-dev
sudo apt-get install libxft-dev

If you are planning to use the Code::Blocks IDE, also install this

sudo apt-get install codeblocks

I like to use subversion to install the latest FLTK-1.3.release:

svn co http://svn.easysw.com/public/fltk/fltk/branches/branch-1.3/ fltk-1.3
To update to the latest version, just go into the fltk-1.3 directory and type

svn update


2.2 Linux Mint 9
-------------------

Linux Mint 9 can be downloaded here:

http://www.linuxmint.com/
If you have not done so yet, download and install Linux Mint.

Open a shell and install some software:

sudo apt-get install g++
sudo apt-get install gdb
sudo apt-get install subversion
sudo apt-get install autoconf
sudo apt-get install libx11-dev
sudo apt-get install libglu1-mesa-dev
These two are optional, but highly recommended:
sudo apt-get install libasound2-dev
sudo apt-get install libxft-dev

If you are planning to use the Code::Blocks IDE, also install this

sudo apt-get install codeblocks

I like to use subversion to install the latest FLTK-1.3.release:

svn co http://svn.easysw.com/public/fltk/fltk/branches/branch-1.3/ fltk-1.3
To update to the latest version, just go into the fltk-1.3 directory and type

svn update

FIXME: no FL_SYMBOL font (-*-symbol-*), font 15 (Zapf-Dingbats)


2.3 Fedora 13
-------------------

Fedora 13 Linux can be downloaded here:

http://fedoraproject.org/
If you have not done so yet, download and install Fedora.

Open a terminal window and install some software. In Fedora, the default user
has no permission to call "sudo", so we will change user a few times:

su root
yum groupinstall "Development Tools"
yum groupinstall "X Software Development"

If you are planning to use the Code::Blocks IDE, also install this

yum install codeblocks.i686 (for 64 bit machines)

Don't forget to leave root status (Ctrl-D) before loading FLTK. To install FLTK
for every user, you either have to set root user again, or use "visudo" to add
yourself to the "sudo" list.

I like to use subversion to install the latest FLTK-1.3.release:

svn co http://svn.easysw.com/public/fltk/fltk/branches/branch-1.3/ fltk-1.3
To update to the latest version, just go into the fltk-1.3 directory and type

svn update

FIXME: no FL_SYMBOL font (-*-symbol-*), font 15 (Zapf-Dingbats)



3 HOW TO BUILD FLTK USING GCC
================================


3.1 Downloading and Unpacking
--------------------------------

Download FLTK from here:

http://www.fltk.org/software.php

If you are familiar with "subversion" and like to stay current with your
version, you will find the subversion access parameters at the bottom of that
page. Unpack FLTK into a convenient location. I like to have everything in my
dev directory:

cd
mkdir dev
cd dev
mv ~/Downloads/fltk-1.3.xxxx.tar.gz .
tar xvfz fltk-1.3.xxxx.tar.gz
cd fltk-1.3.xxxx

3.2 Configuring FLTK
-----------------------

Stay in your FLTK source-code directory. Type:
autoconf

Now configure your FLTK installation:

./configure
ADVANCED: type "./configure --help" to get a complete list of optional
configurations parameters. These should be pretty self-explanatory. Some
more details can be found in README.
:END_ADVANCED

The configuration script will check your machine for the required resources
which you should have installed as described in the Prerequisites chapter. Review
the Configuration Summary, maybe take some notes.


3.3 Building FLTK
--------------------

Now this is easy. Stay in your FLTK source-code directory and type:

make

The entire FLTK toolkit including many test programs will be built for you. No
warnings should appear. If some do, please let the FLTK developer team know via
the mailing list or the bug reporting template at www.fltk.org .

Actually, as of Oct 28 2010, quite a bunch of warnings will show, mostly about
suggested parenthesis. Please ignore them until we can fix them.


3.4 Testing FLTK
-------------------

After a successful build, you can test FLTK's capabilities:

test/demo


3.5 Installing FLTK
----------------------

If you did not change any of the configuration settings, FLTK will be installed
in "/usr/local/include" and "/usr/local/lib" by typing

sudo make install
If you are using the KDE, GNOME or XFCE desktop environments and want to call
"fluid" from the desktop menu, you will need to install additional files and
icons under "/usr/share" by typing:

sudo make install-desktop
It is possible to install FLTK without superuser privileges by changing the
installation path to a location within the user account by adding the
"--prefix=PREFIX" parameters to the "./configure" command.


3.6 Creating new Projects
----------------------------

FLTK provides a neat script named "fltk-config" that can provide all the flags
needed to build FLTK applications using the same flags that were used to build
the library itself. Running "fltk-config" without arguments will print a list
options. The easiest call to compile an FLTK application from a single source
file is:

fltk-config --compile myProgram.cxx

"fltk-config" and "fluid" will be installed in "/usr/local/bin/" by default. I
recommend that you add it to the command search path.



4 CREATING A NEW PROJECT IN CODE::BLOCKS
===========================================

Code::Blocks is a free and popular C++ IDE in the Linux world. It also runs on
OS X and MSWindows. Configured correctly, it can also cross-compile between
these platforms. This chapter focuses on creating a new FLTK project for Linux,
assuming that FLTK 1.3 was previously built and installed in its default
location from the command line.

If not done yet, install Code::Blocks as described in the Prerequisites chapter
above, or download it from their web site. This description is based on
version 10.05:

http://www.codeblocks.org/
Start Code::Blocks. Select File > New > Project. In the "New from template"
dialog box, click on "FLTK project" and follow the instructions.

The default project support basic fltk. If you would like to add support for
images, OpenGL, GLUT, or Forms, add the corresponding flags --use-images,
--use-gl, --use-glut, and --use-forms respectively.

The flags are located in the "Project Build Options" dialog. To change the
compiler flags, select your project in the tree view, then select the
"Compiler Settings" tab, then "Other Options" and add the flags to
`fltk-config --cxxflags` in front of the second "`".

The linker flags are located in the "Linker Settings" tab under "Other Linker
Options". Add the flags to `fltk-config --ldstaticflags` in front of the
second "`".



5 DOCUMENT HISTORY
=====================

Oct 30 2010 - matt: added Code::Blocks chapter
Oct 28 2010 - matt: restructured entire document and verified instructions
Nov 14 2010 - duncan: added install-desktop

Loading…
Cancel
Save