10 Using raco pollen

Racket provides centralized command-line options through raco (short for racket command, see raco: Racket Command-Line Tools).

Once you install Pollen, you can access the following Pollen-specific commands through raco using the subcommand raco pollen.

10.1 Making sure raco pollen works

Open a terminal window and type:

If raco pollen is installed correctly, you’ll see:

But if you get:

You’ll need to fix the problem before proceeding, most likely by reinstalling Pollen (see Installation).

If your error is like this:

You have a deeper problem with your Racket installation (often a misconfiguration of PATH).

10.2 raco pollen

Same as raco pollen help.

10.3 raco pollen help

Displays a list of available commands.

10.4 raco pollen start

Start the project server from the current directory using the default port, which is the value of the parameter current-server-port (by default, port 8080).

This command can be invoked with two optional arguments, and two optional switches.

raco pollen start path will start the project server from path rather than the current directory (making path its root directory).

raco pollen start path port will start the project server in path using port rather than current-server-port. This is useful if you want to have multiple project servers running simultaneously.

If you want to start in the current directory but with a different port, use . as the path:

Pollen defaults to port 8080 because it’s not commonly used by other network services. But Pollen has no idea what else is running on your machine. If 8080 is already in use, you’ll get an error when you try to start the Pollen project server. In that case, try a different port.

Adding the optional -l or --launch switch will open the main project dashboard in your web browser after the project server starts.

Adding the optional --local switch will restrict the project server to responding to requests from localhost. (By default, the project server will respond to requests from any client.)

10.5 raco pollen render

This command can be invoked two ways: in source mode or directory mode.

In both modes, the optional --dry-run or -d switch prints the paths that would be rendered by this command without actually doing so.

In both modes, the optional --force or -f switch forces a fresh render from source, even if the file is already cached, by updating the modification date of the file (à la touch). Thus, if modification dates are important to you, don’t use this option.

In both modes, the optional --null or -n switch renders as usual, but doesn’t write any files. (Convenient if you’re arranging special render behavior, for instance writing to a database or network server.)

Source mode: raco pollen render source ... will render only the source paths specified in source .... Consistent with the usual command-line idiom, this can be a single path, a list of paths, or a pattern:

Paths can also be specified as output rather than input paths, and the corresponding source paths will be discovered:

The optional --target or -t switch specifies the render target for multi-output source files. If the target is omitted, the renderer will use whatever target appears first in (setup:poly-targets).

See also Using raco pollen render with poly sources.

The optional --parallel or -p switch creates a set of parallel rendering jobs equal to the number of processing cores on the system. On a multi-core machine, this will usually make your rendering job finish faster. The order of rendering is not guaranteed, of course, so if your project depends on a certain order of rendering, don’t use this option.

The alternative --jobs <count> or -j <count> switch does the same thing, but takes one argument that creates <count> parallel jobs (which can be more or less than the number of processing cores).

As a rule of thumb, parallel rendering works best if you do raco setup first, which updates Pollen’s disk caches:

Warning: In all cases, the newly rendered output file will overwrite any previous output file.

As of mid-2020, Pollen’s parallel-processing performance under the CS (= Chez Scheme) variant of Racket is worse than ordinary Racket. If you use Racket CS, you may get better results using -j 4 (which will limit the operation to four cores) than -p (which will use all available cores).

Directory mode: raco pollen render directory renders all preprocessor source files and then all pagetree files found in the specified directory. If none of these files are found, a pagetree will be generated for the directory (which will include all source files) and then rendered. If the directory argument is omitted, the command defaults to the current directory.

In directory mode, this command can be invoked with two other optional arguments (in addition to the --target, --parallel, and --jobs switches mentioned above):

The --subdir or -s switch also renders subdirectories. current-project-root remains fixed at the initial directory, just as it would be in the project server after invoking raco pollen start.

Certain subdirectories are automatically ignored, including Racket and Pollen private directories (like compiled) and source-control directories (like .git and .svn). You can omit other paths by overriding default-omitted-path?. You can override these omissions — that is, force a path to be included in a recursive render — by overriding default-extra-path?.

The --recursive or -r switch renders subdirectories recursively. Meaning, each subdirectory is treated like an independent subproject, and current-project-root moves around accordingly. In many projects, there won’t be any difference between the -s and -r switches. But if the difference matters in your project, you have them both.

10.6 raco pollen publish

Make a copy of the project directory on the desktop, but without any source files or other Pollen-related files. (This function is pretty lame, and I invite suggestions for improvement.)

raco pollen publish project-dir will publish the project in project-dir onto the desktop in a folder called publish. Warning: if publish already exists on the desktop, it will be overwritten.

raco pollen publish project-dir dest-dir will publish the project in project-dir to dest-dir rather than the desktop. Warning: if dest-dir already exists, it will be overwritten by the newly published directory.

If you’re already in your project directory and want to publish somewhere other than the desktop, use raco pollen publish . dest-dir.

By default, this command will automatically overwrite the destination directory. Adding the optional -c or --confirm switch will ask for confirmation if the destination already exists.

You can determine the default publishing destination for a project by overriding default-publish-directory.

Certain files and directories are automatically omitted from the published directory, including Racket and Pollen sources, Pollen caches, and source-control directories (like .git and .svn). You can omit other files by overriding default-omitted-path?. You can override these omissions — that is, force a path to be published — by overriding default-extra-path?.

The optional --dry-run or -d switch prints the source and destination directories for publishing without actually doing so. If the destination-directory path cannot be created, an error will arise.

10.7 raco pollen setup

Finds Pollen source files in the current directory, compiles them, and loads the results into the Cache. This will give you the snappiest performance during an interactive session with the project server.

Can also be invoked as raco pollen setup directory, which will set up the files in directory.

The optional --parallel or -p switch creates a set of parallel setup jobs equal to the number of processing cores on the system. On a multi-core machine, this will usually make your setup finish faster.

The alternative --jobs <count> or -j <count> switch does the same thing, but takes one argument that creates <count> parallel jobs (which can be more or less than the number of processing cores).

As of mid-2020, Pollen’s parallel-processing performance under the CS (= Chez Scheme) variant of Racket is worse than ordinary Racket. If you use Racket CS, you may get better results using -j 4 (which will limit the operation to four cores) than -p (which will use all available cores).

The optional --dry-run or -d switch prints the paths that would be compiled by this command without actually doing so.

10.8 raco pollen reset

Resets Pollen’s Cache by deleting the cache directories, including compiled directories created by Racket. Use this when you need a fresh start in life.

Can also be invoked as raco pollen reset directory, which will reset a different project directory.

10.9 raco pollen version

Would you believe this prints the Pollen version number.

10.10 The POLLEN environment variable

Pollen recognizes a POLLEN environment variable on the command line, which can be used to pass through any value you like. This value can be used within your project files with (getenv "POLLEN"), which if not set, returns #f. Take this file, for instance:

The POLLEN environment variable will change how it’s rendered:

10.11 Logging & the PLTSTDERR environment variable

See Logging for an introduction to Racket’s logging system.

By default, Pollen will log messages at the 'info level or above to the console during any terminal session (e.g., project server or rendering job). So if you start the project server like so:

You will see log messages starting with:

And so forth.

You can use Racket’s PLTSTDERR environment variable to adjust the level of logging. If you provide an explicit log level for Pollen, it will override this default behavior. So if you only want to see messages at the 'error level or above, you would invoke the project server like so:

After this, the project server will work normally, but you won’t see the usual 'info-level messages, and instead will only see 'error messages or above.

Conversely, if you want more detailed logging, you can invoke the 'debug log level like so:

Then you’ll see the usual 'info messages, plus a bunch more.