Building and installing
Before you can use clipboard, you must build it from sources and optionally install it.
- First, obtain the clipboard source distribution, if you haven’t already. This file should be named something like “clipboard-20.tbz” or “clipboard-20.tgz”. The word “TARBALL” is used in place of the filename below; where you see TARBALL, type the filename instead.
- Unpack the archive. If the filename ends in .tbz, .bz, or .bz2, use bunzip2 TARBALL. If it ends in .tgz or .gz, use gunzip TARBALL. The resulting file should have a name like “clipboard-20.tar” (I’ll use “TARFILE” here); type tar xf TARFILE.
- Change your working directory so you are in the distribution directory. Assuming this is named “clipboard-20”, type cd clipboard-20.
- Build the executable by typing buildit. There are preprocessor macros you can place after the word “buildit” to include or exclude certain features.
- Install the executable. Type buildit --install. If you wish the executable to be installed in someplace other than /usr/local/bin, you can pass the directory name after the build command. For example, buildit --install /usr/bin.
This is a list of the preprocessor macros you can supply to the build process to influence the resulting program. If your compiler is gcc, append each of these to -D, for example “-DBUFSIZE=1048576 -DESCALATE”. Other compilers should work similarly.
- NO_ESCALATE
- Turns off escalated allocation. Escalated allocation is recommended if you intend to copy large amounts of data to the clipboard and you don’t want to copy from a file using the -c option. With this, clipboard starts by reading a fixed amount (64 K by default) and doubles that amount every time it increases the buffer size when reading from stdin. Thus, the increment will be 64 K for the first read, 64 K for the second read, 128 K, 256 K, etc.
- USE_FD
- Turns on an experimental feature: file–descriptor I/O. Normally, clipboard uses file streams. My own comparisons between FDs and streams has not revealed a significant difference in performance, but YMMV.
- NOARGSUPPORT
- Turns off support for command–line arguments. All I/O must then be done through stdin and stdout (i.e. the pipeline).
- NOCLIPCAT
- Turns off the feature by which, when copying multiple things, they will all be copied to the clipboard together at the end of processing (after any command–line flags have been processed). You should specify this if you turn off argument support (with NOARGSUPPORT); the clipcat feature isn’t very useful otherwise (in fact, without argument support, the clipcat code never runs).
- BUFSIZE=N
- Specify a buffer increment of N bytes. When reading from stdin, clipboard will read N bytes at a time. Doesn’t apply to direct–from–file operations or stdout. When escalated allocation is present, this is the initial increment.
- DEBUG
- Turns on lots of messages which tell you what clipboard is doing. You generally should not enable this directly; instead, use the --debug option to the build script.
buildit [option] [version] [compile-options]
You can specify one option from the list below, or no option. The version, if specified, must have the decimal removed (for example, “20” == 2.0), and is used to identify the source file and output name. If you specify no version, it will attempt to compile clipboard.c as clipboard. If you do specify a version, it will attempt to compile clipboard-VERSION.c as clipboard-VERSION. The compile-options are passed to the compiler during the build phase.
Build script options
- --debug
- Turns on a large number of messages, turns on debugging symbols, and turns off the automatic stripping of the executable. Makes the program unuseful for shell scripts, and very large (about a MB).
- --no-optimisation/no-optimization
- Turns off optimisation. Normally, clipboard is built with -O2. Implied by --debug. Not recommended for the general public.
- --optimise=N/--optimize=N
- Sets optimisation (-O) to N. In GCC 3.3, N can be 0, 1, 2, nothing (--optimise=), or ‘s’. See the compiler documentation for appropriate values for the -O flag.
- --fast=CPU
- Uses gcc3’s -fast option to build an executable that is as fast as possible. Requires a CPU argument that can be fed to the -mcpu= and -mtune= options. As of 2004/GCC 3.3, acceptable values are G3, G4, and G5.
- --profilable
- Includes profiling symbols in the executable, so you can use a profiler (e.g. gprof) to see a breakdown of where CPU time is being spent. Not recommended for the general public.
- --install
- Assumes the program has already been built and attempt to install it — in /usr/local/bin by default. You can supply a different location using the BINDIR environment variable. If the directory does not exist, it will be created. If the directory does exist but you do not have permission to write there, the installation will be sudone and you will be asked for your password.
Usage
Usually, you can use clipboard with no arguments, and it will figure out whether you want to copy, paste, or both.
% ps xww | clipboard > processes.txt
However, clipboard also accepts a number of arguments, short and long.
- -c, --copy, -x, --cut, -w
- Copy from stdin to the clipboard (i.e., write to the clipboard). “--cut”/“-x” is included for completeness, but what clipboard actually does is arguable.
- -v, --paste, -r
- Paste from the clipboard to stdout (i.e., read from the clipboard).
- -b, --clear
- Clear the clipboard.
- -t, --translate-newlines
- Turn on newline translation — that is, translation of line-feeds (UNIX newlines) into carriage-returns (Mac newlines) and vice versa. Opposite of -T/--no-translate-newlines. This is the default.
- -T, --no-translate-newlines
- Turn off newline translation. Opposite of -t/--translate-newlines.
- -?, -h, --help
- Prints a thorough description of options.
- -f
- Specify a file to read/write instead of stdin/stdout. This option is actually ignored; a filename is accepted with or without -f.
- -sNUM
- Sets the initial buffer size to NUM bytes. See the discussion of the ESCALATE macro above.
For each copy or paste option, you can specify zero or more options, and optionally a file name. For example:
% clipboard -c ~/Documents/log1.txt -c ~/Documents/log2.txt -v ~/Documents/log-all.txt
This would copy log1.txt and log2.txt to the clipboard (both, in order) and paste through stdout into log-all.txt. The same semantics work for the paste command, but not the clear command (because it has no use for files).
One thing worth noting: If you’re going to copy from a file, use the -c option and specify the pathname on the command–line — don’t simply redirect it in through stdin.
- WRONG:
- % clipboard < ~/Documents/log-all.txt
- RIGHT:
- % clipboard -c ~/Documents/log-all.txt
The latter command can reduce the time taken by a third if log-all.txt is large.