package: drbd-utils-pacemaker

title: ocf_linbit_drbd(7)

text:
# ocf_linbit_drbd(7)

## NAME
ocf_linbit_drbd - Manages a DRBD device as a Master/Slave resource

## SYNOPSIS
drbd [start | stop | monitor | promote | demote | meta-data | validate-all]

## DESCRIPTION
This resource agent manages a DRBD resource as a master/slave resource. DRBD is a shared-nothing replicated storage device.

NOTE: To avoid data-divergence, you should enable either DRBD "quorum" and "on-no-quorum io-error" (recommended), or configure proper fencing policies in both DRBD *and* Pacemaker (fencing resource-and-stonith). This cannot be done from this resource agent alone.

See the DRBD User's Guide for more information. https://docs.linbit.com/

## SUPPORTED PARAMETERS
drbd_resource

The name of the drbd resource from the drbd.conf file. (unique, required, string, no default)

drbdconf

Full path to the drbd.conf file. (optional, string, default "/etc/drbd.conf")

adjust_master_score

Space separated list of four master score adjustments for different scenarios: - only access to 'consistent' data - only remote access to 'uptodate' data - currently Secondary, local access to 'uptodate' data, but remote is unknown - local access to 'uptodate' data, and currently Primary or remote is known Numeric values are expected to be non-decreasing.

The first value is 0 by default to prevent pacemaker from trying to promote while it is unclear whether the data is really the most recent copy. (DRBD knows it is "consistent", but is unsure about "uptodate"ness). Please configure proper fencing methods both in DRBD (fencing resource-and-stonith; appropriate (un)fence-peer handlers) AND in Pacemaker to make this work reliably.

Advanced use: Adjust the other values to better fit into complex dependency score calculations.

Intentionally diskless nodes ("Diskless Clients") with access to good data via some (or all) their peers will use the 3rd or 4th value (minus one) when they are (Secondary, not all peers up-to-date) or (ALL peers are up-to-date, or they are Primary themselves). This may need to change if this should become a frequent use case.

Special considerations:

If a Secondary DRBD is connected to a peer in Primary role, but Pacemaker does not know about any Primary (using crm_resource --locate), we conclude that there likely is a cluster-split-brain, and may try to "help" Pacemaker by removing the master-score. Also see "remove_master_score_if_peer_primary".

(optional, string, default "0 10 1000 10000")

stop_outdates_secondary

Recommended setting: leave at default (disabled). Note that this feature depends on the passed in information in OCF_RESKEY_CRM_meta_notify_master_uname to be correct, which unfortunately is not reliable for pacemaker versions up to at least 1.0.10 / 1.1.4.

If a Secondary is stopped (unconfigured), it may be marked as outdated in the drbd meta data, if we know there is still a Primary running in the cluster. Note that this does not affect fencing policies set in drbd config, but is an additional safety feature of this resource agent only. You can enable this behaviour by setting the parameter to true.

If this feature seems to not do what you expect, make sure you have defined fencing policies in the drbd configuration as well.

(optional, boolean, default false)

ignore_missing_notifications

Some setups do not benefit from notifications. Allow to disable notifications without patching this resource agent. (optional, boolean, default false)

wfc_timeout

Unless set to the empty string or any non-digits, wait (at most) this many seconds for the connection(s) to be established after bringing them up during "start". (optional, integer, default 5)

remove_master_score_if_peer_primary

See also "adjust_master_score" and "fail_promote_early_if_peer_primary". To prevent a potentially failed promotion attempt in case of cluster split-brain (Pacemaker communication loss) while DRBD is still connected to a Primary, you can request to remove any master score while DRBD is connected to a Primary (and that Primary peer looks like it has all disks up-to-date).

This may delay legitimate failovers after Primary crash by up to some TCP timeout (until DRBD realizes that the Primary is gone) plus one monitoring interval.

This parameter is interpreted almost as an "ocf boolean", with the exception of a literal "unexpected", that is:

- (yes|true|1) [actually, according to the OCF spec, also (YES|TRUE|True|ja|ON), but please don't go there]: is "true": remove (or never assign) master scores, if DRBD appears to see a (healthy) Primary

- "unexpected": assign master scores as described under "adjust_master_score", while removing it if DRBD appears to see a (healthy) Primary that Pacemaker does not know about (as determined by crm_resource --locate).

- everything else is "false": ignore the peer role while assigning master scores.

(optional, string, default "false")

fail_promote_early_if_peer_primary

See also "adjust_master_score" and "remove_master_score_if_peer_primary". To avoid a useless retry loop during promotion attempts in case of cluster split-brain (Pacemaker communication loss) while DRBD is still connected to a Primary, you can chose to give up after the first try if this situation is detected.

If a Primary "vanishes", TCP may not immediately detect this, and an idle DRBD may take some time until it does in-DRBD-protocol "pings". Pacemaker may well detect Primary loss earlier than DRBD, and try to promote while DRBD thinks it can still see a Primary. Which means, in general, trying to promote at least once is necessary, as that implies an in-DRBD-protocol "peer alive" check.

But if that does not succeed, re-trying until we hit the operation timeout may not be desired, so you can disable it.

(optional, boolean, default false)

unfence_if_all_uptodate

If all volumes of this resource report to be UpToDate, call an unfence script hook, just in case some stale fencing constraint or similar is still around. - With DRBD utils version <= 8.9.4, this is hardcoded to /usr/lib/drbd/crm-unfence-peer.sh -r $DRBD_RESOURCE

- With DRBD utils version >= 8.9.5, this is dispatched to $DRBDADM unfence-peer $DRBD_RESOURCE

In any case, the hook itself is responsible to fetch $OCF_RESKEY_unfence_extra_args from its environment.

(optional, boolean, default false)

unfence_extra_args

This may be used to pass extra hints to the unfence hook. See description of unfence_if_all_uptodate. (optional, boolean, default --quiet --flock-required --flock-timeout 0 --unfence-only-if-owner-match)

require_drbd_module_version_ge

Use this you want to force failure of this resource agent if the detected DRBD kernel (module) driver version is lower than a required minimum. Example: use require_drbd_module_version_ge=9.0.16 to fail unless DRBD module version >= 9.0.16 is available (effectively requires DRBD 9).

The intention of this is to give a more useful failure message after accidentally downgrading the DRBD version by installing/upgrading a new kernel.

Note: "ge", "greater-or-equal", inclusive. Required format: x.y.z

Set empty to skip this check.

(optional, string, default "8.0.0")

require_drbd_module_version_lt

Use this you want to force failure of this resource agent if the detected DRBD kernel (module) driver version is higher than a required maximum. Example: use require_drbd_module_version_lt=9.0.0 to fail unless DRBD module version < 9.0 is available (effectively requires DRBD 8.4).

Note: "lt", "less-than", exclusive. Required format: x.y.z

Set empty to skip this check.

(optional, string, default "10.0.0")

connect_only_after_promote

This may be useful for "stacked" setups without proper fencing on the lower layer (which we obviously do not recommend), to avoid some of the ugly side effects that may arise after resolving a split-brain on the lower layer. Keep this DRBD instance disconnected until it is promoted. After promotion we issue an additional "adjust", which is supposed to initiate the connection attempts.

This causes a new data generation identifier ("current uuid") to be generated after the failover of a "healthy" DRBD.

(optional, boolean, default false)

## SUPPORTED ACTIONS
This resource agent supports the following actions (operations):

start

Starts the resource. Suggested minimum timeout: 240.

reload

Suggested minimum timeout: 30.

promote

Promotes the resource to the Master role. Suggested minimum timeout: 90.

demote

Demotes the resource to the Slave role. Suggested minimum timeout: 90.

notify

Suggested minimum timeout: 90.

stop

Stops the resource. Suggested minimum timeout: 100.

monitor (Slave role)

Performs a detailed status check. Suggested minimum timeout: 20. Suggested interval: 20.

monitor (Master role)

Performs a detailed status check. Suggested minimum timeout: 20. Suggested interval: 10.

meta-data

Retrieves resource agent metadata (internal use only). Suggested minimum timeout: 5.

validate-all

Performs a validation of the resource configuration.

## EXAMPLE CRM SHELL
The following is an example configuration for a drbd resource using the crm(8) shell:

```
primitive p_drbd ocf:linbit:drbd \

  params \

    drbd_resource=string \

  op monitor timeout="20" interval="20" role="Slave" \

  op monitor timeout="20" interval="10" role="Master"
```

```
ms ms_drbd p_drbd \

  meta notify="true" interleave="true"
```

## EXAMPLE PCS
The following is an example configuration for a drbd resource using pcs(8)

```
pcs resource create p_drbd ocf:linbit:drbd \

  drbd_resource=string \

  op monitor timeout="20" interval="20" role="Slave" \

  op monitor timeout="20" interval="10" role="Master" --master
```

## SEE ALSO
https://docs.linbit.com/, https://clusterlabs.org/, https://www.linbit.com/drbd-community/

## AUTHORS
LINBIT HA Solutions GmbH


title: ocf_linbit_drbd-attr(7)

text:
# ocf_linbit_drbd-attr(7)

## NAME
ocf_linbit_drbd-attr - import DRBD state change events as transient node attributes

## SYNOPSIS
drbd-attr [start | stop | monitor | meta-data | validate-all]

## DESCRIPTION
This listens for DRBD state change events, and sets or deletes transient node attributes based on the "promotion_score" and "may_promote" values as presented by the DRBD events2 interface.

Optionally using a dampening delay, see attrd_updater for details.

To be used as a clone on all DRBD nodes. The idea is to start DRBD outside of pacemaker, use DRBD auto-promote, and add location constraints for the Filesystem or other resource agents which are using DRBD.

## SUPPORTED PARAMETERS
dampening_delay

To be used as dampening delay in attrd_updater. (optional, integer, default 5)

attr_name_prefix

The attributes will be named "*prefix*-drbd_resource_name". You can chose that prefix here. (optional, string, default "drbd-promotion-score")

record_event_details

It may be convenient to know which event lead to the current score. This setting toggles the recording of the event. The attributes will be named "*prefix*:event-details-drbd_resource_name". (optional, boolean, default false)

## SUPPORTED ACTIONS
This resource agent supports the following actions (operations):

start

Starts the resource. Suggested minimum timeout: 20s.

stop

Stops the resource. Suggested minimum timeout: 20s.

monitor

Performs a detailed status check. Suggested minimum timeout: 20s. Suggested interval: 60s.

validate-all

Performs a validation of the resource configuration. Suggested minimum timeout: 20s.

meta-data

Retrieves resource agent metadata (internal use only). Suggested minimum timeout: 5s.

## EXAMPLE CRM SHELL
The following is an example configuration for a drbd-attr resource using the crm(8) shell:

```
primitive p_drbd-attr ocf:linbit:drbd-attr \

  op monitor timeout="20s" interval="60s" depth="0"
```

## EXAMPLE PCS
The following is an example configuration for a drbd-attr resource using pcs(8)

```
pcs resource create p_drbd-attr ocf:linbit:drbd-attr \

  op monitor timeout="20s" interval="60s" depth="0"
```

## SEE ALSO
https://docs.linbit.com/, https://clusterlabs.org/, https://www.linbit.com/drbd-community/

## AUTHORS
LINBIT HA Solutions GmbH


package: dvdauthor

title: video_format(7)

text:
# video_format(7)

## NAME
video_format - Proposal For A Video Format Preference Specification

## DESCRIPTION
A number of different programs that create or work with video material need to know whether to generate their output in NTSC or PAL format. The ones that I’ve seen seem to have a hard-coded preference for one unless the user specifies the other. Overriding the default every time you want to use these programs gets tiresome.

Therefore, there needs to be a way for the user to configure a single default that will apply to all these programs. This default should be settable on a per-user basis and a systemwide basis, with the per-user setting overriding the systemwide one, as is usual. It makes sense to avoid dotfile clutter by following, at least to some extent, the XDG Base Directory Specification http://standards.freedesktop.org/basedir-spec/latest/.

The preference setting shall consist of the single word “NTSC” or “PAL” (without quotes, might as well be case-insensitive). This can be specified in the following ways, in order of decreasing priority:

•

As the value of the environment variable VIDEO_FORMAT

•

As the contents of the user-specific file $XDG_CONFIG_HOME/video_format, with $XDG_CONFIG_HOME defaulting to $HOME/.config if not defined.

•

As the contents of a systemwide file dir/video_format, where dir is taken in turn from the colon-separated items in the value of $XDG_CONFIG_DIRS until the file is found, or if $XDG_CONFIG_DIRS is not defined, then the single directory /etc.

The application should use the first of these settings that it finds, searching in the specified order.

Note: the XDG Base Dir spec says systemwide config files should go in /etc/xdg. I'm not sure why this is, since lots of other apps put systemwide config in other places in /etc. Particularly since the spec doesn’t similarly restrict shared read-only data to just one subdirectory of /usr/share.

## DISCUSSION
Can this spec apply to both standard-definition and high-definition video? For standard definition, there is a difference of frame size, being 720 by 480 for NTSC and 720 by 576 for PAL (in both cases, the aspect ratio of the displayed image is always 4:3). But this doesn’t seem to matter for high definition. For both standard-definition and high-definition, there is a difference of frame rates, based around 29.97 fps for NTSC and 25 fps for PAL.

Note also that if a config file earlier in the search contains an invalid setting, the search does not continue even if another, later config file might contain a valid setting. This allows the user to override a system default with “no default”. Is this important? I think it could be.

## REFERENCE IMPLEMENTATION
The following Python code implements a routine called get_default_video_format that returns either one of the strings “NTSC” or “PAL” indicating the user/system-configured default format as per the spec above, or None if the default is invalid or not configured.

```
    class xdg_base_dir :

        "Implementation of relevant parts of the XDG Base Directory specification" \

        " <http://standards.freedesktop.org/basedir-spec/latest/>."

        @classmethod

        def get_config_home(self) :

            "returns the directory for holding user-specific config files."

            result = os.environ.get("XDG_CONFIG_HOME")

            if result == None :

                result = os.path.join(os.environ["HOME"], ".config")

            #end if

            return result

        #end get_config_home

        @classmethod

        def config_search_path(self) :

            "returns the list of config directories to search (apart from the user area)."

            return tuple(os.environ.get("XDG_CONFIG_DIRS", "/etc").split(":"))

              # note spec actually says default should be /etc/xdg, but /etc is the

              # conventional location for system config files.

        #end config_search_path

        @classmethod

        def find_first_config_path(self, path) :

            "searches for path in all the config directory locations in order of decreasing" \

            " priority, returning the expansion where it is first found, or None if not found."

            paths_to_try = iter((self.get_config_home(),) + self.config_search_path())

              # highest priority first

            while True :

                this_path = next(paths_to_try, None)

                if this_path == None :

                    break

                this_path = os.path.join(this_path, path)

                if os.path.exists(this_path) :

                    break

            #end while

            return this_path

        #end find_first_config_path

    #end xdg_base_dir

    valid_video_formats = frozenset(("NTSC", "PAL"))

    def get_default_video_format() :

        video_format = os.environ.get("VIDEO_FORMAT")

        if video_format == None :

            config_file = xdg_base_dir.find_first_config_path("video_format")

            if config_file != None :

                try :

                    video_format = open(config_file, "r").readline().strip()

                except OSError :

                    video_format = None

                #end try

            #end if

        #end if

        if video_format != None :

            video_format = video_format.upper()

            if video_format not in valid_video_formats :

                video_format = None

            #end if

        #end if

        return video_format

    #end get_default_video_format

```


package: dynamips

title: hypervisor_mode(7)

summary: allows you to run simultaneously

text:
# hypervisor_mode(7)

## NAME
hypervisor_mode - allows you to run simultaneously many virtual router instances, and to simulate ATM, Ethernet or Frame‐Relay networks.

## SYNOPSIS
dynamips -H [ip_address:]tcp_port

## DESCRIPTION
You can connect directly to the TCP control port with telnet, or use dynagen/dynagui that will pass commands transparently. The second method is highly recommended.

The command syntax is simple: <module> <function> [arguments...] For example: "vm start R1" starts virtual instance named "R1".

Available since version 0.2.5.

The modules that are currently defined are given below:

hypervisor General hypervisor management vm

General virtual machine (VM) management

vm_debug

General virtual machine (VM) debugging

c7200

Virtual instances of Cisco 7200

c3745

Virtual instances of Cisco 3745

c3725

Virtual instances of Cisco 3725

c3600

Virtual instances of Cisco 3600

c2691

Virtual instances of Cisco 2691

c2600

Virtual instances of Cisco 2600

c1700

Virtual instances of Cisco 1700

nio

Network Input/Output (NIO) descriptors

nio_bridge

NIO bridges (shared media)

atmsw

ATM switches

atm_bridge

ATM bridges

frsw

Frame‐Relay switches

ethsw

Ethernet switches

object_store

Object store

Hypervisor management module ("hypervisor")

hypervisor version

Display the version of dynamips.

hypervisor module_list

Display the module list.

hypervisor cmd_list <module>

Display commands recognized by the specified module.

hypervisor close

Close the current session.

hypervisor stop

Destroy all objects and stop hypervisor.

hypervisor reset

Destroy all objects. (used to get an empty configuration)

hypervisor working_dir <directory>

Set the directory to use to store files.

hypervisor save_config <filename>

Save the configuration of all objects into the specified file.

hypervisor parser_test [<a1> [... <a10>]]

Display up to 10 arguments. (since version 0.2.6-RC1)

hypervisor tsg_stats

Dump statistics about JIT code sharing to the console. (since version 0.2.8-RC3, unstable)

Virtual Machine module ("vm")

vm list

List all VM instances. (c7200, c3745, c3725, c3600, c2691, c2600, c1700)

vm list_con_ports

List all VM console TCP port. (since version 0.2.6-RC5)

vm create <instance_name> <instance_id> <platform>

Create a new router instance. The ID must be unique and is used to name files on disk. (since version 0.2.8-RC1)

vm rename <instance_name> <new_name>

Rename a router instance. (since version 0.2.11)

vm delete <instance_name>

Delete the specified instance. (since version 0.2.8-RC1)

vm start <instance_name>

Start the instance. At least the IOS image must be set. (since version 0.2.8-RC1)

vm stop <instance_name>

Stop the instance. The settings are kept. (since version 0.2.8-RC1)

vm get_status <instance_name>

Get the status of a VM instance. Return values: 0=inactive, 1=shutting down, 2=running, 3=suspended. (since version 0.2.11)

vm set_tsg <instance_name> <group_id>

Set translation sharing group. (since version 0.2.8-RC3-community, unstable)

vm set_debug_level <instance_name> <level>

Set the debug level (which is a number) for a VM. By default, no specific debug is enabled (level = 0).

vm set_ios <instance_name> <ios_file>

Set the IOS image file to use. There is no default.

vm set_config <instance_name> <startup_file> [<private_file>]

Set the config files that are pushed to startup-config and private-config in NVRAM when the instance is started. To keep existing data, use an empty string ('') for the filename. The optional <private_file> is an empty string by default. (supports <private_file> since version 0.2.10)

vm extract_config <instance_name>

Get the contents of the config files startup-config and private-config from NVRAM. The data of each file is encoded in a Base64 string, surrounded by single quotes. (returns private-config since version 0.2.10)

vm push_config <instance_name> <startup_cfg> [<private_cfg>]

Push configuration to the config files startup-config and private-config in NVRAM. The data is a Base64 encoded string, or '(keep)' to keep existing data. The optional <private_cfg> is '(keep)' by default. (supports <private_cfg> since version 0.2.11)

vm set_ram <instance_name> <ram_size>

Set the RAM size, specified in Mbytes.

vm set_nvram <instance_name> <nvram_size>

Set the NVRAM size, specified in Kbytes.

vm set_ram_mmap <instance_name> <0|1>

Enable/Disable use of a mapped file to simulate router memory. By default, a mapped file is used. This is a bit slower, but requires less memory.

vm set_sparse_mem <instance_name> <0|1>

Enable/disable use of sparse memory. (since version 0.2.7-RC1)

vm suspend <instance_name>

Suspend execution of the instance.

vm resume <instance_name>

Resume execution of the instance.

vm set_clock_divisor <instance_name> <clock_div>

Set the clock divisor value. The higher is the value, the faster is the clock in the virtual machine. The default is 4, but it is often required to adjust it.

vm set_blk_direct_jump <instance_name> <0|1>

Enable/disable use of block direct jump. (compatibility option, since version 0.2.7-RC2)

vm set_idle_pc <instance_name> <pc_value>

Set the idle Pointer Counter (PC). You must determine it through the method explained in the main README file.

vm set_idle_pc_online <instace_name> <cpu_id> <pc_value>

Set the idle PC value when the CPU is online. (since version 0.2.6-RC2)

vm get_idle_pc_prop <instance_name> <cpu_id>

Get the idle PC proposals. Takes 1000 measurements and records up to 10 idle PC proposals. There is a 10ms wait between each measurement. (since version 0.2.6-RC2)

vm show_idle_pc_prop <instance_name> <cpu_id>

Dump the idle PC proposals. (since version 0.2.6-RC2)

vm set_idle_max <instance_name> <cpu_id> <idle_max>

Set CPU idle max value. (since version 0.2.6-RC2)

vm set_idle_sleep_time <instance_name> <cpu_id> <idle_sleep_time>

Set CPU idle sleep time value. (since version 0.2.6-RC2)

vm show_timer_drift <instance_name> <cpu_id>

Show info about potential timer drift. (since version 0.2.6-RC3)

vm set_ghost_file <instance_name> <ghost_ram_filename>

Set ghost RAM file. (since version 0.2.6-RC3, needs an extra bogus argument before version 0.2.6-RC4)

vm set_ghost_status <instance_name> <ghost_status>"

Set ghost RAM status. (since version 0.2.6-RC3, needs an extra bogus argument before version 0.2.6-RC4)

vm set_exec_area <instance_name> <area_size>

Set the exec area size. The exec area is a pool of host memory used to store pages translated by the JIT (they contain the native code corresponding to MIPS code pages).

vm set_disk0 <instance_name> <value>

Set size of PCMCIA ATA disk0.

vm set_disk1 <instance_name> <value>

Set size of PCMCIA ATA disk1.

vm set_conf_reg <instance_name> <value>

Set the config register value. The default is 0x2102.

vm set_con_tcp_port <instance_name> <tcp_port>

Set the TCP port to use for console. By default, no TCP port is chosen, meaning that you cannot get access to the console.

vm set_aux_tcp_port <instance_name> <tcp_port>

Set the TCP port to use for AUX port. By default, no TCP port is chosen, meaning that you cannot get access to the AUX port.

vm cpu_info <instance_name> <cpu_id>

Show info about the CPU identified by "cpu_id". The boot CPU (which is typically the only CPU) has ID 0.

vm cpu_usage <instance_name> <cpu_id>

Show cpu usage of dynamips in seconds. (experimental)

The instance must exist, "cpu_id" is ignored. (since version 0.2.8-RC5-community)

vm send_con_msg <instance_name> <str> [<format>]

(since version 0.2.6-RC3) Send a message on the console. It only writes the bytes that fit in the console buffer.

(since version 0.2.14) The optional argument <format> indicates the string format. On success it will report "X byte(s) written".

String formats:

* plain - plain string (default, old behavior)

* base64 - base64 encoded string

vm send_aux_msg <instance_name> <str> [<format>]

(since version 0.2.6-RC3) Send a message on the AUX port. It only writes the bytes that fit in the aux buffer.

(since version 0.2.14) The optional argument <format> indicates the string format. On success it will report "X byte(s) written".

String formats:

* plain - plain string (default, old behavior)

* base64 - base64 encoded string

vm slot_bindings <instance_name>

Show slot bindings. (since version 0.2.8-RC1)

vm slot_nio_bindings <instance_name> <slot_id>

Show NIO bindings for the specified slot. (since version 0.2.8-RC1)

vm slot_add_binding <instance_name> <slot_id> <port_id> <dev_type>

Add a slot binding. (since version 0.2.8-RC1)

vm slot_remove_binding <instance_name> <slot_id> <port_id>

Remove a slot binding . (since version 0.2.8-RC1)

vm slot_add_nio_binding <instance_name> <slot_id> <port_id> <nio_name>

Add a NIO binding for a slot/port. (since version 0.2.8-RC1)

vm slot_remove_nio_binding <instance_name> <slot_id> <port_id>

Remove a NIO binding for a slot/port. (since version 0.2.8-RC1)

vm slot_enable_nio <instance_name> <slot_id> <port_id>

Enable NIO of the specified slot/port. (since version 0.2.8-RC1)

vm slot_disable_nio <instance_name> <slot_id> <port_id>

Disable NIO of the specified slot/port. (since version 0.2.8-RC1)

vm slot_oir_start <instance_name> <slot_id> <subslot_id>

OIR to start a slot/subslot. (since version 0.2.8-RC3-community)

vm slot_oir_stop <isntance_name> <slot_id> <subslot_id>

OIR to stop a slot/subslot. (since version 0.2.8-RC3-community)

Virtual Machine debugging module ("vm_debug")

Available since version 0.2.6-RC1.

vm_debug show_cpu_regs <instance_name> <cpu_id>

Dump CPU registers to the console.

vm_debug show_cpu_mmu <instance_name> <cpu_id>

Dump CPU MMU info to the console. (since version 0.2.7-RC1)

vm_debug set_cpu_reg <instance_name> <cpu_id> <reg_id> <value>

Set the value of a CPU register.

vm_debug add_cpu_breakpoint <instance_name> <cpu_id> <address>

Add a breakpoint.

vm_debug remove_cpu_breakpoint <instance_name> <cpu_id> <address>

Remove a breakpoint.

vm_debug pmem_w32 <instance_name> <cpu_id> <address> <value>

Write a 32-bit memory word to physical memory.

vm_debug pmem_r32 <instance_name> <cpu_id> <address>

Read a 32-bit memory word from physical memory.

vm_debug pmem_w16 <instance_name> <cpu_id> <address> <value>

Write a 16-bit memory word to physical memory.

vm_debug pmem_r16 <instance_name> <cpu_id> <address>

Read a 16-bit memory word from physical memory.

vm_debug pmem_cfind <instance_name> <cpu_id> <bytes> [<first> [<last>]]

Find a sequence of bytes in physical memory interval [first,last]. The byte sequence is composed of hexadecimal characters and must have a length multiple of 2. The interval defaults to the complete memory space. Only the memory of cacheable devices (ram, rom, disks, ...) is searched. (since version 0.2.12)

Virtual Cisco 7200 instances module ("c7200")

c7200 list

List all existing Cisco 7200 instances.

c7200 set_npe <instance_name> <npe_name>

Set the NPE model. For example: npe‐100, npe‐400, ... The default is "npe‐400".

c7200 set_midplane <instance_name> <midplane_name>

Set the midplane model, it can be either "std" or "vxr". The default is "vxr".

c7200 get_mac_addr <instance_name>

Get the base MAC address of the router. By default, the address is automatically generated with this pattern : ca<instance_id>.<process_pid>.0000 (Cisco format). (since version 0.2.11)

c7200 set_mac_addr <instance_name> <mac_addr>

Set the base MAC address of the router. The MAC address patern can be the Cisco format (e.g. ca01.1234.0000) or the standard format (e.g. ca:01:12:34:00:00).

c7200 set_system_id <instance_name> <system_id>

Set the system id. (since version 0.2.8-RC3-community)

c7200 set_temp_sensor <instance_name> <sensor_id> <temperature>

Set temperature for a DS1620 sensor. This can be used to simulate environmental problems like overheat. (since version 0.2.8-RC3-community)

c7200 set_power_supply <instance_name> <power_supply_id> <0|1>

Set power supply status. This can be used to simulate environmental problems like power loss. (since version 0.2.8-RC3-community)

c7200 show_hardware <instance_name>

Display virtual hardware info about the instance.

Virtual Cisco 3745 instances module ("c3745")

c3745 list

List all existing Cisco 3745 instances.

c3745 set_iomem <instance_name> <size>

Set the I/O mem size.

c3745 get_mac_addr <instance_name>

Get the base MAC address of the router. By default, the address is automatically generated with this pattern : c4<instance_id>.<process_pid>.0000 (Cisco format). (since version 0.2.11)

c3745 set_mac_addr <instance_name> <mac_addr>

Set the base MAC address of the router. The MAC address patern can be the Cisco format (e.g. c401.1234.0000) or the standard format (e.g. c4:01:12:34:00:00).

c3745 set_system_id <instance_name> <system_id>

Set the system id. (since version 0.2.8-RC3-community)

c3745 show_hardware <instance_name>

Display virtual hardware info about the instance.

Virtual Cisco 3725 instances module ("c3725")

c3725 list

List all existing Cisco 3725 instances.

c3725 set_iomem <instance_name> <size>

Set the I/O mem size.

c3725 get_mac_addr <instance_name>

Get the base MAC address of the router. By default, the address is automatically generated with this pattern : c2<instance_id>.<process_pid>.0000 (Cisco format). (since version 0.2.11)

c3725 set_mac_addr <instance_name> <mac_addr>

Set the base MAC address of the router. The MAC address patern can be the Cisco format (e.g. c201.1234.0000) or the standard format (e.g. c2:01:12:34:00:00).

c3725 set_system_id <instance_name> <system_id>

Set the system id. (since version 0.2.8-RC3-community)

c3725 show_hardware <instance_name>

Display virtual hardware info about the instance.

Virtual Cisco 3600 instances module ("c3600")

c3600 list

List all existing Cisco 3600 instances.

c3600 set_chassis <instance_name> <chassis_name>

Set the chassis model. Possible values: 3620, 3640, 3660. The default is "3640".

c3600 set_iomem <instance_name> <size>

Set the I/O mem size.

c3600 get_mac_addr <instance_name>

Get the base MAC address of the router. By default, the address is automatically generated with this pattern : cc<instance_id>.<process_pid>.0000 (Cisco format). (since version 0.2.11)

c3600 set_mac_addr <instance_name> <mac_addr>

Set the base MAC address of the router. The MAC address patern can be the Cisco format (e.g. cc01.1234.0000) or the standard format (e.g. cc:01:12:34:00:00).

c3600 set_system_id <instance_name> <system_id>

Set the system id. (since version 0.2.8-RC3-community)

c3600 show_hardware <instance_name>

Display virtual hardware info about the instance.

Virtual Cisco 2691 instances module ("c2691")

c2691 list

List all existing Cisco 2691 instances.

c2691 set_iomem <instance_name> <size>

Set the I/O mem size.

c2691 get_mac_addr <instance_name>

Get the base MAC address of the router. By default, the address is automatically generated with this pattern : c0<instance_id>.<process_pid>.0000 (Cisco format). (since version 0.2.11)

c2691 set_mac_addr <instance_name> <mac_addr>

Set the base MAC address of the router. The MAC address patern can be the Cisco format (e.g. c001.1234.0000) or the standard format (e.g. c0:01:12:34:00:00).

c2691 set_system_id <instance_name> <system_id>

Set the system id. (since version 0.2.11)

c2691 show_hardware <instance_name>

Display virtual hardware info about the instance.

Virtual Cisco 2600 instances module ("c2600")

Available since version 0.2.7-RC1.

c2600 list

List all existing Cisco 2600 instances.

c2600 set_chassis <instance_name> <chassis_name>

Set the chassis model. Possible values: 2610, 2611, 2620, 2621, 2610XM, 2611XM, 2620XM, 2621XM, 2650XM, 2651XM. The default is "2610".

c2600 set_iomem <instance_name> <size>

Set the I/O mem size.

c2600 get_mac_addr <instance_name>

Get the base MAC address of the router. By default, the address is automatically generated with this pattern : c8<instance_id>.<process_pid>.0000 (Cisco format). (since version 0.2.11)

c2600 set_mac_addr <instance_name> <mac_addr>

Set the base MAC address of the router. The MAC address patern can be the Cisco format (e.g. c801.1234.0000) or the standard format (e.g. c8:01:12:34:00:00).

c2600 set_system_id <instance_name> <system_id>

Set the system id. (since version 0.2.8-RC3-community)

c2600 show_hardware <instance_name>

Display virtual hardware info about the instance.

Virtual Cisco 1700 instances module ("c1700")

Available since version 0.2.8-RC1.

c1700 list

List all existing Cisco 1700 instances.

c1700 set_chassis <instance_name> <chassis_name>

Set the chassis model. Possible values: 1710, 1720, 1721, 1750, 1751, 1760. The default is "1720".

c1700 set_iomem <instance_name> <size>

Set the I/O mem size.

c1700 get_mac_addr <instance_name>

Get the base MAC address of the router. By default, the address is automatically generated with this pattern : d0<instance_id>.<process_pid>.0000 (Cisco format). (since version 0.2.11)

c1700 set_mac_addr <instance_name> <mac_addr>

Set the base MAC address of the router. The MAC address patern can be the Cisco format (e.g. d001.1234.0000) or the standard format (e.g. d0:01:12:34:00:00).

c1700 set_system_id <instance_name> <system_id>

Set the system id. (since version 0.2.8-RC3-community)

c1700 show_hardware <instance_name>

Display virtual hardware info about the instance.

Network Input/Output (NIO) module ("nio")

nio list

List all exiting NIOs.

nio create_udp <nio_name> <local_port> <remote_host> <remote_port>

Create an UDP NIO with the specified parameters.

nio create_udp_auto <nio_name> <local_addr> <local_port_start> <local_port_end>

Create an auto UDP NIO. (since version 0.2.8-RC3-community)

nio connect_udp_auto <nio_name> <remote_host> <remote_port>

Connect an UDP Auto NIO to a remote host/port. (since version 0.2.8-RC3-community)

nio create_unix <nio_name> <local_file> <remote_file>

Create an UNIX NIO with the specified parameters.

nio create_vde <nio_name> <control_file> <local_file>

Create a VDE NIO with the specified parameters. VDE stands for "Virtual Distributed Ethernet" and is compatible with UML (User‐Mode‐Linux) switch.

nio create_tap <nio_name> <tap_device>

Create a TAP NIO. TAP devices are supported only on Linux and FreeBSD and require root access.

nio create_gen_eth <nio_name> <eth_device>

Create a generic ethernet NIO, using PCAP (0.9.4 and greater). It requires root access. Available if compiled with GEN_ETH.

nio create_linux_eth <nio_name> <eth_device>

Create a Linux ethernet NIO. It requires root access and is supported only on Linux platforms. Available if compiled with LINUX_ETH.

nio create_null <nio_name>

Create a Null NIO.

nio create_fifo <nio_name>

Create a Null NIO.

nio crossconnect_fifo <nio_name> <nio_name>

Establish a cross-connect between 2 FIFO NIO.

nio rename <nio_name> <new_name>

Rename a NIO. (since version 0.2.11)

nio delete <nio_name>

Delete the specified NIO. The NIO can be deleted only when it is not anymore in use by another object.

nio set_debug <nio_name> <debug>

Enable/Disable debugging for the specified NIO. When debugging is enabled, received and emitted packets are displayed at screen. It is mainly used to debug interface drivers.

nio bind_filter <nio_name> <direction> <filter_name>

Bind a packet filter. Direction is 0 for receiving, 1 for sending, 2 for both. Filter freq_drop drops packets. Filter capture captures packets and is only available if compiled with GEN_ETH.

nio unbind_filter <nio_name> <direction>

Unbind a packet filter.

nio setup_filter <nio_name> <direction> [<a3> [...<a10>]]

Setup a packet filter for a given NIO. The arguments are passed on to the setup function of the filter.

Filter freq_drop has 1 argument <frequency> . It will drop everything with a -1 frequency, drop every Nth packet with a positive frequency, or drop nothing.

Filter capture has 2 arguments <link_type_name> <output_file> . It will capture packets to the target output file. The link type name is a case‐insensitive DLT_ name from the pcap library constants with the DLT_ part removed.

nio get_stats <nio_name>

Get statistics of a NIO. (since version 0.2.8-RC3-community)

nio reset_stats <nio_name>

Reset statistics of a NIO. (since version 0.2.8-RC3-community)

nio set_bandwidth <nio_name> <bandwidth>

Set bandwidth constraint. (since version 0.2.8-RC3-community)

NIO bridge module ("nio_bridge")

nio_bridge list

List all NIO bridges.

nio_bridge create <bridge_name>

Create a NIO bridge. A NIO bridge acts as a shared media (a kind of hub).

nio_bridge rename <bridge_name> <new_name>

Rename a NIO bridge. (since version 0.2.11)

nio_bridge delete <bridge_name>

Delete a NIO bridge.

nio_bridge add_nio <bridge_name> <nio_name>

Add a NIO as new port in a NIO bridge. The NIO must be created through the "nio" module.

nio_bridge remove_nio <bridge_name> <nio_name>

Remove the specified NIO as member of the NIO bridge.

Virtual Ethernet switch module ("ethsw")

ethsw list

List all Ethernet switches.

ethsw create <switch_name>

Create a new Ethernet switch.

ethsw rename <switch_name> <new_name>

Rename an Ethernet switch. (since version 0.2.11)

ethsw delete <switch_name>

Delete the specified Ethernet switch.

ethsw add_nio <switch_name> <nio_name>

Add a NIO as new port in an Ethernet switch. The NIO must be created through the "nio" module.

ethsw remove_nio <switch_name> <nio_name>

Remove the specified NIO as member of the Ethernet switch.

ethsw set_access_port <switch_name> <nio_name> <vlan_id>

Set the specified port as an ACCESS port in VLAN <vlan_id>.

ethsw set_dot1q_port <switch_name> <nio_name> <native_vlan>

Set the specified port as a 802.1Q trunk port, with native VLAN <native_vlan>.

ethsw set_qinq_port <switch_name> <nio_name> <outer_vlan>

Set the specified port as a trunk (QinQ) port. (since version 0.2.3-RC3-community)

ethsw clear_mac_addr_table <switch_name>

Clear the MAC address table.

ethsw show_mac_addr_table <switch_name>

Show the MAC address table (output format: Ethernet address, VLAN, NIO)

Virtual ATM switch module ("atmsw")

atmsw list

List all ATM switches.

atmsw create <switch_name>

Create a new ATM switch.

atmsw rename <switch_name> <new_name>

Rename an ATM switch. (since version 0.2.11)

atmsw delete <switch_name>

Delete the specified ATM switch.

atmsw create_vpc <switch_name> <input_nio> <input_vpi> <output_nio> <output_vpi>

Create a new Virtual Path connection (unidirectional).

atmsw delete_vpc <switch_name> <input_nio> <input_vpi> <output_nio> <output_vpi>

Delete a Virtual Path connection (unidirectional).

atmsw create_vcc <switch_name> <input_nio> <input_vpi> <input_vci> <output_nio> <output_vpi> <output_vci>

Create a new Virtual Channel connection (unidirectional).

atmsw delete_vcc <switch_name> <input_nio> <input_vpi> <input_vci> <output_nio> <output_vpi> <output_vci>

Delete a Virtual Channel connection (unidirectional).

Virtual ATM bridge module ("atm_bridge")

Available since version 0.2.8-RC2.

atm_bridge list

List all ATM bridges.

atm_bridge create <bridge_name>

Create a new ATM bridge.

atm_bridge rename <bridge_name> <new_name>

Rename an ATM bridge. (since version 0.2.11)

atm_bridge delete <bridge_name>

Delete an ATM bridge.

atm_bridge configure <bridge_name> <eth_nio> <atm_nio> <vpi> <vci>

Configure an ATM bridge.

atm_bridge unconfigure <bridge_name>

Unconfigure an ATM bridge.

Virtual Frame‐Relay switch module ("frsw")

frsw list

List all Frame‐Relay switches.

frsw create <switch_name>

Create a new Frame‐Relay switch.

frsw rename <switch_name> <new_name>

Rename a Frame-Relay switch. (since version 0.2.11)

frsw delete <switch_name>

Delete the specified Frame‐Relay switch. frsw create_vc <switch_name> <input_nio> <input_dlci> <output_nio> <output_dlci> Create a new Virtual Circuit connection (unidirectional).

frsw delete_vc <switch_name> <input_nio> <input_dlci> <output_nio> <output_dlci>

Delete a Virtual Circuit connection (unidirectional).

Object store module ("object_store")

Available since version 0.2.8-RC2.

object_store write <object_name> <data>

Write an object, data provided in base64 encoding.

object_store read <object_name>

Read an object and return data in base64 encoding.

object_store rename <object_name> <new_name>

Rename an object. (since version 0.2.11)

object_store delete <object_name>

Delete an object from the store.

object_store delete_all

Delete all objects from the store

object_store list

Object list.

## REPORTING BUGS
Please send bug reports to https://github.com/GNS3/dynamips/issues

## SEE ALSO
dynamips(1), nvram_export(1), dynagen(1), dynagui(1)

http://www.gns3.net/dynamips/

http://forum.gns3.net/

https://github.com/GNS3/dynamips

## OLD WEBSITES
http://www.ipflow.utc.fr/index.php/

http://www.ipflow.utc.fr/blog/

http://hacki.at/7200emu/index.php

## AUTHOR
dynamips is being maintained by Flávio J. Saraiva <flaviojs2005@gmail.com>. This manual page was initially written by Erik Wenzel <erik@debian.org> for the Debian GNU/Linux system.


title: e2tools(7)

text:
# e2tools(7)

## NAME
e2tools - utilities to manipulate files in an ext2/ext3 filesystem

## DESCRIPTION
E2tools is a simple set of GPL'ed utilities to read, write, and manipulate files in an ext2/ext3 filesystem. These utilities access a filesystem directly using the ext2fs library. I wrote these tools in order to copy files into a linux filesystem on a machine that does not have ext2 support. Of course, they can also be used on a linux machine to read/write to disk images or floppies without having to mount them or have root access.

Supported functionality:

e2cp

copy files

e2mv

move files

e2rm

remove files

e2mkdir

create directory

e2ln

create hard links

e2ls

list files/directories

e2tail

output the last part of a file

In general, to specify a directory or file on an ext2 filesystem for the e2tools utilities, use the following form:

filesystem:directory_path

The filesystem can be an unmounted partition or a regular file that's been formatted to contain an ext2 filesystem. In general, if a command takes multiple file names on the command line, if the first one contains an ext2 file specification, the rest of the files are assumed to be on the same filesystem until another one is explicitly stated:

/tmp/boot.img:/tmp/file1

/tmp/file2

/tmp/file3

/tmp/boot2.img:/tmp/file4

Files 1-3 are on /tmp/boot.img and the last file is on /tmp/boot2.img

## SEE ALSO
e2cp(1), e2ln(1), e2ls(1), e2mkdir(1), e2mv(1), e2rm(1), e2tail(1).

## AUTHOR
The e2tools were written by Keith Sheffield <sheff@pobox.com>.

This manual page was written by Lucas Wall <lwall@debian.org>, for the Debian project (but may be used by others).


ecryptfs

package: ecryptfs-utils

title: ecryptfs(7)

text:
# ecryptfs(7)

## NAME
eCryptfs - an enterprise-class cryptographic filesystem for Linux

## SYNOPSIS
mount -t ecryptfs [SRC DIR] [DST DIR] -o [OPTIONS]

## DESCRIPTION
eCryptfs is a POSIX-compliant enterprise-class stacked cryptographic filesystem for Linux. It is derived from Erez Zadok's Cryptfs, implemented through the FiST framework for generating stacked filesystems. eCryptfs extends Cryptfs to provide advanced key management and policy features. eCryptfs stores cryptographic metadata in the header of each file written, so that encrypted files can be copied between hosts; the file will be decryptable with the proper key, and there is no need to keep track of any additional information aside from what is already in the encrypted file itself. Think of eCryptfs as a sort of "gnupgfs."

## OPTIONS
KERNEL OPTIONS

Parameters that apply to the eCryptfs kernel module.

ecryptfs_sig=(fekek_sig)

Specify the signature of the mount wide authentication token. The authentication token must be in the kernel keyring before the mount is performed. ecryptfs-manager or the eCryptfs mount helper can be used to construct the authentication token and add it to the keyring prior to mounting.

ecryptfs_fnek_sig=(fnek_sig)

Specify the signature of the mount wide authentication token used for filename crypto. The authentication must be in the kernel keyring before mounting.

ecryptfs_cipher=(cipher)

Specify the symmetric cipher to be used on a per file basis

ecryptfs_key_bytes=(key_bytes)

Specify the keysize to be used with the selected cipher. If the cipher only has one keysize the keysize does not need to be specified.

ecryptfs_passthrough

Allows for non-eCryptfs files to be read and written from within an eCryptfs mount. This option is turned off by default.

no_sig_cache

Do not check the mount key signature against the values in the user's ~/.ecryptfs/sig-cache.txt file. This is useful for such things as non-interactive setup scripts, so that the mount helper does not stop and prompt the user in the event that the key sig is not in the cache.

ecryptfs_encrypted_view

This option provides a unified encrypted file format of the eCryptfs files in the lower mount point. Currently, it is only useful if the lower mount point contains files with the metadata stored in the extended attribute. Upon a file read in the upper mount point, the encrypted version of the file will be presented with the metadata in the file header instead of the xattr. Files cannot be opened for writing when this option is enabled.

ecryptfs_xattr

Store the metadata in the extended attribute of the lower files rather than the header region of the lower files.

verbose

Log ecryptfs information to /var/log/messages. Do not run eCryptfs in verbose-mode unless you are doing so for the sole purpose of development, since secret values will be written out to the system log in that case.

MOUNT HELPER OPTIONS

Parameters that apply to the eCryptfs mount helper.

key=(keytype):[KEY MODULE OPTIONS]

Specify the type of key to be used when mounting eCryptfs.

ecryptfs_enable_filename_crypto=(y/n)

Specify whether filename encryption should be enabled. If not, the mount helper will not prompt the user for the filename encryption key signature (default).

verbosity=0/1

If verbosity=1, the mount helper will ask you for missing values (default). Otherwise, if verbosity=0, it will not ask for missing values and will fail if required values are omitted.

KEY MODULE OPTIONS

Parameters that apply to individual key modules have the alias for the key module in the prefix of the parameter name. Key modules are pluggable, and which key modules are available on any given system is dependent upon whatever happens to be installed in /usr/lib*/ecryptfs/.

passphrase_passwd=(passphrase)

The actual password is passphrase. Since the password is visible to utilities (like ps under Unix) this form should only be used where security is not important.

passphrase_passwd_file=(filename)

The password should be specified in a file with passphrase_passwd_file=(passphrase). It is highly recommended that the file be stored on a secure medium such as a personal USB key.

passphrase_passwd_fd=(file descriptor)

The password is specified through the specified file descriptor.

passphrase_salt=(hex value)

The salt should be specified as a 16 digit hex value.

openssl_keyfile=(filename)

The filename should be the filename of a file containing an RSA SSL key.

openssl_passwd_file=(filename)

The password should be specified in a file with openssl_passwd=(openssl-password). It is highly recommended that the file be stored on a secure medium such as a personal USB key.

openssl_passwd_fd=(file descriptor)

The password is specified through the specified file descriptor.

openssl_passwd=(password)

The password can be specified on the command line. Since the password is visible in the process list, it is highly recommended to use this option only for testing purposes.

## EXAMPLE
The following command will layover mount eCryptfs on /secret with a passphrase contained in a file stored on secure media mounted at /mnt/usb/.

mount -t ecryptfs -o key=passphrase:passphrase_passwd_file=/mnt/usb/file.txt /secret /secret

Where file.txt contains the contents "passphrase_passwd=[passphrase]".

## SEE ALSO
mount(8)

/usr/share/doc/ecryptfs-utils/ecryptfs-faq.html

http://ecryptfs.org/

## NOTES
Do not run eCryptfs in verbose-mode unless you are doing so for the sole purpose of development, since secret values will be written out to the system log in that case. Make certain that your eCryptfs mount covers all locations where your applications may write sensitive data. In addition, use dm-crypt to encrypt your swap space with a random key on boot, or see ecryptfs-setup-swap(1).

Passphrases have a maximum length of 64 characters.

## BUGS
Please post bug reports to the eCryptfs bug tracker on Launchpad.net: https://bugs.launchpad.net/ecryptfs/+filebug.

For kernel bugs, please follow the procedure detailed in Documentation/oops-tracing.txt to help us figure out what is happening.

## AUTHOR
This manpage was (re-)written by Dustin Kirkland <kirkland@ubuntu.com> for Ubuntu systems (but may be used by others). Permission is granted to copy, distribute and/or modify this document under the terms of the GNU General Public License, Version 2 or any later version published by the Free Software Foundation.

On Debian systems, the complete text of the GNU General Public License can be found in /usr/share/common-licenses/GPL.


ecm

package: extra-cmake-modules

title: ecm(7)

summary: Extra CMake Modules

text:
# ecm(7)

## NAME
ecm - Extra CMake Modules

## INTRODUCTION
The Extra CMake Modules package, or ECM, adds to the modules provided by CMake, including ones used by find_package() to find common software, ones that can be used directly in CMakeLists.txt files to perform common tasks and toolchain files that must be specified on the commandline by the user.

In addition, it provides common build settings used in software produced by the KDE community.

While the driving force of this module is to reduce duplication in CMake scripts across KDE software, it is intended to be useful for any software that uses the CMake build system.

## USAGE
To use ECM, add the following to your CMakeLists.txt:

```
find_package(ECM REQUIRED NO_MODULE)
set(CMAKE_MODULE_PATH ${ECM_MODULE_PATH})
```

(note that you may want to append ${ECM_MODULE_PATH} to CMAKE_MODULE_PATH rather than discarding the existing value). You can then just include the modules you require, or use find_package() as needed. For example:

```
include(ECMInstallIcons)
```

Developers of KDE software will often want to use the KDE standard settings provided by ECM; they can do the following:

```
find_package(ECM REQUIRED NO_MODULE)
set(CMAKE_MODULE_PATH ${ECM_MODULE_PATH})
include(KDEInstallDirs)
include(KDECompilerSettings)
include(KDECMakeSettings)
```

Note that any combination of the above includes can be used if you only want some of the settings. Some of the functionality of KDECMakeSettings can also be selectively disabled.

### Organization
ECM provides four different types of modules.

- Core modules provide helpful macros for use in project CMake scripts. See ecm-modules(7) for more information.

- Find modules extend the functionality of CMake’s find_package() command. See ecm-find-modules(7) for more information.

- KDE modules provide common settings for software produced by KDE; much of this may also be useful to other projects. See ecm-kde-modules(7) for more information.

- Toolchain files change the build tools and targets used by CMake. See ecm-toolchains(7) for more information.

The ${ECM_MODULE_DIR}, ${ECM_FIND_MODULE_DIR} and ${ECM_KDE_MODULE_DIR} variables may be used instead of ${ECM_MODULE_PATH} if you only need some of this functionality.

## DEVELOPMENT
The ecm-developer(7) manual contains more information about developing for Extra CMake Modules.

## LICENSE
All code is licensed under the BSD 3-Clause license.

## LINKS

- Home page: https://commits.kde.org/extra-cmake-modules

- Documentation: https://api.kde.org/ecm/

- Mailing list: https://mail.kde.org/mailman/listinfo/kde-buildsystem

- IRC channel: #kde-devel on Libera Chat

- Git repository: https://commits.kde.org/extra-cmake-modules

## COPYRIGHT
KDE Developers


ecm-developer

title: ecm-developer(7)

summary: ECM Developer Reference

text:
# ecm-developer(7)

## NAME
ecm-developer - ECM Developer Reference

## WRITING MODULES
The CMake 3 documentation (and cmake-developer(7) in particular) has a lot of useful information about writing CMake modules, including a large section devoted to find modules. This guide will only highlight things that are particular to the Extra CMake Modules project.

Most of these are stylistic points. For example, the license header for a module in ECM should look like:

```
# SPDX-FileCopyrightText: 20XX Your Name <your.email@example.com>
#
# SPDX-License-Identifier: BSD-3-Clause
```

Documentation is written in reStructuredText format and put inside a bracket comment with a .rst: id after the opening bracket:

```
#[=======================================================================[.rst:
The docs
#]=======================================================================]
```

(docs/sphinx/ext/ecm.py has code to extract the rst text from a comment with such wrapping)

Functions should be used instead of macros unless there is a good reason not to (and that reason should be noted in a comment), and lowercase should be used for macros, functions and commands.

4 spaces is the generally-recommended indent, although there are several files that use 2 spaces; consistency within a file is more important than consistency across files.

If in doubt, look at how other modules in Extra CMake Modules are written, and follow the same pattern.

### Find Modules
A good template for find module documentation is:

```
#[=======================================================================[.rst:
FindFoo
-------
Finds the Foo library.
This will define the following variables:
``Foo_FOUND``

    True if (the requested version of) Foo is available
``Foo_VERSION``

    The version of Foo, if it is found
``Foo_LIBRARIES``

    This can be passed to target_link_libraries() instead of the ``Foo::Foo``

    target
``Foo_INCLUDE_DIRS``

    This should be passed to target_include_directories() if the target is not

    used for linking
``Foo_DEFINITIONS``

    This should be passed to target_compile_options() if the target is not

    used for linking
If ``Foo_FOUND`` is TRUE, it will also define the following imported target:
``Foo::Foo``

    The Foo library
In general we recommend using the imported target, as it is easier to use.
Bear in mind, however, that if the target is in the link interface of an
exported library, it must be made available by the package config file.
#]=======================================================================]
```

Note the use of definition lists for the variables.

Because of the ECMUseFindModules module, projects may easily make local copies of find modules, and may install those copies with their own CMake project config files. For this reason, find modules should include the full BSD 3-clause license:

```
#=============================================================================
# Copyright 20XX Your Name <your.email@example.com>
#
# Redistribution and use in source and binary forms, with or without
# modification, are permitted provided that the following conditions
# are met:
#
# 1. Redistributions of source code must retain the copyright
#    notice, this list of conditions and the following disclaimer.
# 2. Redistributions in binary form must reproduce the copyright
#    notice, this list of conditions and the following disclaimer in the
#    documentation and/or other materials provided with the distribution.
# 3. The name of the author may not be used to endorse or promote products
#    derived from this software without specific prior written permission.
#
# THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
# IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
# OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
# IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
# INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
# NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
# DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
# THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
# (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
# THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
#=============================================================================
```

Find modules should always provide imported targets in addition to the traditional variables (like Foo_LIBRARIES, etc).

Unlike find modules shipped with CMake, if the module requires a specific CMake version it is not enough to warn when the minimum required version is not high enough: you should also produce an error when the actual CMake version being used is not high enough. This can be done with:

```
if(CMAKE_VERSION VERSION_LESS 3.16.0)

    message(FATAL_ERROR "CMake 3.16.0 is required by FindFoo.cmake")
endif()
if(CMAKE_MINIMUM_REQUIRED_VERSION VERSION_LESS 3.16.0)

    message(AUTHOR_WARNING "Your project should require at least CMake 3.16.0 to use FindFoo.cmake")
endif()
```

The ECMFindModuleHelpers module has several useful functions and macros. For example, it allows you to replace the above version check with:

```
ecm_find_package_version_check(Foo)
```

### Components
Using ECMFindModuleHelpers, creating a find module for a library with several inter-dependent components is reasonably straightforward. After the documentation, you need to include the module and do the usual version check:

```
include(ECMFindModuleHelpers)
ecm_find_package_version_check(Foo)
```

The important macros are ecm_find_package_parse_components and ecm_find_package_handle_library_components. These take a list of components, and query other variables you provide to find out the information they require. The documentation for ECMFindModuleHelpers provides more information, but a simple setup might look like:

```
set(Foo_known_components Bar Baz)
set(Foo_Bar_pkg_config "foo-bar")
set(Foo_Bar_lib "bar")
set(Foo_Bar_header "foo/bar.h")
set(Foo_Bar_pkg_config "foo-baz")
set(Foo_Baz_lib "baz")
set(Foo_Baz_header "foo/baz.h")
```

If Baz depends on Bar, for example, you can specify this with

```
set(Foo_Baz_component_deps "Bar")
```

Then call the macros:

```
ecm_find_package_parse_components(Foo

    RESULT_VAR Foo_components

    KNOWN_COMPONENTS ${Foo_known_components}
)
ecm_find_package_handle_library_components(Foo

    COMPONENTS ${Foo_components}
)
```

Of course, if your components need unusual handling, you may want to replace ecm_find_package_handle_library_components with, for example, a foreach loop over the components (the body of which should implement most of what a normal find module does, including setting Foo_<component>_FOUND).

At this point, you should set Foo_VERSION using whatever information you have available (such as from parsing header files). Note that ecm_find_package_handle_library_components will set it to the version reported by pkg-config of the first component found, but this depends on the presence of pkg-config files, and the version of a component may not be the same as the version of the whole package. After that, finish off with

```
include(FindPackageHandleStandardArgs)
find_package_handle_standard_args(Foo

    FOUND_VAR

        Foo_FOUND

    REQUIRED_VARS

        Foo_LIBRARIES

    VERSION_VAR

        Foo_VERSION

    HANDLE_COMPONENTS
)
include(FeatureSummary)
set_package_properties(Foo PROPERTIES

    URL "https://www.foo.example.com/"

    DESCRIPTION "A library for doing useful things")
```

## SUBMITTING MODULES
Proposed new modules should be submitted using the KDE Review Board instance, and be assigned to the buildsystem and extracmakemodules groups. You should be able to point to two separate projects that will make use of the module.

The mailing list can be found at https://mail.kde.org/mailman/listinfo/kde-buildsystem.

## COPYRIGHT
KDE Developers


ecm-find-modules

title: ecm-find-modules(7)

summary: ECM Find Modules Reference

text:
# ecm-find-modules(7)

## NAME
ecm-find-modules - ECM Find Modules Reference

## INTRODUCTION
Find modules are used by the CMake find_package command to search for packages that do not provide their own CMake package config files. CMake provides an extensive set of find modules, and Extra CMake Modules (ECM) adds to that.

To use ECM’s find modules, you need to tell CMake to find the ECM package, and then add either ${ECM_MODULE_PATH} or ${ECM_FIND_MODULE_DIR} to the CMAKE_MODULE_PATH variable:

```
find_package(ECM REQUIRED NO_MODULE)
set(CMAKE_MODULE_PATH ${ECM_FIND_MODULE_DIR})
```

Using ${ECM_MODULE_PATH} will also make the modules intended for direct use by CMake scripts available (see ecm-modules(7) and ecm-kde-modules(7)).

You can also make local copies of find modules using the ecm_use_find_modules function from ECMUseFindModules, which is automatically included when ECM is found:

```
find_package(ECM REQUIRED NO_MODULE)
ecm_use_find_modules(

    DIR "${CMAKE_BINARY_DIR}/cmake"

    MODULES FindEGL.cmake
)
set(CMAKE_MODULE_PATH "${CMAKE_BINARY_DIR}/cmake")
```

This allows selective use of ECM’s find modules, and the NO_OVERRIDE argument can be used to ensure that if CMake ships its own version of that find module, it will be used instead.

## ALL FIND MODULES

### Find7Zip
Try to find 7-Zip.

If the 7-Zip executable is not in your PATH, you can provide an alternative name or full path location with the 7Zip_EXECUTABLE variable.

This will define the following variables:

7Zip_FOUND

TRUE if 7-Zip is available

7Zip_EXECUTABLE

Path to 7-Zip executable

If 7Zip_FOUND is TRUE, it will also define the following imported target:

7Zip::7Zip

Path to 7-Zip executable

NOTE:

It will see to only find the original 7-Zip, not one of the p7zip forks.

Since 5.113.0.

### Find7z
Try to find 7z.

If the 7z executable is not in your PATH, you can provide an alternative name or full path location with the 7z_EXECUTABLE variable.

This will define the following variables:

7z_FOUND

TRUE if 7z is available

7z_EXECUTABLE

Path to 7z executable

If 7z_FOUND is TRUE, it will also define the following imported target:

7z::7z

Path to 7z executable

NOTE:

Only works on Windows.

Deprecated: since 5.113, use Find7Zip.

Since 5.85.0.

### FindCanberra
Try to find Canberra event sound library.

This will define the following variables:

Canberra_FOUND

True if (the requested version of) Canberra is available

Canberra_VERSION

The version of Canberra

Canberra_LIBRARIES

The libraries of Canberra for use with target_link_libraries()

Canberra_INCLUDE_DIRS

The include dirs of Canberra for use with target_include_directories()

If Canberra_FOUND is TRUE, it will also define the following imported target:

Canberra::Canberra

The Canberra library

In general we recommend using the imported target, as it is easier to use. Bear in mind, however, that if the target is in the link interface of an exported library, it must be made available by the package config file.

Since 5.56.0.

### FindEGL
Try to find EGL.

This will define the following variables:

EGL_FOUND

True if (the requested version of) EGL is available

EGL_VERSION

The version of EGL; note that this is the API version defined in the headers, rather than the version of the implementation (eg: Mesa)

EGL_LIBRARIES

This can be passed to target_link_libraries() instead of the EGL::EGL target

EGL_INCLUDE_DIRS

This should be passed to target_include_directories() if the target is not used for linking

EGL_DEFINITIONS

This should be passed to target_compile_options() if the target is not used for linking

If EGL_FOUND is TRUE, it will also define the following imported target:

EGL::EGL

The EGL library

In general we recommend using the imported target, as it is easier to use. Bear in mind, however, that if the target is in the link interface of an exported library, it must be made available by the package config file.

Since pre-1.0.0.

### FindFFmpeg
Try to find FFmpeg components.

The following components are available:

```
AVCODEC  AVFILTER    AVDEVICE  AVFORMAT
AVUTIL   SWRESAMPLE  SWSCALE   POSTPROCESS
```

If no components are specified in the find_module call, the following ones will be choosen as default:

```
AVFORMAT AVUTIL AVCODEC
```

### Imported Targets
This module provides the following imported targets, if found:

FFmpeg::FFmpeg

For all the required FFmpeg components

FFmpeg::<component>

For each <component> that was found

### Result Variables
This will define the following variables:

FFMPEG_FOUND

System has the all required components.

FFMPEG_INCLUDE_DIRS

Include directory necessary for using the required components headers.

FFMPEG_LIBRARIES

Link these to use the required FFmpeg components.

FFMPEG_DEFINITIONS

Compiler switches required for using the required FFmpeg components.

Additionally for each of the components, the following variables will be defined:

<component>_FOUND

True if (the requestion version of) <component> is available

<component>_INCLUDE_DIRS

Include directory necessary for using the <component> headers

<component>_LIBRARIES

Link these to use <component>

<component>_DEFINITIONS

Compiler switches required for using <component>

<component>_VERSION

The components version (NOTE: always empty on Windows)

As the versions of the various FFmpeg components differ for a given release, and CMake supports only one common version for all components, use the following to specify required versions for multiple components:

```
find_package(FFmpeg 57.48 COMPONENTS AVCODEC)
find_package(FFmpeg 57.40 COMPONENTS AVFORMAT)
find_package(FFmpeg 55.27 COMPONENTS AVUTIL)
```

NOTE: version checking is skipped on Windows

Since 6.20.0.

### FindGLIB2
Try to locate the GLib2 library. If found, this will define the following variables:

GLIB2_FOUND

True if the GLib2 library is available

GLIB2_INCLUDE_DIRS

The GLib2 include directories

GLIB2_LIBRARIES

The GLib2 libraries for linking

GLIB2_INCLUDE_DIR

Deprecated, use GLIB2_INCLUDE_DIRS

GLIB2_LIBRARY

Deprecated, use GLIB2_LIBRARIES

If GLIB2_FOUND is TRUE, it will also define the following imported target:

GLIB2::GLIB2

The GLIB2 library

GLIB2::GTHREAD2

The GThread2 library (since 6.7.0)

GLIB2::GOBJECT

The GObject library (since 6.7.0)

GLIB2::GIO

The GIO library (since 6.7.0)

Since 5.41.0.

### FindGperf
Try to find GNU gperf.

If the gperf executable is not in your PATH, you can provide an alternative name or full path location with the Gperf_EXECUTABLE variable.

This will define the following variables:

Gperf_FOUND

True if gperf is available.

Gperf_EXECUTABLE

The gperf executable.

Gperf_VERSION

The gperf version. (since 5.85)

If Gperf_FOUND is TRUE, it will also define the following imported target:

GPerf::Gperf

The gperf executable.

and the following public function:

```
ecm_gperf_generate(<GperfInput> <OutputFile> <OutputVariable(|target (since 5.83))>

                   [GENERATION_FLAGS <flags>])
```

Run gperf on <GperfInput> to generate <OutputFile>, adding it to the <OutputVariable> variable which contains the source for the target where <OutputFile> is going to be built or, since KF 5.83, if the given argument is a target, to the list of private sources of that target. The target must not be an alias. The optional GENERATION_FLAGS argument is needed to pass extra parameters to gperf (note you cannot override that way the output file).

A simple invocation would be:

```
ecm_gperf_generate(simple.gperf ${CMAKE_CURRENT_BINARY_DIR}/simple.h MySources)
```

Since 5.35.0.

### FindGradle
Provides the ability to build Android AAR libraries using Gradle.

This relies on the Qt provided Gradle, so a Qt for Android installation is required.

```
gradle_add_aar(<target>

               BUIDLFILE build.gradle

               NAME <aar-name>)
```

This builds an Android AAR library using the given build.gradle file.

```
gradle_install_aar(<target>

                   DESTINATION <dest>)
```

Installs a Android AAR library that has been created with gradle_add_aar.

Since 5.76.0.

### FindIcoTool
Try to find icotool.

If the icotool executable is not in your PATH, you can provide an alternative name or full path location with the IcoTool_EXECUTABLE variable.

This will define the following variables:

IcoTool_FOUND

True if icotool is available.

IcoTool_EXECUTABLE

The icotool executable.

If IcoTool_FOUND is TRUE, it will also define the following imported target:

IcoTool::IcoTool

The icotool executable.

Since 5.49.

### FindInotify
Try to find inotify on this system. This finds:

- libinotify on Unix like systems, or

- the kernel’s inotify.

This will define the following variables:

Inotify_FOUND

True if inotify is available

Inotify_LIBRARIES

This has to be passed to target_link_libraries()

Inotify_INCLUDE_DIRS

This has to be passed to target_include_directories()

On some platforms like Linux and SunOS, the libraries and include directories are empty, even though Inotify_FOUND may be set to TRUE. This is because no special includes or libraries are needed. On other systems these may be needed to use inotify.

Since 5.32.0.

### FindIsoCodes
Try to find iso-codes data files. Once done this will define:

IsoCodes_FOUND

Whether the system has iso-codes

IsoCodes_PREFIX

The location in which the iso-codes data files are found

IsoCodes_DOMAINS

The available domains provided by iso-codes

Since 5.80.0.

### FindKF5
Find KDE Frameworks 5 with a single find_package() call.

This will use the package config files provided by the individual frameworks. For example, if you wish to find KArchive, which presents itself to CMake as KF5Archive (ie: you would do find_package(KF5Archive) to find it directly), you can do

```
find_package(KF5 COMPONENTS Archive)
```

If all the required components (those given in the COMPONENTS argument, but not those given in the OPTIONAL_COMPONENTS argument) are found, KF5_FOUND will be set to true. Otherwise, it will be set to false.

Since pre-1.0.0.

### FindLibExiv2
Try to find the Exiv2 library.

This will define the following variables:

LibExiv2_FOUND

True if (the requested version of) Exiv2 is available

LibExiv2_VERSION

The version of Exiv2

LibExiv2_INCLUDE_DIRS

The include dirs of Exiv2 for use with target_include_directories()

LibExiv2_LIBRARIES

The Exiv2 library for use with target_link_libraries(). This can be passed to target_link_libraries() instead of the LibExiv2::LibExiv2 target

If LibExiv2_FOUND is TRUE, it will also define the following imported target:

LibExiv2::LibExiv2

The Exiv2 library

In general we recommend using the imported target, as it is easier to use. Bear in mind, however, that if the target is in the link interface of an exported library, it must be made available by the package config file.

Since 5.53.0.

### FindLibGit2
Try to find libgit2 on a Unix system.

This will define the following variables:

LIBGIT2_FOUND

True if (the requested version of) libgit2 is available

LIBGIT2_VERSION

The version of libgit2

LIBGIT2_LIBRARIES

This can be passed to target_link_libraries() instead of the LibGit2::LibGit2 target

LIBGIT2_INCLUDE_DIRS

This should be passed to target_include_directories() if the target is not used for linking

LIBGIT2_DEFINITIONS

This should be passed to target_compile_options() if the target is not used for linking

If LIBGIT2_FOUND is TRUE, it will also define the following imported target:

LibGit2::LibGit2

The libgit2 library

In general we recommend using the imported target, as it is easier to use. Bear in mind, however, that if the target is in the link interface of an exported library, it must be made available by the package config file.

Since 1.3.0.

### FindLibMount
Try to find the libmount library (part of util-linux), once done this will define:

LibMount_FOUND

LibMount was found on the system.

LibMount_INCLUDE_DIRS

The libmount include directory.

LibMount_LIBRARIES

The libmount libraries.

LibMount_VERSION

The libmount version.

If LibMount_FOUND is TRUE, it will also define the following imported target:

LibMount::LibMount

The libmount library

Since 5.83.0

### FindLibcap
Try to find the setcap binary and cap libraries

This will define:

Libcap_FOUND

system has the cap library and setcap binary

Libcap_LIBRARIES

cap libraries to link against

SETCAP_EXECUTABLE

path of the setcap binary

In addition, the following targets are defined:

Libcap::SetCapabilities

Since 5.80.0

### FindOpenEXR
Try to find the OpenEXR libraries.

This will define the following variables:

OpenEXR_FOUND

True if OpenEXR is available

OpenEXR_LIBRARIES

Link to these to use OpenEXR

OpenEXR_INCLUDE_DIRS

Include directory for OpenEXR

OpenEXR_DEFINITIONS

Compiler flags required to link against OpenEXR

and the following imported targets:

OpenEXR::IlmImf

The OpenEXR core library

In general we recommend using the imported target, as it is easier to use. Bear in mind, however, that if the target is in the link interface of an exported library, it must be made available by the package config file.

Since pre-1.0.0.

### FindPhoneNumber
Try to find PhoneNumber.

This is a component-based find module, which makes use of the COMPONENTS and OPTIONAL_COMPONENTS arguments to find_module. The following components are available:

```
PhoneNumber  GeoCoding
```

If no components are specified, this module will act as though all components were passed to OPTIONAL_COMPONENTS.

This module will define the following variables, independently of the components searched for or found:

PhoneNumber_FOUND

True if (the requestion version of) PhoneNumber is available

For each searched-for components, PhoneNumber_<component>_FOUND will be set to TRUE if the corresponding library was found, and FALSE otherwise. If PhoneNumber_<component>_FOUND is TRUE, the imported target PhoneNumber::<component> will be defined.

Since 5.54.0.

### FindPoppler
Try to find Poppler.

This is a component-based find module, which makes use of the COMPONENTS and OPTIONAL_COMPONENTS arguments to find_module. The following components are available:

```
Core  Cpp  Qt5  Qt4  Glib
```

If no components are specified, this module will act as though all components were passed to OPTIONAL_COMPONENTS.

This module will define the following variables, independently of the components searched for or found:

Poppler_FOUND

TRUE if (the requested version of) Poppler is available

Poppler_VERSION

Found Poppler version

Poppler_TARGETS

A list of all targets imported by this module (note that there may be more than the components that were requested)

Poppler_LIBRARIES

This can be passed to target_link_libraries() instead of the imported targets

Poppler_INCLUDE_DIRS

This should be passed to target_include_directories() if the targets are not used for linking

Poppler_DEFINITIONS

This should be passed to target_compile_options() if the targets are not used for linking

For each searched-for components, Poppler_<component>_FOUND will be set to TRUE if the corresponding Poppler library was found, and FALSE otherwise. If Poppler_<component>_FOUND is TRUE, the imported target Poppler::<component> will be defined. This module will also attempt to determine Poppler_*_VERSION variables for each imported target, although Poppler_VERSION should normally be sufficient.

In general we recommend using the imported targets, as they are easier to use and provide more control. Bear in mind, however, that if any target is in the link interface of an exported library, it must be made available by the package config file.

Since 5.19

### FindPulseAudio
Try to locate the PulseAudio library. If found, this will define the following variables:

PulseAudio_FOUND

True if the system has the PulseAudio library of at least the minimum version specified by either the version parameter to find_package() or the variable PulseAudio_MINIMUM_VERSION

PulseAudio_INCLUDE_DIRS

The PulseAudio include directory

PulseAudio_LIBRARIES

The PulseAudio libraries for linking

PulseAudio_MAINLOOP_LIBRARY

The libraries needed to use PulseAudio Mainloop

PulseAudio_VERSION

The version of PulseAudio that was found

PulseAudio_INCLUDE_DIR

Deprecated, use PulseAudio_INCLUDE_DIRS

PulseAudio_LIBRARY

Deprecated, use PulseAudio_LIBRARIES

If PulseAudio_FOUND is TRUE, it will also define the following imported target:

PulseAudio::PulseAudio

The PulseAudio library

Since 5.41.0.

### FindQtWaylandScanner
Try to find qtwaylandscanner.

If the qtwaylandscanner executable is not in your PATH, you can provide an alternative name or full path location with the QtWaylandScanner_EXECUTABLE variable.

This will define the following variables:

QtWaylandScanner_FOUND

True if qtwaylandscanner is available

QtWaylandScanner_EXECUTABLE

The qtwaylandscanner executable.

If QtWaylandScanner_FOUND is TRUE, it will also define the following imported target:

Wayland::QtScanner

The qtwaylandscanner executable.

This module provides the following functions to generate C++ protocol implementations:

- ecm_add_qtwayland_client_protocol

- ecm_add_qtwayland_server_protocol

```
ecm_add_qtwayland_client_protocol(<target>

                                  PROTOCOL <xmlfile>

                                  BASENAME <basename>

                                  [PREFIX <prefix>]

                                  [PRIVATE_CODE])
ecm_add_qtwayland_client_protocol(<source_files_var>

                                  PROTOCOL <xmlfile>

                                  BASENAME <basename>

                                  [PREFIX <prefix>]

                                  [PRIVATE_CODE])
```

Generate C++ wrapper to Wayland client protocol files from <xmlfile> XML definition for the <basename> interface and append those files to <source_files_var> or <target>. Pass the <prefix> argument if the interface names don’t start with qt_ or wl_. PRIVATE_CODE instructs wayland-scanner to hide marshalling code from the compiled DSO for use in other DSOs. The default is to export this code.

WaylandScanner is required and will be searched for.

```
ecm_add_qtwayland_server_protocol(<target>

                                  PROTOCOL <xmlfile>

                                  BASENAME <basename>

                                  [PREFIX <prefix>]

                                  [PRIVATE_CODE])
ecm_add_qtwayland_server_protocol(<source_files_var>

                                  PROTOCOL <xmlfile>

                                  BASENAME <basename>

                                  [PREFIX <prefix>]

                                  [PRIVATE_CODE])
```

Generate C++ wrapper to Wayland server protocol files from <xmlfile> XML definition for the <basename> interface and append those files to <source_files_var> or <target>. Pass the <prefix> argument if the interface names don’t start with qt_ or wl_. PRIVATE_CODE instructs wayland-scanner to hide marshalling code from the compiled DSO for use in other DSOs. The default is to export this code.

WaylandScanner is required and will be searched for.

Since 1.4.0.

### FindSasl2
Try to find the SASL2 library.

This will define the following variables:

Sasl2_FOUND

System has SASL2.

Sasl2_VERSION

The version of SASL2.

Sasl2_INCLUDE_DIRS

This should be passed to target_include_directories() if the target is not used for linking.

Sasl2_LIBRARIES

The SASL2 library. This can be passed to target_link_libraries() instead of the Sasl2::Sasl2 target

If Sasl2_FOUND is TRUE, the following imported target will be available:

Sasl2::Sasl2

The SASL2 library

Since 5.41.0.

### FindSeccomp
Try to locate the libseccomp library.

This will define the following variables:

Seccomp_FOUND

True if the seccomp library is available

Seccomp_INCLUDE_DIRS

The seccomp include directories

Seccomp_LIBRARIES

The seccomp libraries for linking

If Seccomp_FOUND is TRUE, it will also define the following imported target:

Seccomp::Seccomp

The Seccomp library

Since 5.44.0.

### FindSharedMimeInfo
Try to find the shared-mime-info package.

This will define the following variables:

SharedMimeInfo_FOUND

True if system has the shared-mime-info package

UPDATE_MIME_DATABASE_EXECUTABLE

The update-mime-database executable

and the following imported targets:

SharedMimeInfo::UpdateMimeDatabase

The update-mime-database executable

The follow macro is available:

```
update_xdg_mimetypes(<path>)
```

Updates the XDG mime database at install time (unless the $DESTDIR environment variable is set, in which case it is up to package managers to perform this task).

Since pre-1.0.0.

### FindTaglib
Try to find the Taglib library.

This will define the following variables:

Taglib_FOUND

True if the system has the taglib library of at least the minimum version specified by the version parameter to find_package()

Taglib_INCLUDE_DIRS

The taglib include dirs for use with target_include_directories

Taglib_LIBRARIES

The taglib libraries for use with target_link_libraries()

Taglib_VERSION

The version of taglib that was found

If Taglib_FOUND is TRUE, it will also define the following imported target:

Taglib::Taglib

The Taglib library

Since 5.72.0

### FindUDev
Try to find the UDev library.

This will define the following variables:

UDev_FOUND

System has UDev.

UDev_INCLUDE_DIRS

The libudev include directory.

UDev_LIBRARIES

The libudev libraries.

UDev_VERSION

The libudev version.

If UDev_FOUND is TRUE, it will also define the following imported target:

UDev::UDev

The UDev library

Since 5.57.0.

### FindWayland
Try to find Wayland.

This is a component-based find module, which makes use of the COMPONENTS and OPTIONAL_COMPONENTS arguments to find_module. The following components are available:

```
Client  Server  Cursor  Egl
```

If no components are specified, this module will act as though all components were passed to OPTIONAL_COMPONENTS.

This module will define the following variables, independently of the components searched for or found:

Wayland_FOUND

TRUE if (the requested version of) Wayland is available

Wayland_VERSION

Found Wayland version

Wayland_TARGETS

A list of all targets imported by this module (note that there may be more than the components that were requested)

Wayland_LIBRARIES

This can be passed to target_link_libraries() instead of the imported targets

Wayland_INCLUDE_DIRS

This should be passed to target_include_directories() if the targets are not used for linking

Wayland_DEFINITIONS

This should be passed to target_compile_options() if the targets are not used for linking

Wayland_DATADIR

The core wayland protocols data directory Since 5.73.0

For each searched-for components, Wayland_<component>_FOUND will be set to TRUE if the corresponding Wayland library was found, and FALSE otherwise. If Wayland_<component>_FOUND is TRUE, the imported target Wayland::<component> will be defined. This module will also attempt to determine Wayland_*_VERSION variables for each imported target, although Wayland_VERSION should normally be sufficient.

In general we recommend using the imported targets, as they are easier to use and provide more control. Bear in mind, however, that if any target is in the link interface of an exported library, it must be made available by the package config file.

Since pre-1.0.0.

### FindWaylandProtocols
Try to find wayland-protocols on a Unix system.

This will define the following variables:

WaylandProtocols_FOUND

True if (the requested version of) wayland-protocols is available

WaylandProtocols_VERSION

The version of wayland-protocols

WaylandProtocols_DATADIR

The wayland protocols data directory

### FindWaylandScanner
Try to find wayland-scanner.

If the wayland-scanner executable is not in your PATH, you can provide an alternative name or full path location with the WaylandScanner_EXECUTABLE variable.

This will define the following variables:

WaylandScanner_FOUND

True if wayland-scanner is available.

WaylandScanner_EXECUTABLE

The wayland-scanner executable.

If WaylandScanner_FOUND is TRUE, it will also define the following imported target:

Wayland::Scanner

The wayland-scanner executable.

This module provides the following functions to generate C protocol implementations:

- ecm_add_wayland_client_protocol

- ecm_add_wayland_server_protocol

```
ecm_add_wayland_client_protocol(<target>

                                PROTOCOL <xmlfile>

                                BASENAME <basename>

                                [PRIVATE_CODE])
ecm_add_wayland_client_protocol(<source_files_var>

                                PROTOCOL <xmlfile>

                                BASENAME <basename>

                                [PRIVATE_CODE])
```

Generate Wayland client protocol files from <xmlfile> XML definition for the <basename> interface and append those files to <source_files_var> or <target>.

PRIVATE_CODE instructs wayland-scanner to hide marshalling code from the compiled DSO for use in other DSOs. The default is to export this code.

```
ecm_add_wayland_server_protocol(<target>

                                PROTOCOL <xmlfile>

                                BASENAME <basename>

                                [PRIVATE_CODE])
ecm_add_wayland_server_protocol(<source_files_var>

                                PROTOCOL <xmlfile>

                                BASENAME <basename>

                                [PRIVATE_CODE])
```

Generate Wayland server protocol files from <xmlfile> XML definition for the <basename> interface and append those files to <source_files_var> or <target>.

PRIVATE_CODE instructs wayland-scanner to hide marshalling code from the compiled DSO for use in other DSOs. The default is to export this code.

Since 1.4.0.

### FindX11_XCB
Try to find the X11 XCB compatibility library.

This will define the following variables:

X11_XCB_FOUND

True if (the requested version of) libX11-xcb is available

X11_XCB_VERSION

The version of libX11-xcb (this is not guaranteed to be set even when X11_XCB_FOUND is true)

X11_XCB_LIBRARIES

This can be passed to target_link_libraries() instead of the EGL::EGL target

X11_XCB_INCLUDE_DIR

This should be passed to target_include_directories() if the target is not used for linking

X11_XCB_DEFINITIONS

This should be passed to target_compile_options() if the target is not used for linking

If X11_XCB_FOUND is TRUE, it will also define the following imported target:

X11::XCB

The X11 XCB compatibility library

In general we recommend using the imported target, as it is easier to use. Bear in mind, however, that if the target is in the link interface of an exported library, it must be made available by the package config file.

Since pre-1.0.0.

### FindXCB
Try to find XCB.

This is a component-based find module, which makes use of the COMPONENTS and OPTIONAL_COMPONENTS arguments to find_module. The following components are available:

```
XCB
ATOM         AUX          COMPOSITE    CURSOR       DAMAGE
DPMS         DRI2         DRI3         EVENT        EWMH
GLX          ICCCM        IMAGE        KEYSYMS      PRESENT
RANDR        RECORD       RENDER       RENDERUTIL   RES
SCREENSAVER  SHAPE        SHM          SYNC         UTIL
XF86DRI      XFIXES       XINERAMA     XINPUT       XKB
XTEST        XV           XVMC
```

If no components are specified, this module will act as though all components were passed to OPTIONAL_COMPONENTS. Before 5.82 this excluded XINPUT. Since 5.82 all components are searched for.

This module will define the following variables, independently of the components searched for or found:

XCB_FOUND

True if (the requestion version of) xcb is available

XCB_VERSION

Found xcb version

XCB_TARGETS

A list of all targets imported by this module (note that there may be more than the components that were requested)

XCB_LIBRARIES

This can be passed to target_link_libraries() instead of the imported targets

XCB_INCLUDE_DIRS

This should be passed to target_include_directories() if the targets are not used for linking

XCB_DEFINITIONS

This should be passed to target_compile_options() if the targets are not used for linking

For each searched-for components, XCB_<component>_FOUND will be set to true if the corresponding xcb library was found, and false otherwise. If XCB_<component>_FOUND is true, the imported target XCB::<component> will be defined. This module will also attempt to determine XCB_*_VERSION variables for each imported target, although XCB_VERSION should normally be sufficient.

In general we recommend using the imported targets, as they are easier to use and provide more control. Bear in mind, however, that if any target is in the link interface of an exported library, it must be made available by the package config file.

Since pre-1.0.0.

### Findepoxy
Try to find libepoxy on a Unix system.

This will define the following variables:

epoxy_FOUND

True if (the requested version of) libepoxy is available

epoxy_VERSION

The version of libepoxy

epoxy_LIBRARIES

This should be passed to target_link_libraries() if the target is not used for linking

epoxy_INCLUDE_DIRS

This should be passed to target_include_directories() if the target is not used for linking

epoxy_DEFINITIONS

This should be passed to target_compile_options() if the target is not used for linking

epoxy_HAS_GLX

True if GLX support is available

If epoxy_FOUND is TRUE, it will also define the following imported target:

epoxy::epoxy

The epoxy library

In general we recommend using the imported target, as it is easier to use. Bear in mind, however, that if the target is in the link interface of an exported library, it must be made available by the package config file.

### Findgzip
Try to find gzip.

If the gzip executable is not in your PATH, you can provide an alternative name or full path location with the gzip_EXECUTABLE variable.

This will define the following variables:

gzip_FOUND

TRUE if gzip is available

gzip_EXECUTABLE

Path to gzip executable

If gzip_FOUND is TRUE, it will also define the following imported target:

gzip::gzip

Path to gzip executable

Since 5.85.0.

## SEE ALSO
ecm(7), ecm-modules(7), ecm-kde-modules(7)

## COPYRIGHT
KDE Developers