fltkhs 0.5.0.2 → 0.5.0.3

raw patch · 2 files changed

+21/−241 lines, 2 filesPVP ok

version bump matches the API change (PVP)

API changes (from Hackage documentation)

Files

• fltkhs.cabal +1/−1
• src/Graphics/UI/FLTK/LowLevel/FLTKHS.hs +20/−240

@@ -1,5 +1,5 @@ name : fltkhs-version : 0.5.0.2+version : 0.5.0.3 synopsis : FLTK bindings description:     Low level bindings for the FLTK GUI toolkit. For installation and quick start instruction please scroll all the way down to the README.

@@ -313,7 +313,7 @@ -- This means using Fluid in a FLTKHS project is as simple as creating a Fluid -- interface and running 'cabal build' or 'cabal install'. ----- Additionally the <http://hackage.haskell.org/package/fltkhs-fluid-demos fltkhs-fluid-demos> package+-- Additionally the <https://github.com/deech/fltkhs-fluid-demos fltkhs-fluid-demos> package -- comes with a number of demos that show off how Fluid integrates with FLTKS. -- @@ -482,17 +482,12 @@ -- It should build and install smoothly with the standard: -- -- @--- > ./configure --enable-shared+-- > ./configure --enable-gl --enable-shared --enable-localjpeg --enable-localzlib --enable-localpng -- > make -- > sudo make install -- @ ----- If you are customizing the `configure` step it is important to at least enable shared libraries, OpenGL and Cairo like so: ----- @--- > ./configure --enable-shared --enable-gl--- @--- -- If you didn't install FLTK from source you can use the 'fltk-config' tool to ensure that version 1.3.4-1 is installed: -- -- @@@ -639,7 +634,7 @@  -- $InstallationWindows10 ----- This install guide has been tested on a Windows 10, Thinkpad T450 w/ 16GB RAM.+-- This install guide has been tested on a Windows 10 and Windows 8. -- -- == Install Stack -- Downloading and following the default instructions for the standard <https://www.stackage.org/stack/windows-x86_64-installer Windows installer> should be enough.@@ -662,13 +657,14 @@ -- @ -- -- == Install Necessary Utilities via Pacman--- In the MSYS2 shell prompt do+-- In the MSYS2 shell prompt update and upgrade the MSYS2 installation: -- -- @--- > pacman -Syy # updates the repos to pull the latest snapshot+-- > pacman -Syy+-- > pacmay -Syu -- @ ----- Now we need packages for download and extracting packages:+-- ... install packages for download and extracting packages: -- -- @ -- > pacman -S wget@@ -690,7 +686,7 @@ -- Download the latest stable build of FLTK: -- -- @--- > wget --no-check-certificate http://www.fltk.org/software.php?VERSION=1.3.4-1&FILE=fltk/1.3.4-1/fltk-1.3.4-1-source.tar.gz+-- > wget --no-check-certificate http://fltk.org/pub/fltk/1.3.4/fltk-1.3.4-1-source.tar.gz -- @ -- -- Untar the FLTK archive and enter the directory:@@ -716,7 +712,7 @@ -- @ -- -- == Download And Install The FLTKHS Hello World Skeleton--- The <https://github.com/deech/fltkhs-hello-world fltkhs-hello-world> skeleton is a simple Hello World GUI which provides the base structure for your application. Please see the 'Demos' section of this document for examples of apps that show off more complex uses of the API.+-- The <https://github.com/deech/fltkhs-hello-world fltkhs-hello-world> skeleton is a simple Hello World GUI which provides the base structure for FLTKHS applications. Please see the 'Demos' section of this document for examples of apps that show off more complex uses of the API. -- -- @ -- > wget --no-check-certificate https://github.com/deech/fltkhs-hello-world/archive/master.zip@@ -731,17 +727,16 @@ -- > stack install -- @ ----- To test your installation do:+-- To test the installation: -- -- @ -- > stack exec fltkhs-hello-world -- @ ----- And you're off and running! -- -- == Packaging A Windows Executable ----- While the 'fltkhs-hello-world' application you built above is mostly stand-alone the MSYS2 environment bundled with 'stack' seems to require 3 runtime DLLs. The DLLs are bundled with 'stack' so it's easy to zip them up with the executable and deploy. The required DLLs are: 'libstdc++-6.dll', 'libgcc_s_seh-1.dll' and 'libwinpthread-1.dll'.+-- While the 'fltkhs-hello-world' application is mostly stand-alone the MSYS2 environment bundled with 'stack' seems to require 3 runtime DLLs. The DLLs are bundled with 'stack' so it's easy to zip them up with the executable and deploy. The required DLLs are: 'libstdc++-6.dll', 'libgcc_s_seh-1.dll' and 'libwinpthread-1.dll'. -- -- --@@ -775,235 +770,20 @@ -- And that's it! Any Windows 10 user should now be able to extract 'fltkhs-hello-world.zip' and run 'fltkhs-hello-world.exe'. -- --- $InstallationWindows7------ This install guide has been tested on Windows 7 64-bit with 8GB of RAM.--------- The general steps involved are:------  - Install <http://repo.msys2.org/distrib/x86_64/msys2-x86_64-20150916.exe MSYS2>---  - Install <http://www.cmake.org/files/v3.2/cmake-3.2.1-win32-x86.exe CMake>---  - Install 'make' via MSYS2.---  - Install <https://www.stackage.org/stack/windows-x86_64-installer Stack>---  - Download the <https://github.com/deech/fltkhs-hello-world/archive/master.tar.gz FLTKHS hello world skeleton>---  - Download & compile <http://www.fltk.org/software.php?VERSION=1.3.4-1&FILE=fltk/1.3.4-1/fltk-1.3.4-1-source.tar.gz FLTK 1.3.4-1>---  - Build & install the FLTKHS hello world skeleton project.---  - Verify the install by running `fltkhs-hello-world`------ This install process is certainly not smooth and there are a number of steps--- that the user find mysterious and wonder why it is necessary. Each step below--- starts off with the instructions, followed by a sentence or two that explains--- why it is necessary.------ == Install MSYS2--- MSYS2 installers are available--- <http://repo.msys2.org/distrib/x86_64/msys2-x86_64-20150916.exe here>. Just--- clicking through the installer wizard should be sufficient.------ MSYS2 provides a much nicer development environment compared to the standard--- Windows CMD prompt. Additionally the install process needs some tools that are--- easy to install via 'pacman', the package manager that ships with MSYS2.------ == Install CMake--- Simply click through the--- <http://www.cmake.org/files/v3.2/cmake-3.2.1-win32-x86.exe CMake> installer with--- the default options. Once this process is complete the `cmake` executable should--- be available at the MSYS2 prompt:------ @--- > cmake --version--- cmake version 3.2.1--- @------ On Windows, CMake is used to generate Makefiles. Yes, CMake is available via--- 'pacman' but unfortunately that version (as of this writing) does not have the--- "MSYS Makefiles" generator required by the install process.------ == Install GNU Make--- The following should just work at the MSYS prompt:------ @--- > pacman -S make--- @------ GNU Make is required to build both FLTK and the C files in this package.------ == Install Stack--- The default installation of--- <https://www.stackage.org/stack/windows-x86_64-installer Stack> should also just--- work.------ == Download the FLTKHS Hello World Skeleton--- The latest version of the skeleton is available--- <https://github.com/deech/fltkhs-hello-world/archive/master.tar.gz here>.------ Extract it via MSYS as follows:------ @--- > pacman -S tar--- > pacman -S gzip--- > cd \<your-download-location\> # This is usually \/C\/Users/\<username\>\/Downloads--- > tar -zxvf master.tar.gz--- > mv fltkhs-hello-world-master fltkhs-hello-world--- @------ There should now be a directory called 'fltkhs-hello-world' in the current--- directory. We will need the path to this directory for the next step.------ Why is a skeleton project necessary? In the 'stack' world simply installing a--- library globally does not work since each package is pinned down to a resolver,--- GHC version etc. So in order to build this package we need to build and install--- a package that depends on it. This skeleton is also the preferred way to get--- started with a plain FLKTHS project, so two birds with one stone and all that ...--------- == Download & compile FLTK-1.3.4-1--- Please make sure to only download version--- <http://www.fltk.org/software.php?VERSION=1.3.4-1&FILE=fltk/1.3.4-1/fltk-1.3.4-1-source.tar.gz FLTK 1.3.4-1>.------ If you haven't already installed 'tar' and 'gzip' at the MSYS prompt do:------ @--- > pacman -S tar--- > pacman -S gzip--- @------ Extract the archive:------ @--- > cd \<your-download-location\> # This is usually \/C\/Users/\<username\>\/Downloads--- > tar -zxvf fltk-1.3.4-1-source.tar.gz--- @------ Then descend into the source directory:------ @--- > cd fltkh-1.3.4-1-source--- @------ Make a build directory to hold the generated CMake files:------ @--- > mkdir build--- @------ Descend into the `build` directory:------ @--- > cd build--- @------ And run `cmake` via `stack`:------ @--- > stack exec cmake -- -DOPTION_BUILD_SHARED_LIBS=On .. -G "MSYS Makefiles"--- @------ If you are confused about the 'STACK_YAML' environment variable please see the "GHC 7.10.3 And Beyond (Windows Only)" in the "Obstacles" section above.------ Running the rest of the command via 'stack exec' gives 'cmake' access to the C/C++ compilers bundled with GHC.------ Please note the `..` after `-DOPTION_BUILD_SHARED_LIBS=On` in the command.--- This is important because it tells CMake to build using the CMake specification--- found in the parent directory.------ Once these steps have been completed you should be able to compile the source:------ @--- > make--- @--------- Each compile step may spit out a scary looking warning about a pointer cast,--- but this can be safely ignored. In the logic that sets up callbacks, FLTK casts--- a 'long' argument to a '(void *)'. It can be ignored because it doesn't seem to--- break anything.------ Compiling and linking on an 8GB machine seems to take about 5-6 minutes.------ Also, the final demo may fail to compile and complain about a symbol being--- redefined. This is again an issue with MinGW and can be safely ignored.------ Now it is necessary to define the `FLTK_HOME` environment variable so this package knows where to look for header and library files:------ @--- > export FLTK_HOME=\<path-to-the-FLTK-root-directory\>--- @------ Why install from scratch? The user might have noticed that 'fltk' is--- available via 'pacman' and wonder why we are building it ourselves and setting--- some arbitrary environment variable to point to the location of the headers and--- libraries. The issue is that for some reason CMake can't see the header files--- and libraries when installed via 'pacman'. The linker throws weird errors about--- types being defined in two places. The issue magically disappears when--- installing from scratch and it's pretty easy to do. It's not ideal and we're--- working on removing this step but for now this is the workaround.------ == Install this package------ At this point return to the directory containing the skeleton FLTKHS--- application. If it was left in the 'Downloads' folder this should get back to--- it:------ @--- > cd \/C\/Users\/\<username\>\/Downloads\/fltkhs-hello-world--- @------ Now we can to build it:------ @--- > stack setup--- > stack install--- @--- If you are confused about the 'STACK_YAML' environment variable please see the "GHC 7.10.3 And Beyond (Windows Only)" in the "Obstacles" section above.------ __Note__: Installing FLTKHS takes a *long* time, almost 15 minutes on the--- Windows 7, 8GB RAM test machine. The install will just sit at the `configure`--- and `build` step with no feedback. This is happening because 1. the MinGW C\/C++--- compiler are way slower than gcc\/g++ and 2. the C2HS preprocess step seems to--- take at least 3x as long on Windows. You only have to do this once (hopefully).--- Please be patient.--------- == Verify The Install------ If all goes well there should be an incredibly unimpressive executable 'fltkhs-hello-world' in the 'stack' path. It can be invoked like:------ @--- > stack exec fltkhs-hello-world--- @---- -- $Demos ----- __Update__: As of 0.4.0.7 the <http://github.com/deech/fltkhs-demos FLTKHS demos> and the--- <http://github.com/deech/fltkhs-fluid-demos FLUID demos> will only be updated on Github.--- It is a chore to keep the versions of the demos on Hackage in sync with the proper version--- of <http://hackage.haskell.org/package/fltkhs FLTKHS> and Stack makes them easier--- to install (and play with ) than with Cabal.------ __Update__: As of version 0.4.0.1 all the demos have been moved to their own--- package <http://hackage.haskell.org/package/fltkhs-demos fltkhs-demos>. This speeds--- up installation of this package significantly and also allows the examples to--- be run interactively with `cabal repl`. This was an issue pre-0.4.0.1 because--- the REPL needed to link against the C library containing the C++ bindings and--- was having trouble finding it because it was just created by the Cabal build--- step but not yet installed. This seems like a better solution than hacking--- @Setup.hs@ to make the library visible.------ There are currently two sets of FLTKHS demos, the ones that are part of the--- <http://hackage.haskell.org/package/fltkhs-demos fltkhs-demos> package and ones that--- show off <http://hackage.haskell.org/package/fltkhs-fluid-demos Fluid>--- support.+-- FLTKHS has a almost 25 end-to-end demo applications to help the user get started. They are+-- split into two sets, those <http://github.com/deech/fltkhs-demos written manually> and those+-- that <http://github.com/deech/fltkhs-fluid-demos show how to use FLUID>. ----- Please see the README in the <http://hackage.haskell.org/package/fltkhs-demos fltkhs-demos> package for more information.+-- The READMEs in the repos have installation instructions but they assume that the user has+-- successfully installed FLTK and the 'fltkhs-hello-world' app (see platform specific instructions above). --  -- $GettingStarted -- -- It is assumed that by this point the user has successfully installed this--- library and demos in <http://hackage.haskell.org/package/fltkhs-demos fltkhs-demos> (see+-- library and demos in <http://github.com/deech/fltkhs-demos fltkhs-demos> (see -- above). -- --@@ -1218,12 +998,12 @@ -- runtime performance issues. This is only a compile time problem. -- -- To preserve the user's and the author's sanity a flag `fastCompile` has been--- introduced to the <http://hackage.haskell.org/package/fltkhs-demos fltkhs-demos> and--- to the <http://hackage.haskell.org/package/fltkhs-fluid-demos fltkhs-fluid-demos>.+-- introduced to the <https://github.com/deech/fltkhs-demos fltkhs-demos> and+-- to the <https://github.com/deech/fltkhs-fluid-demos fltkhs-fluid-demos>. -- This flag which tells the compiler to skip the specialising step when -- compiling executables, dramatically decreases compile time but also bloats -- the resulting executable size and probably makes runtime performance much--- slower. In this package and <http://hackage.haskell.org/package/fltkhs-fluid-demos fltkhs-fluid-demos>+-- slower. In this package and <https://github.com/deech/fltkhs-fluid-demos fltkhs-fluid-demos> -- it is enabled by default, since the executables are just -- demos that are not meant to show off performance. To disable this flag, tell -- Stack to ignore it during the `build` step: