Defining Custom Variables

Defining & using custom variables in recipes

Overview

​At the end of the day, AutoPkg input and output variables are just arbitrary strings that are used as a substitute for another string value.

While processors define a set of required and optional variables that can be used within its arguments, you can define your own custom variables within this structure. This is valuable when you need to use a particular processor multiple times within a recipe but need to persist the collected values, as on each subsequent processor run the previous output variable values get overwritten.

Typically, recipes do not need the previous values of a given output variable to persist. For example, if a recipe needs to find multiple files (FileFinder) and copy each of them to a central location (Copier) in order to create a PKG, you can simply run the necessary processors for one file and repeat those processor steps for each additional file. Once you've completed the larger task of copying the files from the collected paths, storing what the previous values were for each item is unnecessary. However, if there is a particular reason you need to find all the files first (e.g., you want to include them in a postinstall script, you need to manipulate two values output by different runs of the same processor), defining a custom variable(s) to store the result(s) of your earlier runs can be a solution. ​

Defining custom variables

​Defining a custom variable is as simple as supplying it as a key in the Arguments dictionary and setting its value to the previously collected output variable. ​

<dict>
	<key>Arguments</key>
	<dict>
		<key>your_custom_variable</key>
		<string>%your_collected_output_variable%</string>
	</dict>
	<key>Processor</key>
	<string>PROCESSOR_NAME</string>
</dict>

​

Example

​In the example below, the FileFinder processor is used twice to collect the paths of two different files.

The first time FileFinder is run (per the processor’s info), the found file path is assigned to the found_filename output variable. The second run of FileFinder sets the previously collected found_filename to a custom previous_file variable and overwrites found_filename with the collected second file path.

Subsequent processors not listed below can then use %previous_file% and %found_filename% in their Arguments dictionary. ​

<dict>
	<key>Comment</key>
	<string>Collect the first file path.</string>
	<key>Arguments</key>
	<dict>
		<key>pattern</key>
		<string>%RECIPE_CACHE_DIR%/%NAME%/*.pkg</string>
	</dict>
	<key>Processor</key>
	<string>FileFinder</string>
</dict>
<dict>
	<key>Comment</key>
	<string>Take the collected first file path and assign it to the custom previous_file variable. Collect the second file path and overwrite the previously collected output variables.</string>
	<key>Arguments</key>
	<dict>
		<key>pattern</key>
		<string>%RECIPE_CACHE_DIR%/%NAME%/*.txt</string>
		<key>previous_file</key>
		<string>%found_filename%</string>
	</dict>
	<key>Processor</key>
	<string>FileFinder</string>
</dict>
​

Adding Comments via Custom Key/Value Pair

One other application of this concept is to add a key/value pair that acts as documentation within your recipe. For those writing recipes in plist format, you may be used to adding comments in HTML or XML with the syntax <!-- [comment] -->. If you run your recipe through a formatting process like plutil --convert xml1 (which is common practice), all of the comments of that type will be stripped.

An effective way to maintain those remarks is to instead add a key/value pair at the same level as Processor and Arguments, where the key name is Comment (by convention) and the string value is the comment you want to include. (This works equally well with YAML recipes.) As long as you maintain valid syntax, the comment will be preserved when run through a formatter like plutil --convert xml1 but the contents will functionally be ignored by AutoPkg. The plist snippet directly above is an example of this usage.