callable

This is an old revision of the document!

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.

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 Client Development page.

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.

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:

• 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 configuration path allowing to combining several configuration sources with user's individual settings.

Further methods:

• set_application("APPNAME") loads the given application, if necessary, and makes it the current one
• 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.
• newScope() create an instance of polymake::perl::Scope .
• include("RULE_FILE") parses one additional rule file in the context of the current application. See the corresponding interactive command include() .
• 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 the clients too. An instance of class polymake::perl::Scope represents (by its mere lifespan) one execution cycle within the polymake session. At the end of the cycle (when an instance of polymake::perl::Scope gets destroyed), some cleanup actions may occur; most important ones are discarding temporary properties from the Objects and restoring the preferences temporarily modified by prefer_now. In the interactive running mode, one execution cycle comprises the evaluation of one complete input line. In the callable library mode, however, there are no natural cyclic events which can be used to perform the cleanup. Therefore, if you expect your program to run for longer time and work with many polymake Objects, you should consider regular creation of polymake::perl::Scope instances with limited lifespan. The only available way to create a polymake::perl::Scope instance is the method Main::newScope(); the instances are not copyable nor assignable. If you create several polymake::perl::Scope instances, their lifespans must be properly nested, that is, the one born last has to die first. Violation of this rule leads to immediate program termination. Methods: • prefer_now("label") corresponds to the interactive command of the same name. • set_custom("name", value) temporarily changes the value of the given custom variable, until the Scope object is destroyed. Custom variables are specified in the same manner as in corresponding Main::set_custom methods. 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.

Following configuration parameters can be requested from polymake-config:

• --cc
the C++ compiler which was used to build polymake itself
• --cflags
options for the C++ compiler without header search paths
• --includes
• --ldflags
options for the linker (such as library search paths and machine architecture)
• --libs