appdir setting confusion

Dear Maintainers,

In the app template created by the dancer2 utility, the sample app code is placed in appdir/lib. This is more than a possibility for organizing code, it is required for the webapp to start correctly, because Dancer2/Core/Role/HasLocation.pm uses this directory structure to set config->{appdir}, the root directory of the webapp.

Dancer2::Manual states:

  When Dancer2 is imported to a script, that script becomes a webapp

I think this needs to be more clear. In the perl culture, a module's install location is not usually relevant to how a module operates, except for the priority of the module being found when the interpreter scans @INC looking for a module to load.

In Dancer1, the webapp module doesn't need to be in appdir/lib/, at least it worked for me to install my webapp in a standard (for perl) location. So this difference in behavior between D1 and D2 could be a cause for extra hiccups during migration, as exemplified by my experience.

If we conclude that there is a problem (and the code comments suggest some pain here) one part of the solution could be to state clearly that the webapp module that imports Dancer2 must be located under appdir/lib.

A second part could be to introduce a routine that issues a warning message about a possibly wrong appdir setting if the appdir doesn't contain a config.yml file or bin/ or environments/ directories.

A third part of the solution could be to add a DANCER2_APPDIR environment variable, and document that it is available.

Thank you for your attention.

Joel Roth

Start with Dancer2/Core/Role/HasLocation.pm and the Dancer2::Manual passage about importing Dancer2 into a script, then compare them with the app template created by the dancer2 utility. Determine which appdir behavior should be supported or documented, and consider the proposed warning and DANCER2_APPDIR options; done means the expected layout and configuration are unambiguous.