README

/***********************************************************************
 * Created by Andreas Paffenholz on 04/18/12.
 * Copyright 2012-2014 by Andreas Paffenholz.
 
 * This program is free software; you can redistribute it and/or modify it
 * under the terms of the GNU General Public License as published by the
 * Free Software Foundation; either version 2, or (at your option) any
 * later version: http://www.gnu.org/licenses/gpl.txt.
 
 * This program 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 General Public License for more details.
 *
 * README
 * PolyViewer
 **************************************************************************/

PolyViewer is a simple reader for files created by polymake (polymake.org) 
released under the GPL.


** BINARY DISTRIBUTION **

A first attempt for a binary distribution can be downloaded at

http://polymake.org/polytopes/paffenholz/data/polymake/mac/PolyViewer.dmg

Follow the instructions given in the INSTALL file contained in the dmg. 
This binary build is still **very** experimental (and the app still has many shortcomings I hope to fix soon). 
Please report any problems you encounter!


** COMPILING THE PROJECT **

Building and running PolyViewer requires that 
  
  libpolymake.2.12.dylib and libpolymake-apps.2.12.dylib

can be found. Further, the gmp headers are needed during compilation (during run time, 
libpolymake knows how to find them). So, in particular, you will have to install polymake first.

For building the app you will have to edit the file 

polymake.xcconfig

found in the root folder. Edit appropriately or use the run script
found under "Build Phases" by uncommenting all lines starting with "echo". This
requires that "polymake-config" can be found in your path. If this is not in a standard place, add

export PATH=$PATH:/path/to/your/polymake-config

to the file 

.bash_profile

in your $HOME folder.

-------------
  
The PolyViewer project now provides a simple interface to the extension 
"poly_db" of polymake written by Silke Horn (see github) to acces the 
polymake database. To use it you most likely have to adjust some search paths. 

During installation of poly_db for polymake you have been asked to install the
perl modules MongoDB, boolean, and Tie-IxHash. To use poly_db with PolyViewer 
we have to add these paths to the launch deamon. Do the following:

1) Find out whether there are already perl libraries loaded (As launchd does not resolve 
    enviroment variables we can't use the standard trick to add $PERL5LIB to the newly set path.). 
    So in a terminal do

launchctl getenv PERL5LIB

    Remember its value (and maybe also write it down somewhere in case you want to remove the 
    additions necessary for PolyViewer).

2) launchd currently does not read locally defined configuration files (see the launchd man page). 

     There are two ways around this nuisance:

     a) If you have sudo rights: Edit (or create, if it is not present) the file /etc/launchd.conf and add

setenv PERL5LIB <path-to>/perl-modules/lib/perl5/darwin-thread-multi-2level:<path-to>MongoDB-0.702.2/lib:<path-to>/boolean-0.30/lib/:<path-to>/Tie-IxHash-1.23/lib/:<path-to>/perl5/site_perl/5.16.2/darwin-thread-multi-2level/

        Adjust the paths by replacing <path-to> with the appropriate value. Also adjust the version numbers if necessary. 
        If in step 1) you found that PERL5LIB is already set, then add this to the above!


     b) If you do not have sudo rights, or you don't want to use them:
     
        i)  in your home folder, do

mkdir ~/.polyviewer
echo "#!/bin/sh" > ~/.polyviewer/launchd-setenv
echo "eval \"launchctl setenv PERL5LIB <path-to>/perl-modules/lib/perl5/darwin-thread-multi-2level:<path-to>MongoDB-0.702.2/lib:<path-to>/boolean-0.30/lib/:<path-to>/Tie-IxHash-1.23/lib/:<path-to>/perl5/site_perl/5.16.2/darwin-thread-multi-2level/\" " >> ~/.polyviewer/launchd-setenv
chmod a+x ~/.polyviewer
chmod a+x ~/.polyviewer/launchd-setenv

            Again remember to adjust the paths and the version numbers, and to add any other PERL5LIB paths you found in step 1)!
           
        ii) Inside the directory ~/Library/LaunchAgents create a file com.github.apaffenholz.PolyViewer.plist and place the following lines into it:
        
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
        <key>EnableGlobbing</key>
        <true/>
        <key>Label</key>
        <string>com.github.apaffenholz.PolyViewer</string>
        <key>KeepAlive</key>
        <false/>
         <key>ProgramArguments</key>
        <array>
                <string>sh</string>
                <string>-c</string>
                <string>~/.polyviewer/launchd-setenv</string>
         </array>
        <key>RunAtLoad</key>
        <true/>
    </dict>
</plist>

             Make this file executable with
             
chmod a+x ~/Library/LaunchAgents/com.github.apaffenholz.PolyViewer.plist


3) In any case you will have to restart your computer to reload the launch demon, or set the variables temporarily by executing

launchctl setenv PERL5LIB <mod paths>

where <mod paths> should be the list of paths to the perl modules used above. The effect of this command is lost with the next restart.


4) If you know of any better way to set PERL5LIB for a gui app it would be nice if you tell me!

-------------

PolyViewer now partially supports computation of new properties: 

- right click on any property at the same level as the one you want to 
    compute and choose "Compute property". Enter the property you want to have.
- right click on a property with subproperties and choose "Add subproperty to object" and
    enter the name of a property you want to add to the current subproperty

This currently only works for non-object properties. As a workaround 
to add e.g. a Hasse diagram enter "HASSE_DIAGRAM.ADJACENCY" 
(or any other property of the Hasse diagram you are interested in).
Any string the polymake command "give" accepts that does not return a perl::Object should work.

Note that for technical reasons the interface currently does not immediately select the new
property in the window (polymake might add further properties during the computation, so
we have to initiate a complete reload of the properties and loose track of the current one).


--------------

Acknowledgements:
Silke Horn has contributed several pieces of code for this app, has developed the polymake database extension
that this app interfaces (see her github page) and has contributed the nice icons for polymake data files!

A more thorough integration of the polymake database into this app is planned.


--- 

internal notes

- including libpolymake requires
  - appropriate compiler/linker flags
  - the preprocessor macro: __ASSERT_MACROS_DEFINE_VERSIONS_WITHOUT_UNDERSCORES=0 to avoid conflicts with functions starting with two underscores:
     full quote from AssertMacros.h
     *	A future release of Mac OS X will no longer do this, and will require that clients move to the
     *  new macros as defined above.  However, in the interim both the new and old macros will work, unless
     *  clients define a macro __ASSERT_MACROS_DEFINE_VERSIONS_WITHOUT_UNDERSCORES before this file is included
     *  in their compilations.  Clients who do not want the older macros defined can accomplish this by adding
     *    #define __ASSERT_MACROS_DEFINE_VERSIONS_WITHOUT_UNDERSCORES 0
     *  at the top of their sources, or my adding -D__ASSERT_MACROS_DEFINE_VERSIONS_WITHOUT_UNDERSCORES=0 to the
     *  gcc compilation options.