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).


title: euca2ools(7)

summary: eucalyptus command line client tools

text:
# euca2ools(7)

## NAME
euca2ools — eucalyptus command line client tools

## DESCRIPTION
The euca2ools suite is a set of command line tools that interact with “Amazon Web Services” (AWS), Eucalyptus, and other AWS-compatible clouds using the REST- and query-based APIs for numerous web services.

The URL for each web service can be set with a SERVICE-url region option, where SERVICE is the name of the service, in euca2ools.ini(5) configuration files and then chosen with the --region command line option or the EUCA_DEFAULT_REGION or AWS_DEFAULT_REGION environment variables. Alternatively, the URL can be set at the command line or with an environment variable that is specific to the service. Environment variables take precedence over configuration file data.

euca2ools are designed to make it as easy as possible to work with multiple AWS-compatible clouds from the command line using euca2ools.ini(5) configuration files, command line options, and shortcuts.

### List of Web Services
Name

Version

Environment variable

Commands

autoscaling

2011-01-01

AWS_AUTO_SCALING_URL

euscale-*

bootstrap

EUCA_BOOTSTRAP_URL

euca-bundle-image(1), euca-bundle-and-upload-image(1), euca-install-image(1), euimage-install-pack(1)

cloudformation

2010-05-15

AWS_CLOUDFORMATION_URL

euform-*

ec2

2015-10-01

EC2_URL

euca-*

elasticloadbalancing

2012-06-01

AWS_ELB_URL

eulb-*

iam

2010-05-08

AWS_IAM_URL

euare-*

monitoring

2010-08-01

AWS_CLOUDWATCH_URL

euwatch-*

s3

2006-03-01

S3_URL

euca-bundle-and-upload-image(1), euca-download-and-unbundle(1), euca-download-bundle(1), euca-install-image(1), euca-upload-bundle(1), euimage-install-pack(1)

sts

2011-06-15

TOKENS_URL

euare-assumerole(1)

## NOTES
The “bootstrap” service, also known as the “Empyrean” service, is specific to eucalyptus. Commands that bundle images can optionally use it to obtain the cloud's signing certificate automatically, provided the cloud runs eucalyptus 4.2 or later.

## SEE ALSO
euca2ools.ini(5)


eudev

package: eudev

title: eudev(7)

summary: Dynamic device management

text:
# eudev(7)

## NAME
udev - Dynamic device management

## DESCRIPTION
udev supplies the system software with device events, manages permissions of device nodes and may create additional symlinks in the /dev directory, or renames network interfaces. The kernel usually just assigns unpredictable device names based on the order of discovery. Meaningful symlinks or network device names provide a way to reliably identify devices based on their properties or current configuration.

The udev daemon, udevd(8), receives device uevents directly from the kernel whenever a device is added or removed from the system, or it changes its state. When udev receives a device event, it matches its configured set of rules against various device attributes to identify the device. Rules that match may provide additional device information to be stored in the udev database or to be used to create meaningful symlink names.

All device information udev processes is stored in the udev database and sent out to possible event subscribers. Access to all stored data and the event sources is provided by the library libudev.

## RULES FILES
The udev rules are read from the files located in the system rules directory /lib/udev/rules.d, the volatile runtime directory /run/udev/rules.d and the local administration directory /etc/udev/rules.d. All rules files are collectively sorted and processed in lexical order, regardless of the directories in which they live. However, files with identical filenames replace each other. Files in /etc have the highest priority, files in /run take precedence over files with the same name in /lib. This can be used to override a system-supplied rules file with a local file if needed; a symlink in /etc with the same name as a rules file in /lib, pointing to /dev/null, disables the rules file entirely. Rule files must have the extension .rules; other extensions are ignored.

Every line in the rules file contains at least one key-value pair. Except for empty lines or lines beginning with #, which are ignored. There are two kinds of keys: match and assignment. If all match keys match against their values, the rule gets applied and the assignment keys get the specified values assigned.

A matching rule may rename a network interface, add symlinks pointing to the device node, or run a specified program as part of the event handling.

A rule consists of a comma-separated list of one or more key-value pairs. Each key has a distinct operation, depending on the used operator. Valid operators are:

==

Compare for equality.

!=

Compare for inequality.

=

Assign a value to a key. Keys that represent a list are reset and only this single value is assigned.

+=

Add the value to a key that holds a list of entries.

-=

Remove the value from a key that holds a list of entries.

:=

Assign a value to a key finally; disallow any later changes.

The following key names can be used to match against device properties. Some of the keys also match against properties of the parent devices in sysfs, not only the device that has generated the event. If multiple keys that match a parent device are specified in a single rule, all these keys must match at one and the same parent device.

ACTION

Match the name of the event action.

DEVPATH

Match the devpath of the event device.

KERNEL

Match the name of the event device.

NAME

Match the name of a network interface. It can be used once the NAME key has been set in one of the preceding rules.

SYMLINK

Match the name of a symlink targeting the node. It can be used once a SYMLINK key has been set in one of the preceding rules. There may be multiple symlinks; only one needs to match.

SUBSYSTEM

Match the subsystem of the event device.

DRIVER

Match the driver name of the event device. Only set this key for devices which are bound to a driver at the time the event is generated.

ATTR{filename}, SYSCTL{kernel parameter}

Match sysfs attribute values of the event device. Trailing whitespace in the attribute values is ignored unless the specified match value itself contains trailing whitespace. Match a kernel parameter value.

KERNELS

Search the devpath upwards for a matching device name.

SUBSYSTEMS

Search the devpath upwards for a matching device subsystem name.

DRIVERS

Search the devpath upwards for a matching device driver name.

ATTRS{filename}

Search the devpath upwards for a device with matching sysfs attribute values. If multiple ATTRS matches are specified, all of them must match on the same device. Trailing whitespace in the attribute values is ignored unless the specified match value itself contains trailing whitespace.

TAGS

Search the devpath upwards for a device with matching tag.

ENV{key}

Match against a device property value.

TAG

Match against a device tag.

TEST{octal mode mask}

Test the existence of a file. An octal mode mask can be specified if needed.

PROGRAM

Execute a program to determine whether there is a match; the key is true if the program returns successfully. The device properties are made available to the executed program in the environment. The program's standard output is available in the RESULT key. This can only be used for very short-running foreground tasks. For details, see RUN.

RESULT

Match the returned string of the last PROGRAM call. This key can be used in the same or in any later rule after a PROGRAM call.

Most of the fields support shell glob pattern matching and alternate patterns. The following special characters are supported:

*

Matches zero or more characters.

?

Matches any single character.

[]

Matches any single character specified within the brackets. For example, the pattern string tty[SR] would match either ttyS or ttyR. Ranges are also supported via the - character. For example, to match on the range of all digits, the pattern [0-9] could be used. If the first character following the [ is a !, any characters not enclosed are matched.

|

Separates alternative patterns. For example, the pattern string abc|x* would match either abc or x*.

The following keys can get values assigned:

NAME

The name to use for a network interface. The name of a device node cannot be changed by udev, only additional symlinks can be created.

SYMLINK

The name of a symlink targeting the node. Every matching rule adds this value to the list of symlinks to be created. The set of characters to name a symlink is limited. Allowed characters are 0-9A-Za-z#+-.:=@_/, valid UTF-8 character sequences, and \x00 hex encoding. All other characters are replaced by a _ character.

Multiple symlinks may be specified by separating the names by the space character. In case multiple devices claim the same name, the link always points to the device with the highest link_priority. If the current device goes away, the links are re-evaluated and the device with the next highest link_priority becomes the owner of the link. If no link_priority is specified, the order of the devices (and which one of them owns the link) is undefined.

Symlink names must never conflict with the kernel's default device node names, as that would result in unpredictable behavior.

OWNER, GROUP, MODE

The permissions for the device node. Every specified value overrides the compiled-in default value.

SECLABEL{module}

Applies the specified Linux Security Module label to the device node.

ATTR{key}

The value that should be written to a sysfs attribute of the event device.

SYSCTL{kernel parameter}

The value that should be written to kernel parameter.

ENV{key}

Set a device property value. Property names with a leading . are neither stored in the database nor exported to events or external tools (run by, for example, the PROGRAM match key).

TAG

Attach a tag to a device. This is used to filter events for users of libudev's monitor functionality, or to enumerate a group of tagged devices. The implementation can only work efficiently if only a few tags are attached to a device. It is only meant to be used in contexts with specific device filter requirements, and not as a general-purpose flag. Excessive use might result in inefficient event handling.

RUN{type}

Add a program to the list of programs to be executed after processing all the rules for a specific event, depending on type: program

Execute an external program specified as the assigned value. If no absolute path is given, the program is expected to live in /lib/udev, otherwise, the absolute path must be specified. This is the default if no type is specified.

builtin

As program, but use one of the built-in programs rather than an external one.

The program name and following arguments are separated by spaces. Single quotes can be used to specify arguments with spaces.

This can only be used for very short-running foreground tasks. Running an event process for a long period of time may block all further events for this or a dependent device.

Starting daemons or other long-running processes is not appropriate for udev; the forked processes, detached or not, will be unconditionally killed after the event handling has finished.

LABEL

A named label to which a GOTO may jump.

GOTO

Jumps to the next LABEL with a matching name.

IMPORT{type}

Import a set of variables as device properties, depending on type: program

Execute an external program specified as the assigned value and import its output, which must be in environment key format. Path specification, command/argument separation, and quoting work like in RUN.

builtin

Similar to program, but use one of the built-in programs rather than an external one.

file

Import a text file specified as the assigned value, the content of which must be in environment key format.

db

Import a single property specified as the assigned value from the current device database. This works only if the database is already populated by an earlier event.

cmdline

Import a single property from the kernel command line. For simple flags the value of the property is set to 1.

parent

Import the stored keys from the parent device by reading the database entry of the parent device. The value assigned to IMPORT{parent} is used as a filter of key names to import (with the same shell glob pattern matching used for comparisons).

This can only be used for very short-running foreground tasks. For details see RUN.

WAIT_FOR

Wait for a file to become available or until a timeout of 10 seconds expires. The path is relative to the sysfs device; if no path is specified, this waits for an attribute to appear.

OPTIONS

Rule and device options: link_priority=value

Specify the priority of the created symlinks. Devices with higher priorities overwrite existing symlinks of other devices. The default is 0.

string_escape=none|replace

Usually control and other possibly unsafe characters are replaced in strings used for device naming. The mode of replacement can be specified with this option.

static_node=

Apply the permissions specified in this rule to the static device node with the specified name. Static device node creation can be requested by kernel modules. These nodes might not have a corresponding kernel device at the time udevd is started; they can trigger automatic kernel module loading.

watch

Watch the device node with inotify; when the node is closed after being opened for writing, a change uevent is synthesized.

nowatch

Disable the watching of a device node with inotify.

The NAME, SYMLINK, PROGRAM, OWNER, GROUP, MODE, and RUN fields support simple string substitutions. The RUN substitutions are performed after all rules have been processed, right before the program is executed, allowing for the use of device properties set by earlier matching rules. For all other fields, substitutions are performed while the individual rule is being processed. The available substitutions are:

$kernel, %k

The kernel name for this device.

$number, %n

The kernel number for this device. For example, sda3 has kernel number 3.

$devpath, %p

The devpath of the device.

$id, %b

The name of the device matched while searching the devpath upwards for SUBSYSTEMS, KERNELS, DRIVERS, and ATTRS.

$driver

The driver name of the device matched while searching the devpath upwards for SUBSYSTEMS, KERNELS, DRIVERS, and ATTRS.

$attr{file}, %s{file}

The value of a sysfs attribute found at the device where all keys of the rule have matched. If the matching device does not have such an attribute, and a previous KERNELS, SUBSYSTEMS, DRIVERS, or ATTRS test selected a parent device, then the attribute from that parent device is used. If the attribute is a symlink, the last element of the symlink target is returned as the value.

$env{key}, %E{key}

A device property value.

$major, %M

The kernel major number for the device.

$minor, %m

The kernel minor number for the device.

$result, %c

The string returned by the external program requested with PROGRAM. A single part of the string, separated by a space character, may be selected by specifying the part number as an attribute: %c{N}. If the number is followed by the + character, this part plus all remaining parts of the result string are substituted: %c{N+}.

$parent, %P

The node name of the parent device.

$name

The current name of the device. If not changed by a rule, it is the name of the kernel device.

$links

A space-separated list of the current symlinks. The value is only set during a remove event or if an earlier rule assigned a value.

$sys, %S

The sysfs mount point.

$devnode, %N

The name of the device node.

%%

The % character itself.

$$

The $ character itself.

## HARDWARE DATABASE FILES
The hwdb files are read from the files located in the system hwdb directory /usr/lib/udev/hwdb.d, the volatile runtime directory /run/udev/hwdb.d and the local administration directory /etc/udev/hwdb.d. All hwdb files are collectively sorted and processed in lexical order, regardless of the directories in which they live. However, files with identical filenames replace each other. Files in /etc have the highest priority, files in /run take precedence over files with the same name in /usr/lib. This can be used to override a system-supplied hwdb file with a local file if needed; a symlink in /etc with the same name as a hwdb file in /usr/lib, pointing to /dev/null, disables the hwdb file entirely. hwdb files must have the extension .hwdb; other extensions are ignored.

The hwdb file contains data records consisting of matches and associated key-value pairs. Every record in the hwdb starts with one or more match string, specifying a shell glob to compare the database lookup string against. Multiple match lines are specified in additional consecutive lines. Every match line is compared indivdually, they are combined by OR. Every match line must start at the first character of the line.

The match lines are followed by one or more key-value pair lines, which are recognized by a leading space character. The key name and value are separated by =. An empty line signifies the end of a record. Lines beginning with # are ignored.

The content of all hwdb files is read by udevadm(8) and compiled to a binary database located at /etc/udev/hwdb.bin, or alternatively /usr/lib/udev/hwdb.bin if you want ship the compiled database in an immutable image. During runtime only the binary database is used.

## SEE ALSO
udevd(8), udevadm(8)


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.

### 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

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 on Linux systems.

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 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>])
ecm_add_qtwayland_client_protocol(<source_files_var>

                                  PROTOCOL <xmlfile>

                                  BASENAME <basename>

                                  [PREFIX <prefix>])
```

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_.

WaylandScanner is required and will be searched for.

```
ecm_add_qtwayland_server_protocol(<target>

                                  PROTOCOL <xmlfile>

                                  BASENAME <basename>

                                  [PREFIX <prefix>])
ecm_add_qtwayland_server_protocol(<source_files_var>

                                  PROTOCOL <xmlfile>

                                  BASENAME <basename>

                                  [PREFIX <prefix>])
```

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_.

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>)
ecm_add_wayland_client_protocol(<source_files_var>

                                PROTOCOL <xmlfile>

                                BASENAME <basename>)
```

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

```
ecm_add_wayland_server_protocol(<target>

                                PROTOCOL <xmlfile>

                                BASENAME <basename>)
ecm_add_wayland_server_protocol(<source_files_var>

                                PROTOCOL <xmlfile>

                                BASENAME <basename>)
```

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

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