Document template structure

[takluyver]

Pynsist allows people to extend the default templates to customise installers. The template structure is still evolving, but at some point I should document what blocks are available to override in user templates.

[ghost]

I sent you an email recently asking about how to add some custom shortcuts with parameters to the windows startup directories. You suggested I specify a custom template on the [build] section of the config file with the nsi_template variable. That was helpful and I managed to get it working.

I'd like to leave a couple of comments.

I was thinking about using the SetShellVarContext NSIS function, which only affects the installer, I'd need a second call on the uninstaller, so having a block specifically for the uninstaller section would come in handy.

I read the docs on the nsi_template variable and extended the pyapp.nsi file at first. Then I realized the python installer wasn't being included with the executable. I read a bit of the code and saw there are actually 3 templates used in __init__.py that I needed to choose from, 'pyapp_msvcrt.nsi', 'pyapp_w_pylauncher.nsi', and 'pyapp_installpy.nsi'. These templates then extend pyapp.nsi. I think creating a single entry point template would be handy for the user, which wouldn't need to change it in case the format or the python version on the installer config file is altered later. This entry point template could check the necessary variables with jinja and then use the include statement to add the correct template.

[takluyver]

Thanks!

Having a block for the uninstall section probably makes sense. But it still doesn't make it very convenient to change something like the SetShellVarContext call, because you have to either include the whole parent block or copy the bits of it you want. We could:

1. Live with some copy-pasteing of template code
2. Introduce more fine-grained blocks so you can inherit the bits you need.

3. Introduce many more variables for things like SetShellVarContext, either:

   a. Jinja variables in our template system b. Definitions for the NSIS preprocessor

Conditional inheritance - having one template that can inherit from a number of different ones - feels wrong, but maybe it's an acceptable compromise here. The rules are:

• Python >= 3.5 and using the 'bundled' format - use pyapp_msvcrt.nsi
• Python 3 and 'installer' format - use pyapp_installpy.nsi
• Python 2 - use pyapp_w_pylauncher.nsi