user_guide:extend:extensions

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
reference:extensions [2016/03/23 14:46] hampeuser_guide:extend:extensions [2021/01/12 15:38] (current) – external edit 127.0.0.1
Line 7: Line 7:
   * C++ clients and class libraries   * C++ clients and class libraries
  
-//**Note**//\\ Extension management has been completely reworked prior to polymake snapshot version 2.12.4.  All commands and procedures depicted below are only applicable to this snapshot or later releases.  Please refer to the older version of this page for description pertaining to polymake 2.12 or earlier. 
  
 ===== Starting an own extension ===== ===== Starting an own extension =====
Line 27: Line 26:
  
 To create a really new application from scratch, execute the command\\ ''%%found_application "~/my_ext", "APP_NAME";%%'' \\ To create a really new application from scratch, execute the command\\ ''%%found_application "~/my_ext", "APP_NAME";%%'' \\
-Again, it will create a folder hierarchy rooting at ''my_ext/apps/APP_NAME'' After having composed the rules and/or clients, you may include the ''APP_NAME'' in the custom variable ''@start_applications'' stored in ''prefer.pl'' in your polymake settings directory (usually ''~/.polymake''so that you'll have your new application at hand in every interactive session.+Again, it will create a folder hierarchy rooting at ''my_ext/apps/APP_NAME'' After having composed the rules and/or clients, you may add the ''APP_NAME'' to the [[:user_guide:howto:shell_custom#custom_variables|custom variable]] ''@start_applications''so that you'll have your new application at hand in every interactive session.
  
 ===== Configuring an extension ===== ===== Configuring an extension =====
Line 35: Line 34:
 In the case your extension needs a third-party library to build the C++ clients, you should provide a pre-build configuration procedure performing some preparations and sanity checks like adding compiler and linker flags necessary to find this library, asserting that its version is not too old for you, etc. In the case your extension needs a third-party library to build the C++ clients, you should provide a pre-build configuration procedure performing some preparations and sanity checks like adding compiler and linker flags necessary to find this library, asserting that its version is not too old for you, etc.
  
-All this is done in a script ''configure.pl'' located in the top directory of your extension.  For this purpose, every extension gets at its birth a personal copy of a script template ''configure.pl.template'' You should edit it, filling the stubs of the functions with appropriate actions, introduce configuration options, if needed, and finally rename the script into ''configure.pl'' Then this script will be executed immediately during the [[#using_other_people_s_extensions|extension import]] as well as each time one runs the interactive command ''reconfigure_extension'' All clients in the extension are recompiled after each reconfiguration, at the latest at the beginning of the next polymake session.+All this is done in a script ''configure.pl'' located in the ''support'' directory of your extension.  For this purpose, every extension gets at its birth a personal copy of a script template ''configure.pl.template'' You should edit it, filling the stubs of the functions with appropriate actions, introduce configuration options, if needed, and finally rename the script into ''configure.pl'' Then this script will be executed immediately during the [[#using_other_people_s_extensions|extension import]] as well as each time one runs the interactive command ''reconfigure_extension'' All clients in the extension are recompiled after each reconfiguration, at the latest at the beginning of the next polymake session.
  
 The script template contains comments describing the purpose and signature of each mandatory function; you may also want to look for the examples into the configuration scripts of extensions bundled with polymake.  At your disposal are all utilities from the module ''perllib/Polymake/Configure.pm'' and all core configuration variables, both defined in the package ''Polymake::Configure'' The extension configuration script is interpreted in a separate package; please, don't change into other package within the script.  Also be aware that the extended perl syntax (like namespace mode) is not allowed for the configure script. The script template contains comments describing the purpose and signature of each mandatory function; you may also want to look for the examples into the configuration scripts of extensions bundled with polymake.  At your disposal are all utilities from the module ''perllib/Polymake/Configure.pm'' and all core configuration variables, both defined in the package ''Polymake::Configure'' The extension configuration script is interpreted in a separate package; please, don't change into other package within the script.  Also be aware that the extended perl syntax (like namespace mode) is not allowed for the configure script.
Line 81: Line 80:
  
 In the case of a large team working together on an extension individual contributions may still be distinguished by usual  In the case of a large team working together on an extension individual contributions may still be distinguished by usual 
-[[reference:rulefiles#credits_and_help|credit notes]] embedded in the rulefiles; then the credit note of the entire extension will be assigned by default to all rules and functions lacking individual credit notes.+[[user_guide:extend:rulefiles#credits_and_help|credit notes]] embedded in the rulefiles; then the credit note of the entire extension will be assigned by default to all rules and functions lacking individual credit notes.
  
 ===== Managing changes in data model ===== ===== Managing changes in data model =====
Line 115: Line 114:
 ===== Writing testcases ==== ===== Writing testcases ====
  
-It is always a good idea - especially if your extension is large - to write unit tests for your code. Those are essentially small examples which test individual rules and functions. One advantage of this is that you will quickly notice if a change in your code (or in a new polymake release) breaks something in your extension. Polymake offers a convenient set of tools for this, you can find a full description [[howto/devel/testcases|here]].+It is always a good idea - especially if your extension is large - to write unit tests for your code. Those are essentially small examples which test individual rules and functions. One advantage of this is that you will quickly notice if a change in your code (or in a new polymake release) breaks something in your extension. Polymake offers a convenient set of tools for this, you can find a full description [[user_guide:extend:unit_tests|here]].
 ===== Using other people's extensions ===== ===== Using other people's extensions =====
  
Line 128: Line 127:
 ===== Relations between extensions ===== ===== Relations between extensions =====
  
-Extensions may build upon each other, establishing dependence relations similar to software packages installed on your computer.  The relations between extensions are described in dedicated sections of description files ''polymake.ext'' Every section contains one or more URIs of related extensions, separated with white spaces or distributed over several lines.  An empty line marks the end of a section, similar to [[reference:rulefiles]].+Extensions may build upon each other, establishing dependence relations similar to software packages installed on your computer.  The relations between extensions are described in dedicated sections of description files ''polymake.ext'' Every section contains one or more URIs of related extensions, separated with white spaces or distributed over several lines.  An empty line marks the end of a section, similar to [[user_guide:extend:rulefiles]].
  
   ? ''REQUIRE'' URI URI#version ...   ? ''REQUIRE'' URI URI#version ...
Line 150: Line 149:
  
 If you later try to load a data file referring to the URI of the obliterated extension, polymake will ask you, as usual, to enter its installation directory.  If you are sure that in the meanwhile all the stuff has migrated into the standard distribution and/or other (already loaded) extensions, you should respond with the magic word ''ignore'' . If you later try to load a data file referring to the URI of the obliterated extension, polymake will ask you, as usual, to enter its installation directory.  If you are sure that in the meanwhile all the stuff has migrated into the standard distribution and/or other (already loaded) extensions, you should respond with the magic word ''ignore'' .
 +
  • user_guide/extend/extensions.1458744396.txt.gz
  • Last modified: 2016/03/23 14:46
  • by hampe