This toolkit is intended to assist foobar configuration authors in packaging their work for distribution. It is based on NSIS, and will produce an executable setup file which will install the config file and supporting images, fonts and components to the user's Foobar installation. It can download and install components from remote locations, in order to avoid restrictions on re-distribution of components for those components whose license restricts that.
To use this toolkit, you must first instal NSIS, and the following plugins for it:
Once NSIS and the required plugins listed above are installed, this toolkit requires no further installation. Simply place all the files together in a convenient folder.
7za.exe and unrar.exe (not unrarw32.exe, which is the installer that contains unrar.exe) should also be placed either in the same folder as the toolkit files. If they are placed elsewhere then the ConfigSettings.nsh file can be used to point to their actual locations.
Before the toolkit can be used to create an installer, you must prepare your configuration and supporting files for distribution. In the examples, I have assumed that foobar2000 is intalled to c:\Program Files\foobar2000, but if this is not the case, adjust as appropriate.
All images referenced by your configuration should be placed in a sub-folder of an Images sub-folder of the foobar2000 folder. The sub-folder name should be unique to your configuration, to avoid clashes with other configurations. It is recommended that the form author name\config name\, which would give a final path to the images for a config as being:
c:\Program Files\foobar2000\Images\authorName\configName
Within your config, all references to images should reference images in this folder, and they should all be relative. This means instead of referencing "c:\Program Files\foobar2000\Images\authorName\configName\coolButton.png", a config should reference "Images\authorName\configName\coolButton.png". Otherwise the images will not be seen unless the user has foobar installed in exactly the same place as you do. If you have a tool for editing config files (like FooCfgToXml) then this can be often done with a search and replace operation. In any case, you should test your results before distribution.
If you have foobar installed with per-user settings, your foobar2000.cfg file will be in your Application Data\foobar2000 folder. It must be copied to your foobar2000 folder, so that the toolkit can find your config file as:
c:\Program Files\foobar2000\foobar2000.cfg
If your configuration includes playlist tree config files, which will be of the form playlist-tree-n.pts, then these too must be in your foobar2000 folder. Again, if you are using per-user settings, you will need to copy these so that the toolkit can find them as:
c:\Program Files\foobar2000\*.pts
If your configuration includes Panels UI config files, which will be in a "PanelsUI" folder, then these must also be in your foobar2000 folder. If you are using per-user settings, they will need to be copied there so that the toolkit can find them as:
c:\Program Files\foobar2000\PanelsUI\*.*
Any fonts that you want to include with your configuration should be copied from your Windows Fonts folder to a sub-folder of a Fonts sub-folder of the foobar2000 folder. The sub-folder must have the same form as the Images sub-folder, which would give the recommended final path to the fonts as being:
c:\Program Files\foobar2000\Fonts\authorName\configName
Please ensure you have permission to redistribute any fonts you place in this folder.
You must add a file called RequiredComponents.nsh to a sub-folder of the Components sub-folder of the foobar2000 folder. The sub-folder must have the same form as the Images sub-folder, which would give the recommended final path to the fonts as being:
c:\Program Files\foobar2000\Components\authorName\configName\RequiredComponents.nsh
The content of the RequiredComponents.nsh must be as follows: Any line may start with a ;, which indicates a comment. Blank lines are also allowed. Apart from those two cases, each line must define a component which needs to be installed. Depending on whether the component is to be bundled with the installer, or to be remotely downloaded and installed at install time, the line may be one of:
!insertmacro RemoteComponent "component_dll_filename.dll" "archive_name.zip" "http://url_to_archive_file"
or
!insertmacro BundledComponent "component_dll_filename.dll"
There is a template RequiredComponents.nsh provided as part of the toolkit distribution which contains example lines for a number of common components. This can be copied into the appropriate folder and the components used uncommented in it. It is hoped that these component definition lines can be shared in the foobar forums, or even complete RequiredComponents.nsh files.
Please ensure you have permission to redistribute any components that you use the BundledComponent line to include in the installer.
If you have any other files that you want to include with your configuration, such as a readme file, they should be placed in a sub-folder of a Misc sub-folder of the foobar2000 folder. The sub-folder must have the same form as the Images sub-folder, which would give the recommended final path to the fonts as being:
c:\Program Files\foobar2000\Misc\authorName\configName
Once the configuration file has been prepared as described above, ConfigSettings.nsh can be edited for it. A template ConfigSettings.nsh is provided as part of the toolkit distribution.
Open the file in any text editor, and change the first two (non-comment) lines to replace your config name, and your author name. For example:
!define CONFIG_NAME "MySuperPrettyConfig"
!define CONFIG_AUTHOR "Alex"
The next line specifies where the configuration files should be taken from. This will be the foobar installation where you prepared them in the first steps.
!define COPY_CONFIG_FROM "c:\program files\foobar2000"
After that, if you decided not to use the authorName\configName convention, you can change the line which defines what subfolder to look for the files used by the configuration. Otherwise, leave it as it is.
!define CONFIG_SUBFOLDER "${CONFIG_AUTHOR}\${CONFIG_NAME}"
Following that line there are several !define INCLUDES_ lines which specify which sorts of files the configuration uses. If you don't have any of a particular sort of file, just delete or comment out that line.
!define INCLUDES_IMAGES
!define INCLUDES_FONTS
!define INCLUDES_MISC
!define INCLUDES_COMPONENTS
!define INCLUDES_CONFIG
If you are using any remotely installed components that are distributed in rar or 7z files, then you will need to include 7za.exe and/or unrar.exe in your installer to extract them. To do this, use the next two lines to specify where to find them, if not in the same folder as the installer scripts.
!define INCLUDE_7ZA "7za.exe"
!define INCLUDE_UNRAR "unrar.exe"
You can create multiple copies of this file if you manage multiple configs, but only the one named ConfigSettings.nsh appearing in the same folder as ConfigInstaller.nsi will be used.
If you've installed NSIS, this should simply be a matter of right clicking on ConfigInstaller.nsi and selecting "Compile NSIS Script". It depends on having the following files present in the same folder:
The output should be an exe file in the same folder with the name of your config specified in ConfigSettings.nsh followed by " Setup.exe". "MySuperPrettyConfig Setup.exe", for example.
It is currently not possible to safely uninstall a configuration, so no uninstaller has been provided. If you want to roll back to the settings you had before an installation, a backup config file is created by the installer, stamped with the date and time of the installation. To roll back, close foobar, delete foobar2000.cfg and rename the foobar2000.cfg.date and time.bak file to foobar2000.cfg.
If you are finding that images do not appear, then make sure that when you run foobar, you run it from its own folder. If you start foobar from a shortcut, this can be achieved by right clicking on the shortcut, choosing properties, then filling in the "Start In" box with the folder foobar is installed in.
The goal of this toolkit was freedom to tinker, and freedom to share creativity. In the same spirit, please feel free to give copies of this work to whoever you think might find it useful. Of couse, if you improve on anything that you think might be useful to others, please share your changes too!