Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision
Previous revision
callable [2012/03/28 12:16]
gawrilow [Main class]
callable [2019/02/12 13:22] (current)
gawrilow [Building a program]
Line 1: Line 1:
 ===== Callable Library ===== ===== Callable Library =====
  
-Starting with release 3.0, polymake ​will offer an alternative interface for integration with other software, a C++ callable library.  Developers having access to SVN snapshots can start using it right now.+polymake ​offers ​an alternative interface for integration with other software, a C++ callable library.
  
-This page describes only those parts of the interface which are specific to the callable library. ​ Software collaborating with polymake may (and in most cases even have to) use the Object and Function interfaces too; they are described on the [[:reference:​clients|Client Development page]].+This page describes only those parts of the interface which are specific to the callable library. ​ Software collaborating with polymake may (and in most cases even have to) use the Object and Function interfaces too; they are described on the [[user_guide:extend:​clients|Client Development page]]. 
 + 
 +Benjamin Lorenz gave a [[http://​polymake.org/​lib/​exe/​fetch.php/​cal_pres.pdf|presentation]] on the callable library with [[http://​polymake.org/​lib/​exe/​fetch.php/​callable.tbz|examples]].
  
 ==== Main class ==== ==== Main class ====
  
-The polymake as a library must be initialized by creating an instance of class ''​polymake::​Main''​. ​ This class is declared in the header ''​Main.h''​ .  Special precaution prevents including this header in the polymake clients, it's designed exclusively for external ​programs.+The polymake as a library must be initialized by creating an instance of class ''​polymake::​Main''​. ​ This class is declared in the header ''​polymake/Main.h''​ .  Special precaution prevents including this header in the polymake clients, it's designed exclusively for standalone ​programs.
  
 An instance of the class ''​polymake::​Main''​ is an empty placeholder,​ whose sole purpose is to pull the whole polymake machine into memory and make it ready to serve your requests. ​ You can create as many instances as you please; important is only the chronologically first one.  If you have linked your application with ''​libpolymake'',​ polymake will stay loaded until the very termination of your program; hence if you want to be able to completely unload the polymake library from memory during the runtime, you should use explicit dynamic loader functions ''​dlopen''​ and ''​dlclose''​ (under Linux; MacOS equivalents exist as well but have substantially longer names). An instance of the class ''​polymake::​Main''​ is an empty placeholder,​ whose sole purpose is to pull the whole polymake machine into memory and make it ready to serve your requests. ​ You can create as many instances as you please; important is only the chronologically first one.  If you have linked your application with ''​libpolymake'',​ polymake will stay loaded until the very termination of your program; hence if you want to be able to completely unload the polymake library from memory during the runtime, you should use explicit dynamic loader functions ''​dlopen''​ and ''​dlclose''​ (under Linux; MacOS equivalents exist as well but have substantially longer names).
  
 ''​polymake::​Main''​ has one constructor:​ ''​polymake::​Main''​ has one constructor:​
-  * ''​%%Main(user-settings = "​user"​)%%''​ \\ where //​user-settings//​ is a string encoding whether and where the user settings like custom variables or results of rule auto-configuration are retrieved from.  The default value is ''​%%"​user"​%%'',​ which causes the standard settings for the interactive mode to come into effect (usually stored under ''​~/​.polymake''​). ​ Other possible values are ''​%%"​none"​%%''​ for "no configuration at all" or a [[howto:​configure|configuration path]] allowing to combining ​several configuration sources with user's individual settings.+  * ''​%%Main(user-settings = "​user"​)%%''​ \\ where //​user-settings//​ is a string encoding whether and where the user settings like custom variables or results of rule auto-configuration are retrieved from.  The default value is ''​%%"​user"​%%'',​ which causes the standard settings for the interactive mode to come into effect (usually stored under ''​~/​.polymake''​). ​ Other possible values are ''​%%"​none"​%%''​ for "no configuration at all" or a [[install:​configure|configuration path]] allowing to combine ​several configuration sources with user's individual settings.
  
 Further methods: Further methods:
Line 18: Line 20:
   * ''​%%set_application_of(Object)%%'' ​ sets the current application to that one where the type of the given object is defined   * ''​%%set_application_of(Object)%%'' ​ sets the current application to that one where the type of the given object is defined
   * ''​%%add_extension("​DIRECTORY"​)%%''​ loads the extension rooted in the given directory. ​ Repeated calls with the same path have no effect.   * ''​%%add_extension("​DIRECTORY"​)%%''​ loads the extension rooted in the given directory. ​ Repeated calls with the same path have no effect.
-  * ''​newScope()''​ create an instance of ''​[[:reference:callable#​scope_class|polymake::​perl::​Scope]]''​ . +  * ''​newScope()''​ create an instance of ''​[[callable#​scope_class|polymake::​perl::​Scope]]''​ . 
-  * ''​%%include("​RULE_FILE"​)%%''​ parses one additional rule file in the context of the current application. See the corresponding interactive command ''​[[http://​polymake.mathematik.tu-darmstadt.de/​release_docs/core.html#i185|include()]]''​ .+  * ''​%%include("​RULE_FILE"​)%%''​ parses one additional rule file in the context of the current application. See the corresponding interactive command ''​[[reldocs>​latest/core.html#include|include()]]''​ .
   * ''​%%set_preference("​label"​)%%''​ \\ ''​%%reset_preference("​label"​)%%''​ correspond to the interactive commands of the same names.   * ''​%%set_preference("​label"​)%%''​ \\ ''​%%reset_preference("​label"​)%%''​ correspond to the interactive commands of the same names.
-  * ''​%%set_custom("​name",​ value)%%''​ \\ ''​%%reset_custom("​name"​)%%'' ​ allow to change values of custom variables. ​ The variable names must be specified fully qualified (unless they reside in the current application package) and with appropriate leading symbol designating its perl type, that is, ''​$''​ for scalars, ''​@''​ for arrays, and ''​%''​ for hash maps.  Note that ''​get_custom()''​ is now a free function available for [[reference:​clients|clients]] too.+  * ''​%%set_custom("​name",​ value)%%''​ \\ ''​%%reset_custom("​name"​)%%'' ​ allow to change values of custom variables. ​ The variable names must be specified fully qualified (unless they reside in the current application package) and with appropriate leading symbol designating its perl type, that is, ''​$''​ for scalars, ''​@''​ for arrays, and ''​%''​ for hash maps.  Note that ''​get_custom()''​ is now a free function available for [[user_guide:​extend:clients#​miscellaneous_functions|clients]] too
 +  * ''​%%greeting(int verbose = 2)%%''​ return the polymake greeting as ''​std::​string''​ with different verbosity levels (0-2): just name + version, with copyright added and including the GPL notice.
  
 ==== Scope class ==== ==== Scope class ====
Line 39: Line 42:
 ==== Building a program ==== ==== Building a program ====
  
-You can use polymake callable library for building your programs only after havong ​installed it at the final destination,​ that is, after ''​make install''​ .  To facilitate the build process, polymake comes with a small utility ''​polymake-config''​ which resides side by side with the main script ''​polymake''​ in the binary installation directory. ​ Calling this utility with various options you can obtain the compiler and linker options needed for successful build of your program. ​ You can even insert the calls in your Makefile directly, using the GNU make ''​$(shell)''​ function or `backtick` shell substitution.+You can use polymake callable library for building your programs only after having ​installed it at the final destination,​ that is, after ''​ninja install''​ .  To facilitate the build process, polymake comes with a small utility ''​polymake-config''​ which resides side by side with the main script ''​polymake''​ in the binary installation directory. ​ Calling this utility with various options you can obtain the compiler and linker options needed for successful build of your program. ​ You can even insert the calls in your Makefile directly, using the GNU make ''​$(shell)''​ function or `backtick` shell substitution.
  
 Following configuration parameters can be requested from ''​polymake-config'':​ Following configuration parameters can be requested from ''​polymake-config'':​
Line 49: Line 52:
   * ''​%%--version%%''​ \\ tells the version of polymake as installed on your system   * ''​%%--version%%''​ \\ tells the version of polymake as installed on your system
  
-You can add an option ''​%%--debug%%''​ before ''​%%--cflags%%'',​ ''​%%--ldflags%%'',​ or ''​%%--libs%%''​ if you are going to debug your program together with polymake. ​ Compiler options displayed without ''​%%--debug%%''​ provide for a build optimized for execution speed. 
  
 Please note that the options displayed by ''​%%--cflags%%''​ are more kind of a suggestion, you are free to change or omit most of them.  Two options are mandatory, however: ''​%%-DPOLYMAKE_DEBUG={0,​1}%%''​ (which controls a plenty of consistency checks in polymake library data structures) and ''​%%-fPIC%%''​ (or similar option, depending on your compiler, which provides for emitting a position-independent binary code). ​ If you omit the latter one, data transfer between C++ and perl worlds, in particular all ''​give()''​ and ''​take()''​ methods, will not work properly in your program. Please note that the options displayed by ''​%%--cflags%%''​ are more kind of a suggestion, you are free to change or omit most of them.  Two options are mandatory, however: ''​%%-DPOLYMAKE_DEBUG={0,​1}%%''​ (which controls a plenty of consistency checks in polymake library data structures) and ''​%%-fPIC%%''​ (or similar option, depending on your compiler, which provides for emitting a position-independent binary code). ​ If you omit the latter one, data transfer between C++ and perl worlds, in particular all ''​give()''​ and ''​take()''​ methods, will not work properly in your program.
 +
 +=== Debugging ===
 +
 +You can add an option ''​%%--debug%%''​ before ''​%%--cflags%%'',​ ''​%%--ldflags%%'',​ or ''​%%--libs%%''​ if you are going to debug your program together with polymake. ​ Compiler options displayed without ''​%%--debug%%''​ provide for a build optimized for execution speed.
 +
 +
  • callable.1332936982.txt.gz
  • Last modified: 2014/01/03 15:45
  • (external edit)