| Both sides previous revision Previous revision Next revision | Previous revisionLast revisionBoth sides next revision |
| user_guide:extend:clients [2019/03/07 10:30] – panizzut | user_guide:extend:clients [2021/01/12 15:38] – external edit 127.0.0.1 |
|---|
| } | } |
| |
| Using a cached pointer allows to call function templates without injecting their definition body in the caller source code, so that they can be defined in a different application or bundled extension. The function may also have several labeled alternative implementations selectable by preference lists. The cached pointer is automatically following the changes introduced by user commands [[:general#preferences|prefer, prefer_now, and reset_preference]]. | Using a cached pointer allows to call function templates without injecting their definition body in the caller source code, so that they can be defined in a different application or bundled extension. The function may also have several labeled alternative implementations selectable by preference lists. The cached pointer is automatically following the changes introduced by user commands [[:user_guide:howto:shell_custom#preferences|prefer, prefer_now, and reset_preference]]. |
| |
| There is, however, a restriction posed on the eligible functions: they must not have keyword arguments (perl::OptionSet), arguments with default values or explicit type parameters. The reason for this restriction is that all this is processed in the perl layer which is bypassed when calling over a pointer. | There is, however, a restriction posed on the eligible functions: they must not have keyword arguments (perl::OptionSet), arguments with default values or explicit type parameters. The reason for this restriction is that all this is processed in the perl layer which is bypassed when calling over a pointer. |
| ==== Miscellaneous functions ==== | ==== Miscellaneous functions ==== |
| ? ''%%var = perl::get_custom("name")%%'' | ? ''%%var = perl::get_custom("name")%%'' |
| :: Retrieve the value of a custom variable. The name argument must start with the perl type designator ''$'', ''@'', or ''%'', matching the type of the custom variable. The name must be fully qualified (exactly how it appears in the user's file ''customize.pl''). If the custom variable is of an array or hash map type, the C++ local variable being assigned to must be of type ''perl::ListResult'' resp. ''perl::OptionSet''. | :: Retrieve the value of a custom variable. The name must be fully qualified with the package name unless it's defined in the package of the same application as this code belongs to. If the custom variable is of an array or hash map type, the C++ local variable being assigned to must be of type ''perl::ListResult'' resp. ''perl::OptionSet''. |
| ? ''%%var = perl::get_custom("name", "key")%%'' | ? ''%%var = perl::get_custom("name", "key")%%'' |
| :: Retrieve the value of an element of a custom hash map variable. | :: Retrieve the value of an element of a custom hash map variable. |
| ==== Building and Debugging ==== | ==== Building and Debugging ==== |
| |
| As already mentioned at the very beginning, the client source code always resides in the application ''src'' directory. It can only be built together with other clients of its application or extension. Just call ''make'' at the top directory of the polymake source tree resp. of the extension. Call ''make Debug=y'' if you are going to run it under the debugger. Take care to call the right client, i.e. the one located in the polymake/perl/ directory. You should call it from outside the directory. | As already mentioned at the very beginning, the client source code always resides in the application ''src'' directory. It can only be built together with other clients of its application or extension. Just run ''ninja -C build/Opt'' at the top directory of the polymake source tree resp. of the extension. Run ''ninja -C build/Debug'' if you are going to run it under the debugger. |
| |
| When your client is called for the first time, it might require a new wrapper for transforming the arguments from perl representation to C++ and the results in the opposite direction. This wrapper will be generated automatically, compiled on the fly, and loaded as a separate dynamic module. Unless you set the custom variable ''$Verbose::cpp'' to 1 or higher, you won't notice anything but some delay in execution. But, if your client is a function template, it will be really instantiated only now, so that some compiler errors might appear. To fix the errors, you don't need to leave the running polymake session in most cases! Just edit the sources of your client and repeat the call. You will only have to quit the session if you make any changes in the glue declarations like ''Functions4perl''. | When your client is called for the first time, it might require a new wrapper for transforming the arguments from perl representation to C++ and the results in the opposite direction. This wrapper will be generated automatically, compiled on the fly, and loaded as a separate dynamic module. Unless you set the custom variable ''$Verbose::cpp'' to 1 or higher, you won't notice anything but some delay in execution. But, if your client is a function template, it will be really instantiated only now, so that some compiler errors might appear. To fix the errors, you don't need to leave the running polymake session in most cases! Just edit the sources of your client and repeat the call. You will only have to quit the session if you make any changes in the glue declarations like ''Function4perl''. |
| |
| When you quit the session later, after having fixed all compiler problems, the automatically created wrapper will be written into a separate source file, located in the subdirectory ''perl'' of the client's source directory. Next time polymake is started, it will recompile the client together with the wrapper once again while loading the application. | When you quit the session later, after having fixed all compiler problems, the automatically created wrapper will be written into a separate source file, located in the subdirectory ''cpperl'' of the application. Next time polymake is started, it will recompile the client together with the wrapper once again while loading the application. |
| |
| If the client belongs to the polymake source tree, or your extension is kept under SVN control as well, the wrapper file will be registered with ''svn add''. Be sure to eventually submit it into the repository together with the client! | If your extension is managed with source version control like git, remember to eventually commit all changes in the ''cpperl'' subdirectory. |
| |
| To debug a client, you must start the whole perl interpreter under gdb. Before you do this for the first time, you should store two useful settings in ''~/.gdbinit'': | To debug a client, you must start the whole perl interpreter under gdb. Before you do this for the first time, you should store two useful settings in ''~/.gdbinit'': |
| Now you can start polymake as follows: | Now you can start polymake as follows: |
| gdb -args perl -S polymake | gdb -args perl -S polymake |
| If you are debugging a client compiled in the SVN working copy of the polymake source tree, which is probably not contained in your PATH, then you should omit the option ''-S'' and specify the full path to ''/your/working/copy/perl/polymake'' instead. | If you are debugging a client compiled in the working copy of the polymake source tree, which is probably not contained in your PATH, then you should omit the option ''-S'' and specify the full path to ''/your/working/copy/perl/polymake'' instead. |
| |
| |
| (gdb) call M.dump() | (gdb) call M.dump() |
| The output goes to ''stderr'', thus be sure not to redirect it (polymake never does it on its own). | The output goes to ''stderr'', thus be sure not to redirect it (polymake never does it on its own). |
| | |