New build instructions for OS X users.

git-svn-id: file:///fltk/svn/fltk/branches/branch-1.3@7730 ea41ed52-d2ee-0310-a9c1-e6b18d33e121

3 files changed, 265 insertions, 70 deletions

diff --git a/README.OSX.txt b/README.OSX.txt
new file mode 100644
index 000000000..c0af43703
--- /dev/null
+++ b/README.OSX.txt
@@ -0,0 +1,263 @@
+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   Installing FLTK
+    3.7   Installing Little Helpers
+    3.8   Creating new Projects
+  4   DOCUMENT HISTORY
+
+
+ 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!    
+
+
+ HOW TO BUILD FLTK USING GCC
+=============================
+
+
+ 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.
+
+
+ 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 you 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
+  
+
+ 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-explenatory. 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.
+
+
+ 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" will complain about a few modules having no
+symbols. This is normal and can safely be ignored.
+
+(actually, as of Oct 23 2010, a handful of warnings related to string literals
+may appear, this is normal and will be fixed)
+
+
+ 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
+
+  sudo make install
+  
+It is possible to install FLTK without superuser previleges by changing the 
+installation path to a location within the user account by adding the 
+"--prefix=PREFIX" parameters 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
+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 XCODE3
+================================
+
+
+ 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
+  
+
+ 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 you version,
+you will find the subversion access parameters at the bottom of that page.
+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.
+
+
+ Configuring FLTK
+------------------
+
+Launch Xcode. Open the project file in 
+
+  .../fltk-1.3.xxxx/ide/Xcode3/FLTK.xcodeproj
+
+Use the "Project" pulldown menu to select the "Active Architecture" and
+"Active Build Configuration".
+  
+
+ Building FLTK
+---------------
+
+Use the "Project" pulldown menu to set the "Active Target" to "Demo". Select
+"Build" form the "Build" menu to create all libraries and test applications.
+
+All frameworks and apps will be loacted in "./ide/Xcode3/build/Debug/" or 
+"./ide/Xcode3/build/Release/".
+
+
+ Testing FLTK
+--------------
+
+Use the "Project" pulldown menu to set the "Active Target" to "Demo". Select
+"Build and Run" form the "Build" menu to run the Demo program. Use Demo to 
+explore all test programs.
+
+
+ Installing FLTK
+-----------------
+
+All FLTK frameworks should be copied from "./ide/Xcode3/build/Debug/" or 
+"./ide/Xcode3/build/Release/" to "/Library/Frameworks/". The matching header
+files must be copied from "./FL/" to "/usr/local/include/FL/".
+
+
+ Installing Little Helpers
+---------------------------
+
+Xcode can learn how to create FLTK projects for you. To add FLTK projects as a 
+new project template for Xcode 3, copy "./ide/Xcode3/Project Templates/" to
+"$(HOME)/Library/Application Support/Developer/Shared/Xcode/" and restart Xcode.
+
+FIXME: 
+Projects that are generated using this template expect fltk 1.3 as it is 
+installed using the command line. Also, you will need to add the 
+"AudioToolbox.framework" manually which is needed to create warning beeps.
+END OF FIXME.
+
+Xcode can also handle the .fl file extension to edit and compile Fluid resource
+files for you. The template project contains custom build rules for .fl files.
+
+Choose Xcode > Preferences to open Xcode's preferences window. There is a 
+toolbar at the top of the window with many buttons. Click the File Types button. 
+
+Create the file "Library/Application Support/Developer/Shared/Xcode/
+Specifications/fluid.pbfilespec" and add the following lines:
+  
+  {
+    Identifier = sourcecode.fluid;
+    BasedOn = sourcecode;
+    Extensions = (fl);
+  }
+
+
+ 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. You will need to add the "AudioToolbox.framework" 
+manually which is needed to create warning beeps.
+
+
+
+ DOCUMENT HISTORY
+==================
+
+Oct 24 2010 - matt: restructured entire document and verified instructions
diff --git a/README.mac b/README.mac
deleted file mode 100644
index b4388ab20..000000000
--- a/README.mac
+++ /dev/null
@@ -1,70 +0,0 @@
-README.mac - 2007-02-06 - Building FLTK under MacOS X
------------------------------------------------------
-
-CONTENTS
-
-    - Introduction
-    - How to Build Using GCC (MacOS X)
-    - Scripts
-    - Known MacFLTK bugs
-    - Test suite status
-    - Other stuff
-    - FLTK 1.0.x for Mac
-
-
-INTRODUCTION
-
-    FLTK currently supports the following development
-    environments on the MacOS X platform:
-
-	- GCC
-	- Metrowerks CodeWarrior
-	- (Apple Project Builder - future releases)
-	- (MPW - future releases)
-
-
-HOW TO BUILD USING GCC (MacOS X)
-
-    Since the MacOS X command line build environment is based on
-    BSD UNIX, the normal UNIX build procedure as described in
-    'README' applies.
-
-
-KNOWN MacFLTK BUGS
-
-    The following FLTK things are not implemented or don't work
-    at present:
-
-	- Line styles are not fully implemented.
-	- Sub-sub-subwindow not tested.
-	- The 'shiny' demo needs work (flush/aglFlush).
-
-UNIVERSAL BINARES
-
-    To create Universal Binaries for Tiger, start "configure"
-    with the following flags:
-      ./configure  --with-archflags="-mmacosx-version-min=10.4\
-                                     -arch i386 -arch ppc"
-
-OTHER STUFF
-
-    The creator ID's 'FLTK', 'Fltk', 'FLID', and 'Flid' are
-    officially registered with Apple Computers, Inc. and can be
-    used for FLTK applications ('FLTK') and FLUID files
-    ('Flid').
-
-    Under MacOS X, all windows are double-buffered. Using
-    Fl_Window has the same effect as using Fl_Double_Window on
-    other operating systems. Fl_Overlay_Window however uses one 
-    additional buffer for the overlay plane.
-
-
-FLTK 1.0.X FOR MAC
-
-    FLTK 1.0.6 for MacOS 8.x and OS 9.x is in beta stage and can
-    be downloaded from http://www.matthiasm.com/flMac.html .
-    The archive contains build files for Metrowerks CodeWarrior
-    5 and 6.
-
-    FLTK 1.0.6 for Mac is not supported by the FLTK team and
-    will not be further developed by the author.
diff --git a/ide/Xcode3/FLTK.xcodeproj/project.pbxproj b/ide/Xcode3/FLTK.xcodeproj/project.pbxproj
index 9eb0b9875..5b9072fa9 100644
--- a/ide/Xcode3/FLTK.xcodeproj/project.pbxproj
+++ b/ide/Xcode3/FLTK.xcodeproj/project.pbxproj
@@ -4247,6 +4247,7 @@
 		C7C5A11DD7448F61DFC69398 /* glpuzzle.cxx */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.cpp.cpp; name = glpuzzle.cxx; path = ../../test/glpuzzle.cxx; sourceTree = SOURCE_ROOT; };
 		C84F99F5AC8C6517F45055B0 /* jdmerge.c */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.c; name = jdmerge.c; path = ../../jpeg/jdmerge.c; sourceTree = SOURCE_ROOT; };
 		C8AE10A8DDF53B8B27E3215A /* Fl_Choice.H */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.cpp.h; name = Fl_Choice.H; path = ../../FL/Fl_Choice.H; sourceTree = SOURCE_ROOT; };
+		C9EDD143127338F600ADB21C /* README.OSX.txt */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = text; name = README.OSX.txt; path = ../../README.OSX.txt; sourceTree = SOURCE_ROOT; };
 		C9F1464F0E6A4DCD77AF72B8 /* Fl_Function_Type.cxx */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.cpp.cpp; name = Fl_Function_Type.cxx; path = ../../fluid/Fl_Function_Type.cxx; sourceTree = SOURCE_ROOT; };
 		CAEC632CEFC2CA7592EF9D74 /* image.app */ = {isa = PBXFileReference; explicitFileType = wrapper.application; includeInIndex = 0; path = image.app; sourceTree = BUILT_PRODUCTS_DIR; };
 		CB23A4CE90D5A89FA2640A78 /* label.app */ = {isa = PBXFileReference; explicitFileType = wrapper.application; includeInIndex = 0; path = label.app; sourceTree = BUILT_PRODUCTS_DIR; };
@@ -5399,6 +5400,7 @@
 		2000E0C1AD91ACA63811D339 = {
 			isa = PBXGroup;
 			children = (
+				C9EDD143127338F600ADB21C /* README.OSX.txt */,
 				5D444464FCF5714805936107 /* Applications */,
 				188555DBC553F66588792C6B /* Frameworks */,
 				015D2BD894993395B263D6C0 /* Tests */,