On this page:
10.1 Making sure raco pollen works
10.2 raco pollen
10.3 raco pollen help
10.4 raco pollen start
10.5 raco pollen render
10.6 raco pollen publish
10.7 raco pollen setup
10.8 raco pollen reset
10.9 raco pollen version
10.10 The POLLEN environment variable

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:

> raco pollen test

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

raco pollen is installed correctly

But if you get:

raco: Unrecognized command: pollen

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

If your error is like this:

Unrecognized command: raco

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 one optional switch.

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/to/project/

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.

> raco pollen start ~/path/to/project/

> raco pollen start ~/path/to/project/scribblings 8088

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

> raco pollen start . 8088

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.

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:

> raco pollen render foo.html.pm

> raco pollen render foo.html.pm bar.html.pm zam.css.pp

> raco pollen render *.html.pm

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

> raco pollen render foo.html

> raco pollen render foo.html bar.html zam.css

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).

> raco pollen render -t pdf foo.poly.pm

See also Using raco pollen render with poly sources.

The optional --parallel or -p switch creates a set of parallel rendering jobs. 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.

> raco pollen render -p foo.html bar.html zam.css

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

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 and --parallel 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?.

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.

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:

#lang pollen
Result is or[(getenv "POLLEN")]{nothing}

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

> raco pollen render test.txt ; cat test.txt

rendering test.txt.pp

rendering: /test.txt.pp as /test.txt

Result is nothing


> POLLEN=DEBUG raco pollen render test.txt ; cat test.txt

rendering test.txt.pp

rendering: /test.txt.pp as /test.txt

Result is DEBUG