Instructions for custom modules are incomplete/outdated(?)

[jakobj]

When following the guidelines here for compiling and installing a custom module, NEST fails to load the module with the following error:

SLI ] (mymodule) Install

Nov 01 16:39:56 Install [Error]: DynamicModuleManagementError
    Module 'mymodule' could not be opened.
    The dynamic loader returned the following error: 'file not found'.
    
    Please check LD_LIBRARY_PATH (OSX: DYLD_LIBRARY_PATH)!

A possibly related issue is that during cmake NEST announces that the installation will be to a non-default directory, although -DCMAKE_INSTALL_PREFIX was not used:

The module will be installed into a non-default location!                                              
Make sure to set the environment variables:                                                              
  export NEST_MODULE_PATH=/home/jordan/opt/nest-simulator-mymodule/install/lib/nest:$NEST_MODULE_PATH     
  export SLI_PATH=/home/jordan/opt/nest-simulator-mymodule/install/share/nest/sli:$SLI_PATH  

Setting the NEST_MODULE_PATH, SLI_PATH variables does not fix the issue.

For some reason this can be fixed by setting LD_LIBRARY_PATH to {install}/lib and {install}/lib/nest:

$ export LD_LIBRARY_PATH=/home/jordan/opt/nest-simulator-mymodule/install/lib:$LD_LIBRARY_PATH
$ export LD_LIBRARY_PATH=/home/jordan/opt/nest-simulator-mymodule/install/lib/nest:$LD_LIBRARY_PATH
[...]
SLI ] (mymodule) Install

Nov 01 16:57:00 Install [Info]:
    loaded module My NEST Module

Could we please make the documentation on this topic a bit more precise, e.g., there seems to be a mismatch between the advice from cmake (setting NEST_MODULE_PATH) and the advice from the NEST binary (setting LD_LIBRARY_PATH)?
Additionally, the loader should be fixed to only require setting LD_LIBRARY_PATH once, if that problem is not specific to my setup (Debian buster 10.1).

@heplesser @jessica-mitchell

[Silmathoron]

Yes, this is also an issue in the context of NESTML and we should decide on a fix...
I briefly discussed it with @jougs and @clinssen here and I think that it would be best to include a check in cmake that the filename does not exist (with an option to overwrite mentioned if it does), then install directly in the NEST install lib folder.

[sarakonradi]

Mentioning #1513 here, as we are currently deciding there whether or not to keep NEST_MODULE_PATH in the first place.

[clinssen]

It looks like setting the runpath is not the solution here, as it was in #1545. When you type "(mymodule) Install", the dynamic loader ignores the configured runpaths (but looks at LD_LIBRARY_PATH); see https://www.gnu.org/software/libtool/manual/html_node/Libltdl-interface.html#index-lt_005fdlopen for documentation.

Options:

1. Manually add the relevant path using lt_dladdsearchdir(). It is however not clear how we should obtain the installation path in the C++ context (in https://github.com/nest/nest-simulator/blob/master/nestkernel/dynamicloader.cpp#L180).
2. Rely on (DY)LD_LIBRARY_PATH and change the documentation suggesting to source nest_vars.sh (which sets (DY)LD_LIBRARY_PATH).

[jougs]

I think option 1. is the one to use and that a #define NEST_LIBRARY_PATH "the/library/path" in libnestutil/config.h.in should nicely solve the problem. It could be set from within CMake as all the other macros are and used from within the DynamicLoader.