# using pub.pl
the `pub.pl` tool is what is called a *command line application*, a *terminal program*, or a *shell program*. this means that it has no graphical interface, and operates simply by reading and writing text to and from files and the keyboard.
to interface with command line tools, we need to use a *terminal emulator*. on Mac OS X this is the Terminal app in the Utilities folder (`/Applications/Utilities/Terminal.app`). on newer versions of the OS, the Utilities folder is sometimes hidden; you can reach it by switching to the Finder, holding down **Command** and **Shift**, and pressing the `U` key. on Linux, this is a tool such as `gnome-terminal`, `mate-terminal`, or `urxvt`.
once you've opened the terminal, there are a few core concepts you need to understand.
## the shell
the *shell* is the command-line application that starts running as soon as you load the terminal. it displays a prompt (by default, usually a string ending in `$`) and accepts *commands.* the shell handles basic file management tasks and launching other applications.
you enter a command into a shell by typing it into the window and pressing the **Return** or **Enter** key. the command performs a task like moving a file or launching a program. when the command finishes, another prompt will be displayed. many commands do not print anything while they are running, so you will simply see a cursor sitting on a blank line until they terminate.
## running `pub.pl`
the only commands you need to understand in order to run `pub.pl` is the `cd` command. the shell can be thought of a bit like a Finder window. a Finder window displays a view of a single folder and lets you take actions on the contents. in the shell's case, this folder is known as the *working directory.*
the `cd` command changes the working directory. it's the analogue of double-clicking on a folder. in order to run `pub.pl`, we need to change the working directory to the one that `pub,pl` is located in. the precise command needed varies depending on where you've put the folder containing your website. if it's in your home folder, you can reach it with the command `cd ~/evergreen`; if it's on your desktop, you can reach it with `cd ~/Desktop/evergreen`. if you've changed the name from `evergreen`, you should write that new name instead.
(a useful trick is *shell autocomplete* -- once you typed part of a name, you can press the **Tab** key and the shell will try to figure out what file or folder you meant.)
once you've reached the right directory, you can run `pub.pl` and generate your site. you do this by entering `./pub.pl` at the prompt and pressing **Enter**. if you receive an error, try running `chmod +x pub.pl` and then trying again.
as `pub.pl` runs, it will display its current status, printing a list of the files it is operating on. once it has finished, it will display the text `ok` and then return you to your shell.
it might be useful to keep a shell open while you work on your website so you can quickly regenerate it. if you do this, it might be useful to know that you can re-run the last command simply by pressing the up arrow and then pressing **Enter** as usual.
## output
the compiled forms of the input files are stored in the `out` folder. you can double-click on them to open them in a browser. to upload them to your web host, see [uploading](upload.html).
## technical details
`pub.pl` is not a binary. as the name suggests, it is self-contained script written in the Perl programming language with no external dependencies besides the Perl interpreter. it should be broadly portable to any POSIX-compliant operating system, and it's possible it runs on Windows, at least under Cygwin. i don't know, haven't tried, and don't care.
`pub.pl` ignores all files and folders whose names begin with `.`, keeping out profligate nonsense like the `.DS_Store` files OSX so enjoys spamming all over every filesystem it gets its greasy hands on, and allowing you to place metadata of your own choosing inside the source tree.
the source code of `pub.pl` is poorly commented and thorny as hell; it in general should be edited only with extreme care and looked upon only as a source of horrified amusement.