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.
raco pollen start path will start the project server in path rather than the current 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 |
10.5 raco pollen render
Render all preprocessor source files and then all pagetree files found in the current 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.
This command can be invoked with extra arguments.
raco pollen render directory will perform the render described above, but in the specified directory.
Alternatively, the command can take a variable number of path arguments. raco pollen render path ... will render only the paths specified in path .... 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 -t or --target 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.
Warning: In all cases, the newly rendered output file will overwrite any previous output file.
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.
You can determine the files that get filtered out in a particular project by using setup:unpublished-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 a different project directory.
10.8 raco pollen reset
Resets Pollen’s Cache by deleting the cache directories.
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:
> 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 |
|