## Installing and running CorpusSearch

- Preliminaries
- Installing CorpusSearch
- Running CorpusSearch

### Preliminaries

- If you are using a Unix-derived system such as Linux and MacOS, you will need to learn something about shells. The instructions below assume that you are using the T shell (tcsh), but MacOS now installs the z shell (zsh) by default, which is an extension of the Bourne shell (bash). The basic installation is the same across shells, but each shell has a slightly different syntax for path specification, aliases, and so on. Please should consult local documentation for details.

- Changes introduced with MacOS 10.15 (Catalina) cause certain Java applications to fail, but as of late 2023, CorpusSearch runs under MacOS 13 (Ventura) and MacOS 14 (Sonoma).

- Please be aware that if your operating system displays paths to you in a language other than English, it almost certainly still uses the English pathnames underlyingly. For instance, on a Mac, a path that appears to you as "/Applicazioni" or "/Utenti/beatrice/Scrivania" will likely need to be specified by the English "/Applications" or "/Users/beatrice/Desktop".

- The following item may be outdated. We leave it up in case it proves useful to some readers. If you are using Windows, we recommend downloading the Java Virtual Machine (version 1.4 or later) from the Sun java site (https://www.java.com/) rather than running Microsoft's Java.

  Here's how to check which virtual machine you are running under Windows XP.

  - Search for the Command Prompt by clicking on the "Run" icon on the Start menu.
  - Enter "cmd" in the dialog box that comes up.
  - Enter "C:\Documents and Settings\username>java -version" in the Command Prompt dialog box that comes up.

### Installing CorpusSearch

- Download the latest version of CorpusSearch from https://corpussearch.sourceforge.net/, or use the version that comes with the LDC release of the Penn Parsed Corpora of Historical English. If necessary, unzip the download.

- In what follows, we assume that you have downloaded version CS_2.003.04.jar. Move the .jar file to a convenient location - for example, the "/Applications" folder under MacOS or the "Program Files" folder under Windows.

- Unix/Linux users (including MacOS):

  - Open a window that allows you to run commands - a Terminal window under MacOS or an xterm window under Unix or Linux.

  - Assuming that you have moved CS_2.003.04.jar to the "/Applications" folder, enter the following line at the prompt in the terminal window.

    >     java -classpath /Applications/CS_2.003.04.jar csearch/CorpusSearch

    If you have moved the .jar file to some other location than /Applications, edit the path accordingly.

  - CorpusSearch should now prompt you for input. If not, check the path to the .jar file. Once you're prompted for input, follow the instructions to quit the search. All you are doing at this point is checking that the path to the program is set up correctly.

  - For convenience, you can add an alias for the above java command to your shell initialization file (for instance, .cshrc, .zshrc, .bashrc). The following line will create such an alias in a .cshrc file:

    >     alias CS 'java -classpath /Applications/CS_2.003.04.jar csearch/CorpusSearch'

    Use the appropriate syntax for other shells. Now you can invoke CorpusSearch with just "CS".

    Again, if your operating system displays pathnames in a language other than English, the alias in your shell initialization file almost certainly needs to be specified in terms of the English directories.

- Windows users:

  - You will need to adapt the above instructions as follows:

  - Launch the Command Prompt via Start -> Run and enter "cmd" in the box ("command" under Windows 98).

  - Enter the following command into the Command Prompt dialog box:

    >     cd C:\

  - At the resulting "C:\>" prompt, enter the following line (adjusting the path to the .jar file if necessary):

    >     java -classpath "C:\Program Files\CS_2.003.04.jar" csearch/CorpusSearch

    Be sure to include the quotation marks in the first argument after "-classpath". Also note the different direction of the slashes in the first and the second argument (backward and forward, respectively).

### Running CorpusSearch

CorpusSearch is run from a terminal window (or "cmd" box) as described above. It needs two arguments to run: a command file and one or more source files. Assuming the alias "CS" defined in the previous section, the following command runs the query "foo.q" on the source file "bar.psd".

>     CS foo.q bar.psd

The above command assumes that the command file and source files are in the same directory as the one from which you're invoking CorpusSearch. If that is not the case, you need to specify full paths to the files in question. For example:

>     CS /path/to/query/file/foo.q path/to/input/file/bar.psd

>     CS ../queries/foo.q ../../corpus/bar.psd

Using standard command line conventions, more than one file can be searched in a single run.

>     CS foo.q a*.psd *z.psd /some/other/directory/*.psd

CorpusSearch can also be invoked without arguments. It then prompts the user to enter the names of the command file and of the source file(s).

The search results are written to a file with the same basename as the query file, but with the extension .out ("foo.out" in the case at hand).

The basename of the output file (but not the extension) can be changed using an "-out" switch. Not "-o", but "-out".

>     CS foo.q bar.psd -out foo-on-bar.out

>     CS foo.q *.psd -out all.out

If CorpusSearch reports a run-time error because the underlying corpus is corrupted (for instance, because of mismatched parentheses), it sends an error message to the terminal screen by default. Tracking down such errors generally requires redirecting the error message to a file. The file is standardly called "ERR", but the name is up to the user.

>     CS foo.q bar.psd >& ERR

>     CS foo.q *.psd >& help-me-debug

Depending on the complexity of a query and the size of the input, searches can take from a few seconds to a few hours. To run a search in the background under Unix/Linux, add an ampersand (&) at the end of your command:

>     CS foo.q bar.psd &

>     CS foo.q bar.psd >& ERR &

Before initiating a search in the background, make sure there is no .out file corresponding to the query you intend to run. If there is, your search will stall.