In trying to get imap2soap.pl to work, I found that civicrm.config.php always sets $currentDir to the physical location it resides in, i.e. it resolves all symlinks, rather than referring to the logical path it is currently being used under.
I am not sure if my description makes sense, but in different words it always returns the same path, even if/when the whole civicrm directory is symlinked elsewhere and invoked from there. Which can cause things that assume the logical (symlinked) path for their operation, to break.
The main problem here seems to be the use of _FILE_ to determine the current working directory. There seems to be no equivalent for returning the logical path of an included file.
I am not proficient in PHP, but all functions I could find to return logical paths return that of the currently active file, i.e. the one that includes civicrm.config.php, rather than the latter itself. So my approach is to first determine the physical paths of both civicrm.config.php (via _FILE_) and the active file including it (by dereferencing the logical path) and doing a string-comparison between the two. The directory path of the config file should match the beginning of the directory path of the active file, and the rest of the string then be the relative path between the two. If that is true, then omitting that same relative path from the end of the logical path of the including file should yield the logical path of the included file, namely civicrm.config.php.
To be doubly (or triply) sure, the code does not only check if the include file directory path matches the beginning of the active file directory path, but also if the relative path we just determined represents the end of the logical path of the including file. If that is the case, then we should be safe in omitting that part.
If any of the outlined assumptions do not apply, the code falls back onto the default (_FILE_, same as before).
and attached `diff -e` file
1. I have only run into the problem (with imap2soap.pl) with version 2.1 alpha3, but the same code has been in place for a while so I assume the same would apply to earlier versions, but have not verified that.
2. in the forum discussion referenced above, Piotr suggested to use Drupal's conf_path() for initialisation. I don't know anything about that, nor do I understand what it does. I would be concerned whether I can rely on that function actually being available in a context where Drupal is not active and a script (as in this case) is for example called from a cron job. I might be wrong but wanted to share my concern just in case I am not.