hamlib-primer

title: hamlib-primer(7)

text:
# hamlib-primer(7)

## NAME
hamlib-primer - compiling and using the radio and rotator control library

## DESCRIPTION
There are several ways to obtain a working installation of Hamlib. The following sections discuss installing from a package manager, building from source, and installing Hamlib project supplied binaries on Microsoft Windows®.

### Installing binary packages on Linux and BSD
The easiest way to install a released version of Hamlib on a Linux based distribution or a BSD variant is through the provided package manager. While package managers vary according to the distribution (it's easy to lump BSD variants in this group too) their end goal is to provide ready to use software packages. Since such a wide variety of package managers exist, it is best to recommend that the documentation for your chosen distribution be your guide.

### A variety of Hamlib sources
Distribution packages are most often official Hamlib releases and in some cases could be quite old and lacking support for newer radios or rotators. In some cases support is improved in existing radio or rotator back ends and bugs are fixed in newer releases. Often times to get the improved support/bug fixes, building from source will be required. Relax, it's not hard. :-)

Source code is available as official releases, testing snapshots, daily development snapshots, and the bleeding edge of development directly from the Git repository. As a rule, even the bleeding edge tarballs should configure and compile without error even though certain implementation work may be in progress and may be incomplete or have errors.

### Getting released source
Official Hamlib source releases, commonly called tarballs can be found on the SourceForge.net Hamlib files Web page. The most recent release is listed first.

### Getting source snapshots
Testing release candidates (RCs) are posted during the period (often a few weeks) before a planned release. Beginning with the 4.0 release, RCs are hosted by the SourceForge.net Hamlib files Web page. RCs are identified by having a ~rcX suffix where the X is replace by a numeral for successive release candidates.

Daily snapshots of the development repository are available via the World Wide Web from Hamlib Git daily snapshots. These are not official releases but are provided for testing new features and bug fixes.

The daily development snapshot is made and posted each day by around 1030 UTC. Daily snapshots should compile but sometimes a bug creeps in that prevents compilation. If that should happen, please report it to the hamlib-developer mailing list.

### Git repository
The source repository can be cloned which copies the repository to your computer including its entire history, branches, and release tag information. In other words, once the git(1) clone command is finished a complete copy of the Hamlib development will be on your computer. You can do quite a lot with this as nothing is hidden from view since the entire history of Hamlib is right there all the way from the very first commit to the present. None of the meta-data is hidden away on some central server.

To clone the repository use the following command:

```
git clone https://git.code.sf.net/p/hamlib/code hamlib
```

or:

```
git clone https://github.com/Hamlib/Hamlib.git
```

Odds are that you will want to run the above command in a sub directory of your home directory. The hamlib directory will be created by Git and the master branch will be checked out for you as the working copy. The master branch is one of several branches used in Hamlib development. It is the main branch of new features and bug fixes. The working copy will be the latest revision of every file at the time of the clone. Later updates from the developers will require using another Git command to update your local repository.

### Building from source
Building from source will be required for various reasons. Perhaps only an older release is provided by your distribution, or you would like to test recent changes to Hamlib—either a specific back end or API changes—and offer a report to the developers, or you would like to take part in development and offer your contribution to the project, or you would just like to learn how to build a relatively comprehensive package from source. Any is a good reason to build from the source code archive.

Before going further, this manual assumes familiarity with working from the command prompt in a Linux/BSD/Unix like system's Bourne shell environment (compatible Bourne shells include bash(1), ksh(1), zsh(1), and several more) either in a virtual console (a text only screen with no graphics) or in a terminal in a desktop environment (xterm(1), rxvt(1), konsole(1) (included with the KDE desktop), gnome-terminal(1), xfce4-terminal(1), terminal(1) (included in macOS), etc.). If this is new to you, take some time and read up on using the shell. A good tutorial can be found at LinuxCommand.org which also offers an in-depth book that can be purchased or downloaded for no cost (the Hamlib project is not associated with nor has any interest in the sale of this book, it just looks like a very good effort on the part of its author).

Let's get started.

### Compiling source tarballs
Before proceeding, it is essential to read the information in the files, README.md, INSTALL, and README.betatester supplied in the Hamlib top-level directory which will be named something like hamlib-3.3~git where the latter part is the release version. In this case the 3.3~git indicates this is a development snapshot of the Git master branch. These files provide detailed information for compiling Hamlib and will vary some from release to release.

Compiling from a source tarball whether it is an official release or a testing or daily development snapshot follows the same set of commands, known as the three step which are each run from the top-level directory:

```
./configure
make
sudo make install
```

### configure
The ./configure command examines your system and checks it for any packages that are required or good to have options for compiling Hamlib. The leading ./ tells the shell to only run the configure command found in the current directory. It is always possible that a configure command could be lurking elsewhere and we don't want to run that!

Run:

```
./configure
```

from the top-level directory.

Note: Some distributions are configured so commands can only be run from directories listed in the PATH environment variable. The ./ is necessary or the configure command will not be run as the current directory (defined as .) is not in the PATH. This is considered a default security feature so that only programs provided by the distribution are run. PATH can be modified for your own session, but that is a topic for the LinuxCommand.org reference above.

Of course, things are usually complicated a bit by options and Hamlib is no exception. The good news is that the defaults, i.e., no options, work well in most situations. Options are needed to enable the compilation of certain portions of Hamlib such as the language bindings. Optional features usually require that more development tools are installed. The INSTALL and README.betatester files in the Hamlib top-level directory will have details on the options available for that release.

A useful option is --prefix which tells configure where in the file system hierarchy Hamlib should be installed. If it is not given, Hamlib will be installed in the /usr/local file system hierarchy. Perhaps you want to install to your home directory instead:

```
./configure --prefix=$HOME/local
```

Note: For practice you may wish to start out using the --prefix=$HOME/local option to install the Hamlib files into your home directory and avoid overwriting any version of Hamlib installed into the system directories. The code examples in the remainder of this manual will assume Hamlib has been installed to $HOME/local.

As a result of this option, all of the files will be installed in the local directory of your home directory. local will be created if it does not exist during installation as will several other directories in it. Installing in your home directory means that root, or superuser (administrator) privileges are not required when running make install. On the other hand, some extra work will need to be done so other programs can use the library. The utilities that are compiled as a part of the Hamlib build system will work as they are linked to the library installed under local. Running them will require declaring the complete path:

```
local/bin/rigctl
```

or modifying your shell's PATH environment variable (see the shell tutorial site above).

Another useful option is --help which will give a few screens full of options for configure. If in a desktop environment the scroll bar can be used to scroll back up through the output. In either a terminal or a virtual console Linux supports the Shift-PageUp key combination to scroll back up. Conversely, Shift-PageDown can be used to scroll down toward the end of the output and the shell prompt (Shift-UpArrow/Shift-DownArrow may also work to scroll one line at a time (terminal dependent)).

After a fair amount of time, depending on your computer, and a lot of screen output, configure will finish its job. So long as the few lines previous to the shell prompt don't say “error” or some such failure message Hamlib is ready to be compiled. If there is an error and all of the required packages listed in README.betatester have been installed, please ask for help on the hamlib-developer mailing list.

### make
The make(1) command is responsible for running the compiler which reads the source files and from the instructions it finds in them writes object files which are the binary instructions the CPU of a computer can execute. make then calls the linker which puts the object files together in the correct order to create the Hamlib library files and its executable programs.

Run:

```
make
```

from the top-level directory.

Any error that causes make to stop early is cause for a question to the hamlib-developer mailing list.

In general make will take longer than configure to complete its run. As it is a system command, and therefore found in the shell's PATH environment variable, prefixing make with ./ will cause a “command not found” error from the shell.

### make install
Assuming that you have not set the installation prefix to your home directory, root (administrator) privileges will be required to install Hamlib to the system directories. Two popular methods exist for gaining root privileges, su(1) and sudo(8). sudo is probably the most popular these days, particularly when using the Ubuntu family of distributions.

Run:

```
sudo make install
```

or:

```
$ su -l
Password:
# make install
```

as root from the top-level directory.

Note: The shell session is shown to show the change in prompt from a normal user account to the root account.

The -l option to su forces a login shell so that environment variables such as PATH are set correctly.

Running make install will call the installer to put all of the newly compiled files and other files (such as this document) in predetermined places set by the --prefix option to configure in the directory hierarchy (yes, this is by design and make is not just flinging files any old place!).

A lot of screen output will be generated. Any errors will probably be rather early in the process and will likely be related to your username not having write permissions in the system directory structure.

### ldconfig
Once the installation is complete one more step is required if Hamlib has never been installed from a local build before. The ldconfig command tells the system library loader where to find the newly installed Hamlib libraries. It too will need to be run with root privileges:

Run:

```
sudo ldconfig
```

as root from any directory or while logged in as root from above.

Note: Subsequent installations of Hamlib will not need to have ldconfig run after each installation if a newer version of Hamlib was not installed, i.e., when recompiling the same version during development.

On some distributions a bit of configuration will be needed before ldconfig will add locally compiled software to its database. Please consult your distribution's documentation.

### Bootstrapping from a 'git clone'
Choosing to build from from a git clone requires a few more development tools (notice a theme here?) as detailed in README.developer. The most critical will be the GNU Autotools (autoconf, automake, libtool, and more) from which the build system consisting of configure, the various Makefile.ins throughout the directory structure, and the final Makefiles are generated.

In the top-level directory is the bootstrap script from which the build system is bootstrapped—the process of generating the Hamlib build system from configure.ac and the various Makefile.ams. At its completion the configure script will be present to configure the build system.

Next configure is run with any needed build options (configure --help is useful) to enable certain features or provide paths for locating needed build dependencies, etc. Environment variables intended for the preprocessor and/or compiler may also be set on the configure command line.

After the configuration is complete, the build may proceed with the make step as for the source tarballs above. Or configure --help may be run, and configure run again with specific options in which case the Makefiles will be regenerated and the build can proceed with the new configuration.

### Other make targets
Besides make install, other targets exist when running make. Running make clean from the top-level directory removes all of the generated object and executable files generated by running make freeing up considerable disk space.

Note: During development of individual source files, it is not necessary to run make clean each time before make. Simply run make and only the modified file(s) and any objects that depend on them will be recompiled. This speeds up development time considerably.

To remove even the generated Makefiles, run make distclean from the top-level directory. After this target is run, configure will need to be run again to regenerate the Makefiles. This command may not be as useful as the Makefiles do not take up much space, however it can be useful for rebuilding the Makefiles when modifying a Makefile.am or configure.ac during build system development.

### Parallel build trees
One feature of the GNU build system used by Hamlib is that the object files can be kept in a directory structure separate from the source files. While this has no effect on the make targets described above, it does help the developer find files in the source tree! One such way of using parallel builds is described in README.developer.

Parallel builds can be very useful as one build directory can be configured for a release and another build directory can be configured for debugging with different options passed to configure from each directory. The generated Makefiles are unique to each build directory and will not interfere with each other.

### Adding debugging symbols
When additional debugging symbols are needed with, for example, the GNU Debugger, gdb, the needed compiler and linker options are passed as environment variables.

Run:

```
../hamlib/configure CFLAGS="-ggdb3 -O0" CXXFLAGS="-ggdb3 -O0"
```

from a sibling build directory intended for a debugging build.

The -ggdb3 option tells the C compiler, in this case the GNU C Compiler, gcc, to add special symbols useful for GDB, the GNU debugger. The -O0 option tells gcc to turn off all optimizations which will make it easier to follow some variables that might otherwise be optimized away. CFLAGS and CXXFLAGS may be set independently for each compiler.

Note: There are a number compiler options available for controlling debugging symbols and setting optimization levels. Please consult the compiler's manual for all the details.

### Compiling for Microsoft Windows
Currently compiling is done on a Debian 10 (Buster) virtual machine using MinGW. README.build-win32 in the scripts directory has details on how this is accomplished.

### Pre-compiled binaries for Microsoft Windows
Pre-compiled binaries for Microsoft Windows 32 and 64 bit architectures (Windows NT and newer) are available for both official releases and daily development snapshots.

Official releases are available through the SourceForge.net file download service.

Daily development snapshots are available from the daily snapshots page.

Beginning with the Hamlib 1.2.15.3 release a self-extracting installer is available. Among its features are selecting which portions of Hamlib are installed. The PATH environment variable will need to be set manually per the included README.w32-bin or README.w64-bin file.

Daily development snapshots feature both a .ZIP archive and the self extracting installer.

Bug reports and questions about these archives should be sent to the hamlib-developer mailing list.

## COPYING
This file is part of Hamlib, a project to develop a library that simplifies radio and rotator control functions for developers of software primarily of interest to radio amateurs and those interested in radio communications.

Copyright © 2001-2020 Hamlib Group (various contributors)

This is free software; see the file COPYING for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

## SEE ALSO
git(1), hamlib(7), ldconfig(8), make(1), su(1), sudo(8)

## COLOPHON
Links to the Hamlib Wiki, Git repository, release archives, and daily snapshot archives are available via hamlib.org.


hamlib-utilities

package: hamlib-devel

title: hamlib-utilities(7)

text:
# hamlib-utilities(7)

## NAME
hamlib-utilities - radio and rotator control utilities of Hamlib

## DESCRIPTION
Included with the Hamlib distribution are several utility programs. Besides providing a way for developers to test new code and bug fixes, the programs also offer a reference implementation for interfacing to the Hamlib library functions both through the C API (Application Programming Interface) and offering a network accessible API.

This page summarizes the three test programs, ampctl(1) for testing amplifier back ends, rigctl(1) for testing radio back ends, and rotctl(1) for testing rotator back ends and the three network daemons, ampctld(1), rigctld(1), and rotcltd(1) for amplifier, radio, and rotator access via network sockets. Also included are three demonstration utilities, rigmem(1), rigsmtr(1), and rigswr(1) which provide functional examples of how Hamlib may be used to accomplish various tasks.

## rigctl
rigctl(1) is the most frequently used Hamlib utility. As the other ctl utilities share many of the same characteristics, much of the introductory information presented in this section is applicable to the other utility programs.

### Introduction to rigctl
Most likely the first of the Hamlib utility programs that is used is rigctl(1). rigctl is a character based interactive program and a command line program able to set or query a radio's value with a single command. rigctl is invoked from a shell command prompt with various options and additional commands.

In its most simple use as a command line program, rigctl is used to set frequency and mode by typing commands after any rigctl options:

```
rigctl F 14205000
rigctl M USB 2400
```

and then query those values:

```
rigctl f
rigctl m
```

Entering interactive mode is a simple matter of not placing any commands after any rigctl options:

```
rigctl
```

Entering interactive mode allows successive commands to be entered without exiting rigctl. Recent additions to rigctl allow command editing and history recall through use of the Readline library.

Interactive mode is indicated by the spartan prompt:

```
Rig command:
```

Commands are given at the prompt and follow the general rule that upper case letters set a value and lower case letters query a value:

```
Rig command: M
Mode: USB
Passband: 2500
Rig command: m
Mode: USB
Passband: 2500
Rig command:
```

An additional prompt is printed when more information is required by the command. For M above, rigctl prompted for the Mode and Passband values. For m above, rigctl returned the Mode and Passband values without further prompts. The command prompt is returned after each command invocation.

The above examples invoked rigctl without specifying a radio model. This is a feature where the Hamlib internal radio model 1 dummy is used. The dummy radio provides a way to test Hamlib functions without the need for actual radio hardware. However, to develop the Hamlib backend capability for a given radio, having the actual radio connected to the computer is necessary for debugging.

For example, to quickly set frequency on an Elecraft K3:

```
rigctl -m 2029 -r /dev/rig F 3900000
```

and to query the frequency and then mode:

```
rigctl -m 2029 -r /dev/rig f
3900000
rigctl -m 2029 -r /dev/rig m
LSB
2000
```

Note: the returned values do not have the prompt strings associated with interactive mode as shown above.

The -m option takes a numeric value that corresponds to a given radio back end model. The -r option takes the path to the port device on POSIX and the device name on Microsoft Windows.

Note: A complete list of supported radio models may be seen by use of the -l option:

```
rigctl -l

 Rig #  Mfg              Model         Version    Status

     1  Hamlib           Dummy         0.5        Beta

     2  Hamlib           NET rigctl    0.3        Beta

  1001  Yaesu            FT-847        0.5        Beta

  1003  Yaesu            FT-1000D      0.0.6      Alpha
.
.
.

 27002  Rohde&Schwarz    EB200         0.1        Untested

 28001  Philips/Simoco   PRM8060       0.1        Alpha

 29001  ADAT www.adat.ch ADT-200A      1.36       Beta
```

The list is long so use Shift-PageUp/Shift-PageDown on Linux, ScrollLock then PageUp/PageDown on Free BSD, or use the scrollbar to the virtual terminal window (cmd window on Microsoft Windows) or the output can be piped to more(1) or less(1), e.g., “rigctl -l | more” to scroll back up the list. The list is sorted numerically by model number since Hamlib 1.2.15.1. Model numbers of a manufacturer/protocol family are grouped together.

### rigctl reference
The complete reference for rigctl can be found in the rigctl(1) manual page.

## rotctl
Identical in function to rigctl(1), rotctl(1) provides a means for testing Hamlib functions useful for rotator control and QTH (Maidenhead gridsquare system, see Maidenhead Locator System) locator computations. As rotators have a much narrower scope than radios, there are fewer command line options and commands for rotctl.

### Introduction to rotctl
rotctl(1) is a character based interactive program and a command line program able to set or query a rotator's value with a single command. rotctl is invoked from a shell command prompt with various options and additional commands.

In its most simple use as a command line program, rotctl is used to set azimuth position and (optionally) elevation by typing commands after any rotctl options:

```
rotctl P 145.0 23.0
rotctl M 8 25
```

and then query those values:

```
rotctl p
```

Entering interactive mode is a simple matter of not placing any commands after any rotctl options:

```
rotctl
```

Entering interactive mode allows successive commands to be entered without exiting rotctl. Interactive mode allows for command editing and history recall through the use of the Readline library.

Interactive mode is indicated by the spartan prompt:

```
Rotator command:
```

Commands are given at the prompt:

```
Rotator command: M
Direction: 16
Speed: 60
Rotator command: p
Azimuth: 11.352000
Elevation: 0.000000
Rotator command: p
Azimuth: 27.594000
Elevation: 0.000000
Rotator command:
```

An additional prompt is printed when more information is required by the command. For M above, rotctl prompted for the Direction and Speed values. For p above, rotctl returned the Azimuth and Elevation values without further prompts. The command prompt is returned after each command invocation.

The above examples invoked rotctl without specifying a rotator model. This is a feature where the Hamlib internal rotator model 1 dummy is used instead. The dummy rotator provides a way to test Hamlib functions without the need for actual rotator hardware. However, to develop back end capability for a given rotator, having the actual controller connected to the computer is necessary for debugging.

For example, to quickly set position for RotorEZ:

```
rotctl -m 401 -r /dev/rotor P 100.0 0.0
```

and to query the position:

```
rotctl -m 401 -r /dev/rotor p
100.000000
0.000000
```

The returned values do not have the prompt strings associated with interactive mode as shown above.

The -m option takes a numeric value that corresponds to a given rotator back end model. The -r option takes the path to the port device on POSIX or the device name on Microsoft Windows.

Note: A complete list of supported rotator models may be seen by use of the -l option:

```
rotctl -l

 Rot #  Mfg              Model         Version    Status

     1  Hamlib           Dummy         0.5        Beta

     2  Hamlib           NET rotctl    0.3        Beta

   201  Hamlib           EasycommI     0.3        Beta

   202  Hamlib           EasycommII    0.3        Beta
.
.
.

  1201  AMSAT            IF-100        0.1        Untested

  1301  LA7LKA           ts7400        0.1        Beta

  1401  Celestron        NexStar       0.1        Untested
```

The list is long so use Shift-PageUp/Shift-PageDown on Linux, ScrollLock then PageUp/PageDown on Free BSD, or use the scrollbar to the virtual terminal window (cmd window on Microsoft Windows) or the output can be piped to more(1) or less(1), e.g. “rotctl -l | more” to scroll back up the list. The list is sorted numerically by model number since Hamlib 1.2.15.1. Model numbers of a manufacturer/protocol family are grouped together.

### rotctl reference
The complete reference for rotctl can be found in the rotctl(1) manual page.

## ampctl
The ampctl(1) utility is a recent addition to the Hamlib utilities as a part of the 4.0 development cycle. It is intended to test the Hamlib implementation of amplifier control and is similar in function to the utilities previously described. See the ampctl(1) manual page for the complete reference.

## rigctld
The rigctld(1) program is a network server that accepts the familiar commands of rigctl(1) and provides the response data over a TCP/IP network socket to an application. In this manner an application can access a rigctld instance from nearly anywhere (caveat, no security is currently provided by rigctld). Applications using rigctld do not link directly to Hamlib nor use its C API.

### Introduction to rigctld
rigctld(1) communicates to a client through a TCP network socket using text commands shared with rigctl(1). The protocol is simple; commands are sent to rigctld on one line and rigctld responds to get commands with the requested values, one per line, when successful, otherwise, it responds with one line RPRT x, where x is a negative number indicating the Hamlib error code. Commands that do not return values respond with the line RPRT x, where x is zero when successful, otherwise a negative number indicating the Hamlib error code. Each line is terminated with a newline, \n, character. This protocol is primarily for use by the NET rigctl (radio model 2) backend.

A separate Extended Response protocol extends the above behavior by echoing the received command string as a header, any returned values as a key: value pair, and the RPRT x string as the end of response marker which includes the Hamlib success or failure value. Consider using this protocol for clients that will interact with rigctld directly through a TCP network socket.

Multiple radios can be controlled on different TCP ports by use of multiple rigctld processes each listening on a unique TCP port. It is hoped that rigctld will be especially useful for client authors using languages such as Perl, Python, PHP, Ruby, TCL, and others.

### rigctld reference
The complete reference for rigctld can be found in the rigctld(1) manual page.

## rotctld
The rotctld(1) program is a network server that accepts the familiar commands of rotctl(1) and provides the response data over a TCP/IP network socket to an application. In this manner an application can access a rotctld instance from nearly anywhere (caveat, no security is currently provided by rotctld). Applications using rotctld do not link directly to Hamlib nor use its C API.

### Introduction to rotctld
rotctld(1) communicates to a client through a TCP network socket using text commands shared with rotctl(1). The protocol is simple, commands are sent to rotctld on one line and rotctld responds to get commands with the requested values, one per line, when successful, otherwise, it responds with one line RPRT x, where x is a negative number indicating the Hamlib error code. Commands that do not return values respond with the line RPRT x, where x is zero when successful, otherwise a negative number indicating the Hamlib error code. Each line is terminated with a newline, \n character. This protocol is primarily for use by the NET rotctl (rotator model 2) backend.

A separate Extended Response protocol extends the above behavior by echoing the received command string as a header, any returned values as a key: value pair, and the RPRT x string as the end of response marker which includes the Hamlib success or failure value. Consider using this protocol for clients that will interact with rotctld directly through a TCP network socket.

Multiple rotators can be controlled on different TCP ports by use of multiple rotctld processes each listening on a unique TCP port. It is hoped that rotctld will be especially useful for client authors using languages such as Perl, Python, PHP, Ruby, TCL, and others.

### rotctld reference
The complete reference for rotctld can be found in the rotctld(1) manual page.

## ampctl
The ampctld(1) utility is a recent addition to the Hamlib utilities as a part of the 4.0 development cycle. It provides network socket access for the Hamlib implementation of amplifier control and is similar in function to the network utilities previously described. See the ampctld(1) manual page for the complete reference.

## rigmem
rigmem may be used to backup and restore memory of radio transceivers and receivers.

### Introduction to rigmem
Backup and restore memory of radio transceivers and receivers. rigmem accepts commands from the command line only.

### rigmem reference
The complete reference for rigmem can be found in the rigmem(1) manual page.

## rigsmtr
rigsmtr uses Hamlib to control a radio to measure S-Meter value versus antenna azimuth.

### Introduction to rigsmtr
rigsmtr rotates the antenna from minimum azimuth to maximum azimuth. Every second, or time_step if specified in seconds, it retrieves the signal strength. Azimuth in degrees and the corresponding S-Meter level in dB relative to S9 are then printed on stdout.

To work correctly, rigsmtr needs a radio that could measure S-Meter and a Hamlib backend that is able to retrieve it, connected to a Hamlib supported rotator.

### rigsmtr reference
The complete reference for rigsmtr can be found in the rigsmtr(1) manual page.

## rigswr
rigswr may be used to measure VSWR vs frequency.

### Introduction to rigswr
rigswr uses Hamlib to control a radio to measure VSWR (Voltage Standing Wave Ratio) over a frequency range.

It scans frequencies from start_freq to stop_freq with an optional increment of freq_step (default step is 100 kHz). All values must be entered as an integer in Hertz (cycles per second).

Note: rigswr assumes that start_freq is less than or equal to stop_freq. If it is greater, rigswr will exit without doing anything.

For each frequency, rigswr transmits at 25% of total POWER during 0.5 second in CW mode and reads VSWR.

Frequency and the corresponding VSWR are then printed on stdout.

To work correctly, rigswr needs a radio that can measure VSWR and a Hamlib backend that supports reading VSWR from the radio.

### rigswr reference
The complete reference for rigswr can be found in the rigswr(1) manual page.

## COPYING
This file is part of Hamlib, a project to develop a library that simplifies radio and rotator control functions for developers of software primarily of interest to radio amateurs and those interested in radio communications.

Copyright © 2001-2020 Hamlib Group (various contributors)

This is free software; see the file COPYING for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

## SEE ALSO
less(1), more(1), ampctl(1), ampctld(1), rigctl(1), rigctld(1), rotctl(1), rotctld(1), rigmem(1), rigsmtr(1), rigswr(1), hamlib(7), hamlib-primer(7)

## COLOPHON
Links to the Hamlib Wiki, Git repository, release archives, and daily snapshot archives are available via hamlib.org.

branch: sisyphus


hasher

package: hasher

title: hasher(7)

summary: modern safe package building technology

text:
# hasher(7)

## NAME
hasher - modern safe package building technology

## SYNOPSIS
hsh [options] <path-to-workdir> <package>...

## RATIONALE
Long ago, when instrumental OS distributions made by few developers were small enough to be placed on a single CD along with their sources, there was no real package building technology. Developers built their packages in host systems that were created by installing the whole OS distribution.

Nowadays instrumental OS distributions are made by dozens if not thousands of developers. They are too large to be installed wholly. As result, traditional package building scheme in host systems no longer fits the requirements: it is insecure, unsafe and awkward.

## REQUIREMENTS
Modern package building technology should:

1.

not lower the host system security;

2.

protect itself from attacks installed by packages;

3.

protect package builds from attacks installed by other packages;

4.

ensure reliability of build results;

5.

provide reasonable performance.

## ARCHITECTURE
The hasher architecture is based on a triple-user model: an unprivileged caller user (C) and two unprivileged pseudousers; the first one (R) emulates the root user in the generated build environment, the second one (U) emulates a regular user who builds software.

Switching between the caller user and the helper users is handled by a special program hasher-priv(8). It is written with extreme caution to defend from attacks installed by unprivileged users. It is also used to purge processes left after pseudousers, to create device files, to mount filesystems, and to control resources allocated for unprivileged processes to defend from DoS-attacks.

In general, the way of a source package in hasher during the build process looks as follows:

1. Generate aptbox.

User C generates an environment (aptbox) for apt.

2. Remove the build environment that could be left by previous builds.

The removal is done sequentially: inside the build chroot by user U, inside the build chroot by user R and finally outside the build chroot by user C.

3. Generate a new build chroot framework.

User C generates the framework, which consists of helper directories and statically linked helper programs: ash(1), find(1) and cpio(1).

4. Generate a basic install environment.

This environment contains everything necessary for regular package installs. User C using apt utilities determines the set of packages required to generate the install environment. User R using static helper programs unpacks these packages.

5. Generate a basic build environment.

This environment contains the tools required for every package build. User C using apt utilities determines the set of packages, user R installs them.

6. Generate build environment for this particular package.

User U fetches package build dependencies, user C using apt utilities determines the set of packages to install, and user R installs them.

7. Build the package.

User U executes the build.

These schemes are designed to eliminate attacks of the type U->R, U->C, R->C, and all attacks targeted to root.

In order to increase performance which is essential when building a lot of packages, hasher implements caching of the basic build environment, this allows to skip steps 4 and 5.

## AUTHOR
Written by Dmitry V. Levin <ldv@altlinux.org> et al.

## REPORTING BUGS
Report bugs to https://bugzilla.altlinux.org/

## COPYRIGHT
Copyright © 2003-2022 Dmitry V. Levin <ldv@altlinux.org>

All rights reserved.

This is free software; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

## SEE ALSO
hsh(1), hasher-priv.conf(5), hasher-priv(8), hasher-useradd(8), /usr/share/doc/hasher-1.7.4/QUICKSTART.


herbstluftwm-tutorial

package: herbstluftwm

title: herbstluftwm-tutorial(7)

summary: A tutorial introduction to herbstluftwm

text:
# herbstluftwm-tutorial(7)

## NAME
herbstluftwm-tutorial - A tutorial introduction to herbstluftwm

## DESCRIPTION
This tutorial explains how to create a basic herbstluftwm setup and introduces the major herbstluftwm features. This tutorial neither covers all features nor specifies the mentioned features entirely; see herbstluftwm(1) for a compact and more complete description.

This tutorial covers these topics:

•Basic installation

•Usage of the client

•The tiling method

•Tags (or workspaces...)

•Multi-Monitor handling

## BASIC INSTALLATION
This describes two alternate installation methods. In any case, you also have to install the dependencies. Beside the standard libraries (XLib) which are found on nearly any system, you should install dzen2 (as current as possible) which is needed by the default panel.sh.

### Via the package manager
You always should prefer installing herbstluftwm via your package manager on your system. It should be called herbstluftwm.

After installing it, the default configuration file has to be copied to your home directory:

```
mkdir -p ~/.config/herbstluftwm
cp /etc/xdg/herbstluftwm/autostart ~/.config/herbstluftwm/
```

You also should activate the tab completion for herbstclient. In case of bash, you can either activate the tab completion in general or source the herbstclient-completion from the bash_completion.d directory in your bashrc. In case of zsh the tab-completion normally is activated already (if not, consider activating it).

### Directly from git
If there is no package for your platform or if you want to use the current git version, then you can pull directly from the main repository:

```
git clone https://github.com/herbstluftwm/herbstluftwm
cd herbstluftwm
make # build the binaries
# install files
mkdir -p ~/bin
# you also have to put $HOME/bin to your path, e.g. by:
echo 'export PATH=$PATH:$HOME/bin' >> ~/.bashrc # or to your zshrc, etc...
ln -s `pwd`/herbstluftwm ~/bin/
ln -s `pwd`/herbstclient ~/bin/
# copy the configuration
mkdir -p ~/.config/herbstluftwm/
cp share/autostart ~/.config/herbstluftwm/
cp share/panel.sh ~/.config/herbstluftwm/
```

•If you are using bash, then source the bash completion file in your ~/.bashrc

```
source path-to/herbstluftwm/share/herbstclient-completion
```

•If you are using zsh, then copy the share/_herbstclient file to the appropriate zsh-completion directory.

Each time there is an update, you have to do the following steps in your herbstluftwm directory:

```
git pull
make
```

## CONFIGURE HERBSTLUFTWM AS YOUR WINDOW MANAGER
As usual you can define herbstluftwm as your window manager by either selecting herbstluftwm in your login manager or by starting it in your ~/.xinitrc, mostly by writing to your xinitrc (or .xsession on some systems):

```
# start herbstluftwm in locked mode (it will be unlocked at the end of your
# autostart)
exec herbstluftwm --locked
```

After logging in the next time, you will get a default herbstluftwm session.

## FIRST START
After starting herbstluftwm, the screen is surrounded by a green frame initially, which indicates that there is only one large frame. A frame is a container where actual windows can be placed or which can be split into two frames.

Start an xterm by pressing Alt-Return, which will fill your entire screen.

## USING THE CLIENT
The only way to communicate to herbstluftwm is by using the client application called herbstclient. Its usual syntax is: herbstclient COMMAND [ARGUMENTS]. This calls a certain COMMAND within your running herbstluftwm instance. This causes some effect (which depends on the given COMMAND and ARGUMENTS), produces some output which is printed by herbstclient and lets herbstclient exit with a exit-code (e.g. 0 for success) like many other UNIX tools:

```
    shell              COMMANDS,

       ╲ COMMAND,      ARGUMENTS

        ╲ ARGUMENTS ╭────────────╮

         ╲          │            │

          V         │            V

         herbstclient         herbstluftwm

          ╱         ^            │

         ╱ output,  │            │

        ╱ exit-code ╰────────────╯

       V               output,

 shell/terminal       exit-code
```

The most simple command only prints the herbstluftwm version:

```
$ # lines prefixed with $ describes what to type, other lines describe the
$ # typical output
$ # Type: her<tab>c<tab> ve<tab>
$ herbstclient version
herbstluftwm 0.4.1 (built on Aug 30 2012)
$ herbstclient set window_border_active_color red
$ # now the window border turned red
```

The configuration of herbstluftwm only is done by calling commands via herbstclient. So the only configuration file is the autostart which is placed at ~/.config/herbstluftwm/ and which is a sequence of those herbstclient calls.

Open it in your favourite text editor and replace the Mod-line by this to use the Super-key (or also called Windows-key) as the main modifier:

```
# Mod=Mod1 # use alt as the main modifier
Mod=Mod4 # use Super as the main modifier
```

After saving the autostart file, you have to reload the configuration:

```
# the following line is identical to directly calling:
# ~/.config/herbstluftwm/autostart
herbstclient reload
```

Now you may notice that the red border color of your terminal turned green again, because the color is set in the default autostart. That’s the typical configuration workflow:

1.Try some new settings in the command line

2.Add them to the autostart file

3.Press Mod-Shift-r which calls the reload command or directly execute the autostart file from your shell to get the error messages if something went wrong.

To learn more about herbstluftwm, just go through the man page line by line and check using the herbstluftwm(1) man page what it does. For a quick introduction to the central paradigms, continue reading this.

## TILING
Initially there is one frame. Each frame has one of the two following possible types:

1.It serves as a container for windows, i.e. it can hold zero up to arbitrarily many windows. Launch several more terminals to see what happens: If there are multiple windows in one frame, they are aligned below each other. To change this layout algorithm, press Mod-space to cycle all the available layouting algorithms for the focused frame.

2.A frame also can be split into two subframes, which can be aligned next to or below each other. Press Mod-o to split to an horizontal alignment. To navigate to the fresh frame right of the old one press Mod-l. Press Mod-u to split vertically. The intuitive navigation is:

```
      ⎧ h (or ←) ⎫                 ⎧ left

      ⎪ j (or ↓) ⎪   means         ⎪ down
Mod + ⎨ k (or ↑) ⎬  ═══════> focus ⎨ up

      ⎩ l (or →) ⎭                 ⎩ right
```

To undo splitting, you can remove a frame via Mod-r. To shift some window from one frame to one of its neighbours, use the same keyboard shortcut while holding the Shift key pressed. It is not possible to resize single windows, only to resize frames. The according keyboard shortcut is the same while holding Control pressed. All in all it is:

```
                    ⎧ h (or ←) ⎫                          ⎧ left

      ⎧         ⎫   ⎪ j (or ↓) ⎪  means  ⎧ focus frame  ⎫ ⎪ down
Mod + ⎨ Shift   ⎬ + ⎨ k (or ↑) ⎬  ═════> ⎨ move window  ⎬ ⎨ up

      ⎩ Control ⎭   ⎩ l (or →) ⎭         ⎩ resize frame ⎭ ⎩ right
```

With this, you can define a custom layout. It can be printed via the layout command:

```
$ herbstclient layout
╾─┐ horizontal 50% selection=1

  ├─┐ vertical 70% selection=0

  │ ├─╼ vertical: 0x1400009

  │ └─╼ vertical:

  └─╼ max: 0x1a00009 [FOCUS]
```

Just play with it a bit to understand how it works. You also can permanently save the layout using the dump command:

```
$ herbstclient dump
(split horizontal:0.500000:1

    (split vertical:0.700000:0

        (clients vertical:0 0x1400009)

        (clients vertical:0))

    (clients max:0 0x1a00009))
$ layout=$(herbstclient dump)
```

And after some changes you can rewind to the original layout with the load command:

```
$ herbstclient load "$layout"       # mind the quotes!
```

## TAGS (OR WORKSPACES OR VIRTUAL DESKTOPS OR ....)
A tag consists of a name and a frame layout with clients on it. With the default autostart, there are nine tags named 1 to 9. You can switch to the ith tag using Mod-i, e.g. Mod-4 to switch to tag 4 or with the command use 4. A window can be move to tag i via Mod-Shift-i, i.e. with the move command.

## MONITORS
The notion of a monitor in herbstluftwm is treated much more abstract and general than in other window managers: A monitor just is a rectangular part of your screen which shows exactly one tag on it.

Initially there is only one large monitor ranging over your entire screen:

```
$ herbstclient list_monitors
0: 1440x900+0+0 with tag "1" [FOCUS]
```

The output shows that there is only one monitor with index 0 at position +0+0 of size 1440x900 showing tag 1. In most cases, the herbstluftwm monitors will match the list of physical monitors. So to add another physical monitor, you have to perform several steps:

1.Enable it, such that it shows a part of your screen. You can use xrandr, xinerama or any other tool you like.

2.Register it in herbstluftwm: Lets assume your new monitor has the resolution 1024x768 and is right of your main screen, then you can activate it via:

```
$ herbstclient set_monitors 1440x900+0+0 1024x768+1440+0
```

Alternatively, if xinerama or xrandr works for your setup, simply run:

```
$ herbstclient detect_monitors
```

For even more automation, you can enable the setting auto_detect_monitors. For more advanced examples, look at the q3terminal.sh example script, which implements a drop-down-terminal like monitor where you can put any application you like.


ibacm

package: ibacm

title: ibacm(7)

text:
# ibacm(7)

## NAME
ibacm - InfiniBand communication management assistant

## SYNOPSIS
\#include <infiniband/acm.h>

## DESCRIPTION
Used to resolve remote endpoint information before establishing communications over InfiniBand.

## NOTES
Th IB ACM provides scalable address and route resolution services over InfiniBand. It resolves system network names and IP addresses to InfiniBand path record data using efficient mechanisms, including caching of data.

The IB ACM provides information needed to establish a connection, but does not implement the communication management protocol. It provides services similar to rdma_getaddrinfo, rdma_resolve_addr, and rdma_resolve_route using IB multicast. The IB ACM does not require IPoIB or use standard naming services, such as DNS, and limits network communication, especially with the IB SA. The ib_acme utility assists in verifying what options of the ibacm service may be usable for the current fabric topology.

Client interactions with the ibacm service are done over sockets through a standard TCP connection. The librdmacm abstracts this interaction.

## RETURN CODES
== 0

success

!= 0

error

## SEE ALSO
ib_acme(1), ibacm(8)


title: ibacm_prov(7)

text:
# ibacm_prov(7)

## NAME
ibacm_prov - InfiniBand communication management assistant provider interface

## SYNOPSIS
\#include <infiniband/acm_prov.h>

## DESCRIPTION
The ibacm provider interface provides a plugin interface that allows a vendor to implement proprietary solutions to support scalable address and route resolution services over InfiniBand.

To add a provider to the ibacm core service, the provider must

1. be implemented as a shared library;

2. be installed under a configured directory, eg., /usr/lib64/ibacm;

3 export a function provider_query() that returns a pointer to its provider info

and version info.

The prototype of provider_query function is defined below:

```
int provider_query(struct acm_provider **info, uint32_t *version);
```

This function should return a pointer to its provider structure:

```
struct acm_provider {
	size_t    size;
	uint32_t  version;
	char      *name;
	int	(*open_device)(const struct acm_device *device,
			void **dev_context);
	void	(*close_device)(void *dev_context);
	int	(*open_port)(const struct acm_port *port,
			void *dev_context, void **port_context);
	void	(*close_port)(void *port_context);
	int	(*open_endpoint)(const struct acm_endpoint *endpoint,
			void *port_context, void **ep_context);
	void	(*close_endpoint)(void *ep_context);
	int	(*add_address)(const struct acm_address *addr, void *ep_context,
			void **addr_context);
	void	(*remove_address)(void *addr_context);
	int	(*resolve)(void *addr_context, struct acm_msg *msg, uint64_t id);
	int	(*query)(void *addr_context, struct acm_msg *msg, uint64_t id);
	int	(*handle_event)(void *port_context, enum ibv_event_type type);
	void	(*query_perf)(void *ep_context, uint64_t *values, uint8_t *cnt);
};
```

The size and version fields provide a way to detect version compatibility. When a port is assigned to the provider, the ibacm core will call the open/add_address functions; Similarly, when a port is down or re-assigned to another provider, the close/remove_address functions will be invoked to release resources. The ibacm core will centralize the management of events for each device and events not handled by the ibacm core will be forwarded to the relevant port through the handle_event() function. The resolve() function will be called to resolve a destination name into a path record. The performance of the provider for each endpoint can be queried by calling perf_query().

To share a configuration file, the path for the ibacm configuration file is exported through the variable opts_file. Each loaded provider can open this configuration file and parse the contents related to its own operation. Non-related sections should be ignored.

Some helper functions are also exported by the ibacm core. For example, the acm_log define (or the acm_write() function) can be used to log messages into ibacm's log file (default /var/log/ibacm.log). For details, refer to the acm_prov.h file.

## NOTES
A provider should always set the version in its provider info structure as the value of the define ACM_PROV_VERSION at the time the provider is implemented. Never set the version to ACM_PROV_VERSION itself as the define may be changed over time when the provider interface is changed, unless the provider itself is placed in ibacm source tree. This is to avoid the version problem when the old provider implementation is built against a new acm_prov.h file. The ibacm will always check the version of the provider at loading time.

## SEE ALSO
ib_acme(1), ibacm(7), ibacm(8)


ibus-emoji

package: ibus

title: ibus-emoji(7)

summary: Call the IBus emoji utility by

text:
# ibus-emoji(7)

## NAME
ibus-emoji - Call the IBus emoji utility by IBus Emojier

## SYNOPSIS
/usr/libexec/ibus-ui-emojier [OPTION]...

## DESCRIPTION
IBus Emojier provides a GUI to select an emoji by typing an emoji annotation or choosing a character with mouse click and it's designed to work as an extended IBus lookup window using Space, Enter, and Arrow keys. The text entry accepts an emoji annotation or Unicode points. If IBus panel is launched, IBus panel calls IBus Emojier with a shortcut key or the right click menu and output the selected emoji on the previous focused text on an application. If IBus panel is not available likes GNOME desktop, You can still use ibus emoji command to launch IBus Emojier and it saves the selected emoji in your clipboard and you can paste the emoji by a paste key likes Control-v.

Refer emoji section in ibus (1) for the command line options.

Homepage: https://github.com/ibus/ibus/wiki

## SETTINGS
ANNOTATION LANGUAGE

You can choose a language of emoji annotations with ibus-setup (1).

FONT

You can choose an emoji font with ibus-setup (1). E.g. "Noto Color Emoji", "Android Emoji" font.

## KEYBOARD OPERATIONS
Super-Period or Super-Semicolon

Launch IBus Emojier. The shortcut key can be customized by ibus-setup (1).

Left, Right arrow, Control-b or Control-f

Select the next left or right category or emoji on the list if an annotation is not typed. Otherwise move the cursor to the immdediate left or right in the typed annotation.

Down, Up arrow, Control-n or Control-p

Select the next top or down category or emoji on the list

Enter

Commit the selected emoji.

Escape

Go back to the category list from emoji list, erase the typed annotation, and close IBus Emojier.

Space

Select the next left category or emoji on the list. If Shift-Space is typed, a space chararacter can be inserted between words in an annotation or Unicode points. E.g. 1f466 Shift-Space 1f3fb

PageDown, PageUp, Control-Shift-n or Control-Shift-p

Move to the next or previous page in the category or emoji list.

Head, End, Control-h or Control-e

Select the first or last emoji on the list if an annotation is not typed. Otherwise move the cursor to the head or end in the typed annotation.

Control-u

Erase the typed annotation.

Control-x or Control-v or Control-c

Cut the selected annotation to the clipboard with Control-x. Paste the contents of the clipboard into the annotation entry with Control-v. Copy the selected annotation to the clipboard with Control-c.

Control-Shift-c

Copy the selected emoji to the clipboard.

## BUGS
If you find a bug, please report it at https://github.com/ibus/ibus/issues


icmconf

package: icmake

title: icmconf(7)

summary: Configuration file for the icmbuild(1)

text:
# icmconf(7)

## NAME
icmconf - Configuration file for the icmbuild(1) program maintenance script

## DESCRIPTION
The icmconf configuration file is used to configure program maintenance performed by icmbuild(1). It uses various directives determining how the program or library maintenance is performed.

Icmconf’s directives are biased towards the construction of C++ programs, but program maintenance for other languages (e.g., C) can also easily be configured.

The icmbuild(1) script ignores empty lines and lines whose first non-blank characters are two consecutive forward slashes (//) or start with a hash-character (#). Long lines can be split over multiple lines by writing a final backslash character at lines continuing at the next line.

## CLASS DEPENDENCIES
Traditional make-utilities recompile all dependent sources once header files are modified. When developing C++ programs this is hardly ever requird, as adding new member functions to classes does not require you to recompile already existing source files. Recompilation is required when the data member organization of classes is altered.

To handle class dependencies in a more sensible way, icmake(1) checks class dependencies using its support programs icm-dep, visiting the classes listed in the CLASSES file if icmconf’s USE_ALL directive was specified. If a directory mentioned in the CLASSES file contains a file having a name equal to the name specified at the USE_ALL parameter, then all sources of classes that depend on that particular class are also recompiled. In practice this means that when you change the data organization of a class you only need to touch it that directory the file whose name was specified by the USE_ALL directive. E.g., if your class is named Data, its sources are in the sub-directory ./data, and #define USE_ALL "a" was specified then after modifying the data organization of the class Data you only need to issue the command touch data/a. Subsequently, at the next icmbuild call all sources in ./data as well as all sources in directories whose (header) files include data.h are recompiled as well.

Likewise, if #define SPCH or (deprecated) #define PRECOMP was used, a similar action is performed for the precompiled headers: if a local file that’s (directly or indirectly) included by internal header files has changed, then the Single Pre-Compiled Header (SPCH) file is recompiled (or (deprecated), having specified PRECOMP the modified class headers are recompiled).

The icmbuild(1) script itself does not inspect these dependencies, but calls the support programs icm-spch and icm-dep to perform the requird tests. The usage summaries of these programs are written to the standard output stream when calling, respectively icmake -S and icmake -d.

## DEFAULT DEFINE SPECIFICATIONS
The following #defines, except for those that are shown as commented (e.g., //#define REFRESH) are required.

o

//#define ADD_LIBRARIES ""

when a program must be linked against additional libraries (other than the name of the program’s library itself (cf. LIBRARY, below) then those libraries should be specified here. E.g., when a program is linked against libbobcat then the specification is:

```
    #define ADD_LIBRARIES  "bobcat"

```

If your program is linked against multiple libraries, then use a blank-separated list of libraries (like #define ADD_LIBRARIES "bobcat math");

o

//#define ADD_LIBRARY_PATHS ""

this directtive must be specified if ADD_LIBRARIES is also specified, although it may be specified as an empty string. When additional libraries (specified at ADD_LIBRARIES) are located in non-standard library locations (e.g., not in /lib and /usr/lib) then these additional paths are (blank space separated) specified here. Specify only the paths, not the -L flags.

It is stronly advised to specify full pathnames here. Relative path specifications can be used by specifying paths relative to the directory that is specified at the TMP_DIR directive (see below);

o

//#define CLS

the clear screen directive. If defined tput clear is called to clear the terminal screen before starting compilations. By default it is not defined. Alternatively the -c option can be passed to icmbuild;

o

\#define CXX "g++"

the C++ compiler to use. For a C compiler specify, e.g., #define CC "gcc". Their settings are overruled by identically named environment variables. If only C files are compiled then #define CXX can be omitted.

By specifying, e.g., #define CXX "ccache g++" compilations use caching facilities, which may impressively reduce recompilation times. Refer to the cccache(1) man-page for details.

o

\#define CXXFLAGS "-Werror -Wall -O2"

C++ compiler options to use (here showing the default options). When the C compiler is used, use #define CFLAGS rather than CXXFLAGS. Their settings are overruled by identically named environment variables. If only C files are compiled then #define CXXFLAGS can be omitted.

Additional options can be defined by adding them to the CXXFLAGS definition. In addition, compilations use the environment variable ICMAKE_CPPSTD to set the C++ standard to use. E.g., after defining

```

    ICMAKE_CPPSTD=--std=c++26

```

the compiler uses the options

```
    --std=c++26 -Werror -Wall -O2

```

o

//#define DEFCOM "..."

a DEFCOM directive may be added to the icmconf file (the icmstart(1) script can do this for you). It can be specified as:

```
    #define DEFCOM  "program"

```

in which case icmbuild does program maintenance, or as

```
    #define DEFCOM  "library"

```

in which case icmbuild does library maintenance.;

o

//#define ICM_DEP "-V go"

the existence and implied existence of USE_ALL files (see the description of the USE_ALL directive). When the (deprecated) PRECOMP directive is specified the recency of precompiled headers is ensured (see also the SPCH description, below). By default icm_dep is called with the shown default arguments. If icm_dep should not be called define ICM_DEP as an empty string (""). Icmake(1)’s man-page contains a separate section about the icm_dep support program;

o

\#define IH ".ih"

the extension used for internal header files. See #define SPCH below. If SPCH is specified the ttI#define H) directive must also be specified;

o

//#define LDFLAGS ""

linker options to use. By default no options are passed to the linker. Its setting is overruled by an identically named environment variable;

o

//#define LIBRARY "ofiles"

by defining this directive a local library (libofiles.a) is constructed. When a binary program is built it is linked against this library rather than to the individual object files.

If a library instead of a program must be constructed (see also the DEFCOM directive), then the LIBRARY directive specifies the library’s base name (without the lib prefix and without the .a extension). In that case source files are expected in sub-directories of the project’s main directory (i.e., the directory containing icmconf). In that case avoid having source and header files in the project’s main directory. Instead, move such files to a separate sub-directory;

o

//#define MAIN "main.cc"

the source file in which the int main function is defined. This directive is required when doing program (rather than library) maintenance.

Note: if source files are located in the project’s main directory but library maintenance is intended (e.g., by specifying #define DEFCOM library) then define MAIN to specify a pseudo main source, whose base name is the base name of the header file in the project’s main directory. This, however, is considered a kludge, and should be avoided by moving those source and header files to a separate sub-directory;

o

//#define MULTICOMP "..."

Example: #define MULTICOMP "jobs -q"

This directive activates threaded compilation of source files. When used its first word specifies the name of a file to contain information about which files must be compiled. This must be a plain filename, not containing directory specifiers (like /). Refer to the icmake(1) man-page’s section ICM-MULTICOMP covering options, arguments, and usage of icm-multicomp which is called when #define MULTICOMP is specified;

o

//#define NO_PRECOMP_WARNING"

when #define PRECOMP (now deprecated) is specified (see below) a warning is issued when a class-directory does not contain a IH file. Such warnings are suppressed by defining NO_PRECOMP_WARNING. This option is only considered when #define PRECOMP is specified;

o

\#define OBJ_EXT ".o"

this directive specifies the extension of object modules created by the compiler;

o

//#define PRECOMP "-x c++-header"

(deprecated, consider declaring #define SPCH instead)

define this directive to construct class-specific pre-compiled headers (in which case the IH) directive must also be specified. Dependencies between (precompiled) headers are automatically considered.

Existing precompiled headers are removed by icmbuild cleangch (or icmbuild clean. When source files of other languages are compiled the PRECOMP’s -x argument must be adapted to those languages;

o

//#define REFRESH

define REFRESH to relink the binary program when icmbuild program is called, even when no file was (re)compiled. This is useful when the program links to external libraries which were updated separately from the currrent project;

o

//#define SHARED

this directive is only interpreted when LIBRARY is also specified. If defined a shared library (extension .so*) is built in addition to a static library (extension .a);

The shared library receives VERSION as its version number while soft links using VERSION’s (see below) major version number an no version number are also made available. E.g., if VERSION is defined as 1.02.03 and #define LIBRARY "demo" then the shared library becomes libdemo.so.1.02.03, with libdemo.so.1 soft-linking to it, and libdemo.so soft-linking to libdemo.so.1;

o

//#define SHAREDREQ ""

when creating a shared library SHAREDREQ specifies the names of libraries and library paths that are required by the constructed shared library itself. E.g., if a library is found in /usr/lib/special, assuming that the name of the required library is libspecial.so, then use the specification #define SHAREDREQ "-L/usr/lib/special -lspecial". The /lib and /usr/lib paths are usually automatically visited by the linker and do not have the be specified. This directive is required (possibly as an empty string) if SHARED is defined;

o

\#define SOURCES "*.cc"

the pattern to locate sources in directories;

o

//#define SPCH "..."

Example: #define SPCH ""

If #define SPCH is specified then #define IH must also be specified.

This directive activates the construction of a Single Pre-Compiled Header (SPCH). Refer to the icmake(1) man-page, section ICM-SPCH for specific details and options when constructing a SPCH. The argument string can be empty, or it can contain specifications which are used when constructing a SPCH. The --internal (or -i) option should not be specified as it is used by default when calling icmake -S.

By default the (g++) command constructing the SPCH is echoed to the standard output stream. This can be suppressed by specifying --quiet (or -q) in the SPCH string (e.g., #define SPCH "-q"). Additional options for the compiler can be specified using --option (or -o) specifications.

o

//#define SPCH_ARGS "..."

Example: #define SPCH_ARGS "specs f:compiler"

In practice the #define SPCH_ARGS specification is hardly ever required. It requires the specification of the #define SPCH directive. Refer to the icmake(1) man-page, section ICM-SPCH for specific details about this specification.

The first word (specs) defines the name of the file (used by icmake -S) to contain the names of the headers used when constructing the SPCH. If SPCH_ARGS is not specified then icmake -S by default uses specs. When SPCH_ARGS is used the specified name must be a plain filename, not containing directory specifiers (like /) or an extension.

The second word (here: f:compiler) is optional, but when provided defines the file containing the compiler-command to use when constructing the SPCH. By default the SPCH is constructed using the following command (all on one line):

```
g++ -c -o $2 ${ICMAKE_CPPSTD} -Wall -Werror -O2 -x c++-header $1

```

To the compiler-command options specified by -o specifications provided in the #define SPCH string are added. It is also possible (but probably less convenient) to specify the command directly as SPCH_ARGS’s second word. In that case surround the command by \\’ (two backslashes and a quote) characters to ensure that the multi-word specification is interpreted by icmake -S as a single argument.

o

\#define TMP_DIR "tmp"

the directory in which intermediate results are stored. To avoid cross-device communications it’s probably best to define TMP_DIR as a sub-directory of the project’s main directory;

o

//#define USE_ALL "a"

when defining this directive icmbuild looks for directories containing files having the names defined by the USE_ALL specification. All source files in those directories as well as all source files in directories that (recursively) depend on the set of directories under consideration are recompiled, after which the USE_ALL files are removed;

o

//#define USE_ECHO ON

when defined as ON (rather than OFF) (system) commands executed by icmbuild are echoed;

o

//#define USE_VERSION

when defined (it is defined by default) a file VERSION is read by icmconf to determine the program’s or library’s version, and the project’s release years. The file VERSION must be available in the project’s main directory containing lines like:

```
    VERSION=1.02.03

    YEARS=2010-2025

```

)

## PARSER MAINTENANCE
The following directives are available in cases where a program uses a parser generator creating a parser class from a grammar specification. By default they’re all commented out, and can be removed if a parser generator is not used. See also the icmstart.rc(7) man-page (section(FINE-TUNING ICMCONF)) for an alternative way to specify the parser-related #defines.

o

//#define PARSER_DIR ""

the sub-directory containing the parser’s specification file. If the PARSER_DIR directory is specified then all other directives in this section must also be specified;

o

//#define PARSFILES ""

if the parser specification file named at PARSSPEC itself includes additional specification files, then patterns matching these additional grammar specification files should be specified here. The pattern is interpreted in the directory specified at PARSER_DIR and could contain a subdirectory name (e.g. specs/*). When files matching the pattern are modified then a new parser is created;

o

//#define PARSFLAGS "-V"

the flags that are used when calling the program specified at PARSGEN;

o

//#define PARSGEN "bisonc++"

the name of the program generating the parser;

o

//#define PARSOUT "parse.cc"

the name of the file generated by the parser generator (used by icmbuild when checking the timestamps of parser specification s);

o

//#define PARSSPEC "grammar"

the name of the parser specification file. This file is expected in the directory specified by the PARSER_DIR directive.

## SCANNER MAINTENANCE
The following directives are available in cases where a program uses a scanner generator creating a lexical scanner class from a set of regular expressions. By default they’re all commented out, and can be removed if a scanner generator is not used. See also the icmstart.rc(7) man-page (section(FINE-TUNING ICMCONF)) for an alternative way to specify the scanner-related #defines.

o

\#define SCANNER_DIR ""

the subdirectory containing the scanner’s specification file. If the SCANNER_DIR directory is specified then all other directives in this section must also be specified;

o

\#define SCANFILES ""

if the lexical scanner specification file named at SCANSPEC itself includes additional specification files, then patterns matching these additional lexer specification files should be specified here. The pattern is interpreted in the directory specified at SCANNER_DIR and could contain a subdirectory name (e.g. specs/*). When files matching the pattern are modified then a new lexical scanner is created. By default no additional specification files are used;

o

\#define SCANFLAGS ""

the flags that are used when calling the program specified at SCANGEN;

o

\#define SCANGEN "flexc++"

the name of the program generating the lexical scanner;

o

\#define SCANOUT "lex.cc"

the name of the file generated by the lexical scanner (which is used by icmbuild when checking the timestamps of scanner specification s).

o

\#define SCANSPEC "lexer"

the name of the lexical scanner specification file. This file is expected in the directory specified by the SCANNER_DIR directive.

## FILES
The mentioned paths are sugestive only and may be installation dependent:

o

/usr/share/icmake/CLASSES

: example of an icmconf CLASSES file;

o

/usr/share/icmake/icmconf

: default (skeleton) icmbuild resource files, like main.cc, usage.cc, etc.;

o

/etc/icmake

: directory containing the default system-wide icmstart(1) configuration file;

o

$HOME/.icmake

: optional user-defined directory containing user-defined specifications overruling the system-wide definitions. This directory is the proper location for a file AUTHOR defining the AUTHOR directive with the user’s name. E.g., my .icmake/AUTHOR file contains:

```
    #define AUTHOR  "Frank B. Brokken (f.b.brokken@rug.nl)";

```

## SEE ALSO
ccache(1), icmake(1), icmbuild(1), icmstart(1), icmstart.rc(7).

## BUGS
None reported.

## COPYRIGHT
This is free software, distributed under the terms of the GNU General Public License (GPL).

## AUTHOR
Frank B. Brokken (f.b.brokken@rug.nl).