Close

Privacy policy

Follow us

https://www.instagram.com/touchdesigner/
https://www.facebook.com/TouchDesigner
https://twitter.com/1null1
https://www.youtube.com/TouchDesignerOfficial
All
User Guide
Forum
Tutorials
Events & Workshops
Features
Community
Showcase
Resources
  1. Home
  2. Project Packager

    Project Packager

    projectPackager is a script and workflow to create Windows-only installers that packages a TouchDesigner project with the necessary TouchDesigner program files into an distributable installer. For the end user, the result will look like an installed application.

    In accordance with Derivative's [EULA] section 15: Where the Licensee wishes to bundle the installer made available on Derivative’s website with the Licensee’s own assets, Licensee must first receive consent from Derivative by contacting Derivative at licensing@derivative.ca. Licensee agrees that: (i) it shall remain fully responsible and liable for Secondary Licensee’s acts or omissions, including Secondary Licensee’s compliance with this Agreement, and (ii) it must and will provide Derivative with the requested information on the Licensee’s intended use of the Project Packager and Packaged Product (both as defined below).

    Generaledit

    You can find the necessary files in the TouchDesigner Installation's Sample folder.

    TouchDesigner is "hidden" in the folder structure without any references in the Program entries, start menu or desktop. It should be noted that a install maker can choose to not install certain files that would be required for a fully functional TouchDesigner. Hence using TouchDesigner from the project's installation folder will not be the same as running a vanilla installed version.

    While you can fully customize the script, removing the dialog which displays Derivative's License is against Derivative's Terms and Conditions. When end users install a project that runs with TouchDesigner, it needs to be made clear that the project has a license and the end user also agrees to Derivative's License and Terms and Conditions.

    Further, it is important to note that end users will have to install a TouchDesigner license key when running a project in TouchDesigner.

    TouchDesigner uses innoSetup to build it's windows os installer.

    Inno Setup is a free installer for Windows programs by Jordan Russell and Martijn Laan. First introduced in 1997, Inno Setup today rivals and even surpasses many commercial installers in feature set and stability.[1]

    Prerequisitesedit

    This workflow will only create an installer for the windows operating system.

    • innoSetup

    Required Filesedit

    • a TouchDesigner project that is contained in a single folder strucutre. This means that any assets this project might use have to be located under the same root folder as the TouchDesigner project file. A creator should make sure that any references to external media and files is relative.
    • a TouchDesigner Installer file which can be downloaded from derivative. Only Installers starting with 2022.xxxxx are supported.
    • an icon file for the project
    • a license file for your project.[2]

    There are may different License types that can be chosen from. It is though important to make sure that the chosen license works in conjunction with Derivative's License.

    Installer Sizes greater than 2.1 GBedit

    By default the overall installer size cannot exceed 2.1 GB. This is a limitation of Innosetup that can be overcome by setting the InnoSetup directive 

    DiskSpanning=yes

    Enabling disk spanning will instead of storing all the compressed file data inside SETUP.EXE, split the installer into multiple SETUP-*.BIN files -- known as "slices" alongside a SETUP.EXE

    The size of each slice and the number of slices to create are determined by the values of the DiskSliceSize and SlicesPerDisk [Setup] section directives, respectively. Other disk spanning-related directives that you may want to tweak include DiskClusterSize and ReserveBytes.

    Note that it is required that you set this directive to yes if the compressed size of your installation exceeds 2,100,000,000 bytes.

    To distribute the resulting files as a single .exe, you can create a self extracting archive utilizing 7zip as well as ResourceHacker

    See further instructions on how to create a self extracting archive below.

    Instructionsedit

    Preperationsedit

    1. Download InnoSetup from here: https://jrsoftware.org/isdl.php
    2. Install InnoSetup
    3. (optional) When using an IDE like VisualStudio, it might make sense to install the "Inno Setup" Extension.[3] Furthermore InnoSetup and this installer script make use of Pascal Scripting (modern Delphi-like Pascal). Installing the Pascal Extension is recommended to ease development.[4]
    4. Copy the ProjectPackager folder from the TouchDesigner Installation's Sample Folder
    5. Make sure the project is contained in a single folder tree.

    Compiling the Installeredit

    The script of interest is called projectPackager.iss. By default it is a fully functioning install builder which requires a number of arguments to be compiled:

    • ProjectName: (required) The name the project and the installer will have.
    • ProjectVersion: (optional, default: 1.0.0.1) A version number for this project.
    • ProjectPublisher: (required) The name of the publisher (you or your company).
    • ProjectURL: (optional, default: None) A URL where end-users might find information about the project.
    • ProjectIcon: (optional) The path to the icon file that will be associated with this project.
    • ProjectLicense: (optional, default: None) The path to a *.rtf file containing the license this project should be licensed under. If not specified, the license displayed during the installation process will be the unlicense.
    • ProjectFolder: (required) The path to the project that will be packaged.
    • ProjectFile: (required) The path to the project's main *.toe file.
    • StartWithPlayer: (optional, default: 0) Ability to choose if the project should start with TouchPlayer (default) or TouchDesigner.
    • TDInstallerLocation: (required) The path to the TouchDesigner Installer that will be packaged with this project.
    • TDSkipFiles: (optional, default: None) Path to a text file containing a list of files from the TouchDesigner installation that should not be packaged with the project.
    • InstallerIcon: (optional, default: an icon) Specify the path to a custom icon which will be that of the installer file.
    • OutputName: (optional, default: ProjectName) Specify the name of the installer file.
    • CodeMeter: (optional, default: 0) If set to true will install the codemeter runtime at the end of the installation process.
    • Sign: (optional, default: 0) If the machine has a code sign certificate installed, enaling this will attempt to sign the installer.

    All of these arguments can be set via the projectPackager.ini file that is included with the folder.

    Optionally, the arguments can be set via the commandline.

    Using the projectPackager.ini file:edit

    In a Terminal navigate to the repository and run: 

    >ISCC.exe projectPackager.iss

    Using Commandline arguments:edit

    Remove the projectPackager.ini file and in a Terminal navigate to the repository and run: 

    >ISCC.exe /dProjectName="My Project" /dProjectVersion="1.0.0.2" projectPackager.iss
    • Pay attention to how every argument needs to be prefaced by /d
    • It should also be noted that entries in the .ini file and command line arguments can be mixed. The command line arguments will take precedence over ini file entries.

    Decreasing Installer sizeedit

    The TDSkipFiles command line argument during compilation of the installer will skip certain files from being included in the final installer. Refer to the example [skipFiles.txt] to see what files might not be necessary for your project.

    Creating a Self Extractable Archiveedit

    The required template files 7zSDTemplate.sfx, configTemplate.txt, and VersionInfoTemplate.rc can be found in the folder ProjectPackager/sfxHelpers.

    • use 7zip to create a archive:
    7za.exe a ./InstallerOutput/installer.7z ./InstallerOutput/*
    • adjust the configTemplate.txt to fit your application
    • adjust the VersionInfoTemplate.rc to fit your application
    • use ResourceHacker to compile the resource file
    "ResourceHacker.exe" -open ./VersionInfo.rc -save ./VersionInfo.res -action compile -log con
    • embed the resulting resource file into 7zSDTD.sfx
    "ResourceHacker.exe" -open ./7zSDTemplate.sfx -save ./7zSD.sfx -res ./VersionInfo.res -action addoverwrite -mask VersionInfo,, -log con
    • create the self extracting archive
    cat ./7zSD.sfx ./config.txt ./InstallerOutput/installer.7z > ./MyApplication.MyVersion.exe
    • last but not least change the permissions on the file
    chmod 770 ./MyApplication.MyVersion.exe

    Creating a github workflowedit

    This is work in progress.

    End User License Agreementedit

    You and those to whom you distribute TouchDesigner with your project package are bound, upon installation, by the TouchDesigner End User License Agreement located here: https://derivative.ca/end-user-license-agreement-eula

    1. ↑ https://jrsoftware.org/isinfo.php
    2. ↑ https://choosealicense.com
    3. ↑ https://marketplace.visualstudio.com/items?itemName=idleberg.innosetup
    4. ↑ https://marketplace.visualstudio.com/items?itemName=alefragnani.pascal