ibus-emoji

package: ibus

title: ibus-emoji(7)

summary: Call the IBus emoji utility by

text:
# ibus-emoji(7)

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

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

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

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

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

## SETTINGS
ANNOTATION LANGUAGE

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

FONT

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

## KEYBOARD OPERATIONS
Control-Shift-e

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

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

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

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

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

Enter

Commit the selected emoji.

Escape

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

Space

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

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

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

Head, End, Control-h or Control-e

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

Control-u

Erase the typed annotation.

Control-x or Control-v or Control-c

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

Control-Shift-c

Copy the selected emoji to the clipboard.

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


icmconf

package: icmake

title: icmconf(7)

summary: Configuration file for the icmbuild(1)

text:
# icmconf(7)

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

## DESCRIPTION
The icmconf configuration file is used to specify and fine-tune the program maintenance performed by the icmbuild(1) program and script. It can be used to activate and specify various directives that determine how the program or library maintenance is performed.

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

The icmbuild(1) script ignores empty lines and lines whose first non-blank characters are two consecutive forward slashes (//). Long lines can be split over multiple lines by writing a final backslash character at lines continuing at the next line (refer to the icmake(1) man-page for further details).

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

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

Likewise, if PRECOMP was defined, then a similar action is performed for the precompiled headers: if a local header file that’s (directly or indirectly) included by a class’s internal header file has changed, then that class’s precompiled header as well as all precompiled headers of dependent classes are recompiled.

The icmbuild(1) script itself does not inspect these dependencies, but calls /usr/lib/icmake/icm-dep to perform the requird tests. The program icm-dep’s short usage summary is written to the standard output stream when calling icmake -d (or directly: /usr/lib/icmake/icm-dep).

## DEFINES IN ICMCONF
All of the following #defines are required except those that are shown as commented #defines (e.g., //#define REFRESH).

o

//#define ADD_LIBRARIES ""

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

```
    #define ADD_LIBRARIES  "bobcat"

```

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

o

//#define ADD_LIBRARY_PATHS ""

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

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

o

//#define CLS

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

o

\#define CXX "g++"

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

o

\#define CXXFLAGS "--std=c++2a -Wall -O2"

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

o

//#define DEFCOM "..."

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

```
    #define DEFCOM  "program"

```

in which case icmbuild does program maintenance, or as

```
    #define DEFCOM  "library"

```

in which case icmbuild does library maintenance.;

o

//#define ICM_DEP "-V go"

the existence and implied existence of USE_ALL files (see the description of the USE_ALL directive), as well as the correct ages of precompiled headers can be checked by icmake’s support program icm_dep. By default icm_dep is called with the shown default arguments. If icm_dep should not be called define ICM_DEP as an empty string (""). Icmake(1)’s man-page contains a separate section about the icm_dep support program;

o

//#define IH ".ih"

the extension used for internal header files. See #define PRECOMP below. If PRECOMP is specified ttIH) must also be specified;

o

//#define LDFLAGS ""

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

o

//#define LIBRARY "modules"

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

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

o

//#define MAIN "main.cc"

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

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

o

//#define NO_PRECOMP_WARNING"

when PRECOMP is defined (see below) a warning is issued when a class-directory does not contain a IH file. Such warnings are suppressed by defining NO_PRECOMP_WARNING. This option is only considered when PRECOMP has been defined;

o

\#define OBJ_EXT ".o"

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

o

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

define this directive to construct precompiled headers (in which case the IH) directive must also have been specified. Dependencies between (precompiled) headers are automatically considered.

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

o

//#define REFRESH

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

o

//#define SHARED

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

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

o

//#define SHAREDREQ ""

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

o

\#define SOURCES "*.cc"

the pattern to locate sources in directories;

o

\#define TMP_DIR "tmp"

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

o

//#define USE_ALL "a"

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

o

//#define USE_ECHO ON

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

o

//#define USE_VERSION

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

```
    VERSION=9.03.00

    YEARS=1992-2020

```

)

## PARSER MAINTENANCE
The following directives are available in cases where a program uses a parser generator creating a parser class from a grammar specification. By default they’re all commented out.

o

//#define PARSER_DIR ""

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

o

//#define PARSFILES ""

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

o

//#define PARSFLAGS "-V"

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

o

//#define PARSGEN "bisonc++"

the name of the program generating the parser;

o

//#define PARSOUT "parse.cc"

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

o

//#define PARSSPEC "grammar"

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

## SCANNER MAINTENANCE
The following directives are available in cases where a program uses a scanner generator creating a lexical scanner class from a set of regular expressions. By default they’re all commented out.

o

\#define SCANNER_DIR ""

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

o

\#define SCANFILES ""

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

o

\#define SCANFLAGS ""

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

o

\#define SCANGEN "flexc++"

the name of the program generating the lexical scanner;

o

\#define SCANOUT "lex.cc"

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

o

\#define SCANSPEC "lexer"

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

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

o

/usr/share/icmake/CLASSES

: example of an icmconf CLASSES file;

o

/usr/share/icmake/icmconf

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

o

/etc/icmake

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

o

$HOME/.icmake

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

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

```

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

## BUGS
icmbuild(1) ends, displaying a fatal error message, if the current working directory does not contain a file icmconf.

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

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


icmstart.rc

title: icmstart.rc(7)

summary: The icmstart(1) resource file

text:
# icmstart.rc(7)

## NAME
icmstart.rc - The icmstart(1) resource file

## DESCRIPTION
The icmstart.rc file specifies files that are installed by icmstart(1).

A default icmstart.rc is found in /etc/icmake/icmstart.rc, but if $HOME/.icmake/icmstart.rc exists then the latter file is used by icmstart(1). $HOME/.icmake/icmstart.rc in turn is overruled by specifying a -c option when invoking icmstart(1).

The default resource file contains the following specifications, preparing for the construction of a C++ program using icmbuild(1):

```
    CLASSES

    icmconf

    P main.cc

    P main.ih

    P usage.cc

    P version.cc

    P ? scanner

    P ? parser

```

The icmstart.rc file may contain: o

empty lines, which are ignored;

o

lines beginning with a hash-character (#), also ignored;

o

an optional installation mode followed by a source-destination specification.

## INSTALLATION MODE
An installation mode consists of a combination of:

o

either a P (don’t install with icmstart xxx library) or an L (don’t install with icmstart xxx program);

o

a D, indicating that the source must also be installed by default, i.e., if neither `program’ or `library’ was specified as second argument;

o

a b, indicating that the file must not be installed if the -b (basic installation) option was specified when calling icmstart;

o

Following the optional P, L, D, or b character a space delimited optional ? may be specified. If specified the installation of the file or directory must be confirmed by the user.

## SOURCE-DESTINATION SPECIFICATIONS
The following source-destination specifications can be used in an icmstart.rc file (using skeletons below to refer to icmstart’s skeleton files directory):

o

source

a file named source must exist in skeletons. It is installed in the destination directory `dest’ that’s specified when calling icmstart(1). Example:

```
    CLASSES

```

skeletons/CLASSES is installed as dest/CLASSES;

o

pathspec

if `pathspec’ does not begin with a slash it must exist in skeletons. It is installed as `pathspec’ in the destination directory specified when calling icmstart(1). Example:

```
    dir/file

```

skeletons/file is installed as dest/dir/file;

o

/pathspec or ~/pathspec

the ~-character is expanded to the user’s home directory. The pathspec’s final element is installed in the destination directory specified when calling icmstart(1). Example:

```
    ~/.icmake/file

```

$HOME/.icmake/file is installed as dest/file

When the above source specifications are followed by a destination specification destspec (a file or non-absolute directory specification) then the source specification is installed as dest/destspec) below the destination directory specified when calling icmstart(1). Examples:

```
    CLASSES CLASSES             # skeletons/CLASSES is installed as

                                #   dest/CLASSES

    dir/file dir/file           # skeletons/dir/file is installed as

                                #   dest/dir/file

    ~/.icmake/file .icmake/file # $HOME/.icmake/file is installed as

                                #   dest/.icmake/file

```

Icmstart converts destination specifications to absolute paths. If these absolute paths do not begin with dest’s absolute path then an error message is displayed and icmstart ends.

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

o

/usr/share/icmake/icmconf: example of an icmbuild configuration file;

o

/usr/share/icmake/CLASSES: example of an icmbuild CLASSES file;

o

/usr/share/icmake/icmstart.rc: default skeleton resource file.

## SEE ALSO
icmake(1), icmbuild(1), icmconf(7), icmstart(1)

## BUGS
None reported

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

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


tc-hfsc

title: tc-hfsc(7)

summary: Hierarchical Fair Service Curve

text:
# tc-hfsc(7)

## NAME
tc-hfcs - Hierarchical Fair Service Curve

## HISTORY & INTRODUCTION
HFSC (Hierarchical Fair Service Curve) is a network packet scheduling algorithm that was first presented at SIGCOMM'97. Developed as a part of ALTQ (ALTernative Queuing) on NetBSD, found its way quickly to other BSD systems, and then a few years ago became part of the linux kernel. Still, it's not the most popular scheduling algorithm - especially if compared to HTB - and it's not well documented for the enduser. This introduction aims to explain how HFSC works without using too much math (although some math it will be inevitable).

In short HFSC aims to:

1)

guarantee precise bandwidth and delay allocation for all leaf classes (realtime criterion)

2)

allocate excess bandwidth fairly as specified by class hierarchy (linkshare & upperlimit criterion)

3)

minimize any discrepancy between the service curve and the actual amount of service provided during linksharing

The main "selling" point of HFSC is feature (1), which is achieved by using nonlinear service curves (more about what it actually is later). This is particularly useful in VoIP or games, where not only a guarantee of consistent bandwidth is important, but also limiting the initial delay of a data stream. Note that it matters only for leaf classes (where the actual queues are) - thus class hierarchy is ignored in the realtime case.

Feature (2) is well, obvious - any algorithm featuring class hierarchy (such as HTB or CBQ) strives to achieve that. HFSC does that well, although you might end with unusual situations, if you define service curves carelessly - see section CORNER CASES for examples.

Feature (3) is mentioned due to the nature of the problem. There may be situations where it's either not possible to guarantee service of all curves at the same time, and/or it's impossible to do so fairly. Both will be explained later. Note that this is mainly related to interior (aka aggregate) classes, as the leafs are already handled by (1). Still, it's perfectly possible to create a leaf class without realtime service, and in such a case the caveats will naturally extend to leaf classes as well.

## ABBREVIATIONS
For the remaining part of the document, we'll use following shortcuts:

```
RT - realtime
LS - linkshare
UL - upperlimit
SC - service curve
```

```

```

## BASICS OF HFSC
To understand how HFSC works, we must first introduce a service curve. Overall, it's a nondecreasing function of some time unit, returning the amount of service (an allowed or allocated amount of bandwidth) at some specific point in time. The purpose of it should be subconsciously obvious: if a class was allowed to transfer not less than the amount specified by its service curve, then the service curve is not violated.

Still, we need more elaborate criterion than just the above (although in the most generic case it can be reduced to it). The criterion has to take two things into account:

- idling periods

- the ability to "look back", so if during current active period the service curve is violated, maybe it isn't if we count excess bandwidth received during earlier active period(s)

Let's define the criterion as follows:

(1)

```
For each t1, there must exist t0 in set B, so S(t1-t0) <= w(t0,t1)
```

Here 'w' denotes the amount of service received during some time period between t0 and t1. B is a set of all times, where a session becomes active after idling period (further denoted as 'becoming backlogged'). For a clearer picture, imagine two situations:

a)

our session was active during two periods, with a small time gap between them

b)

as in (a), but with a larger gap

Consider (a): if the service received during both periods meets (1), then all is well. But what if it doesn't do so during the 2nd period? If the amount of service received during the 1st period is larger than the service curve, then it might compensate for smaller service during the 2nd period and the gap - if the gap is small enough.

If the gap is larger (b) - then it's less likely to happen (unless the excess bandwidth allocated during the 1st part was really large). Still, the larger the gap - the less interesting is what happened in the past (e.g. 10 minutes ago) - what matters is the current traffic that just started.

From HFSC's perspective, more interesting is answering the following question: when should we start transferring packets, so a service curve of a class is not violated. Or rephrasing it: How much X() amount of service should a session receive by time t, so the service curve is not violated. Function X() defined as below is the basic building block of HFSC, used in: eligible, deadline, virtual-time and fit-time curves. Of course, X() is based on equation (1) and is defined recursively:

- At the 1st backlogged period beginning function X is initialized to generic service curve assigned to a class

- At any subsequent backlogged period, X() is:

```
min(X() from previous period ; w(t0)+S(t-t0) for t>=t0),
```

... where t0 denotes the beginning of the current backlogged period.

HFSC uses either linear, or two-piece linear service curves. In case of linear or two-piece linear convex functions (first slope < second slope), min() in X's definition reduces to the 2nd argument. But in case of two-piece concave functions, the 1st argument might quickly become lesser for some t>=t0. Note, that for some backlogged period, X() is defined only from that period's beginning. We also define X^(-1)(w) as smallest t>=t0, for which X(t) = w. We have to define it this way, as X() is usually not an injection.

The above generic X() can be one of the following:

E()

In realtime criterion, selects packets eligible for sending. If none are eligible, HFSC will use linkshare criterion. Eligible time 'et' is calculated with reference to packets' heads ( et = E^(-1)(w) ). It's based on RT service curve, but in case of a convex curve, uses its 2nd slope only.

D()

In realtime criterion, selects the most suitable packet from the ones chosen by E(). Deadline time 'dt' corresponds to packets' tails (dt = D^(-1)(w+l), where 'l' is packet's length). Based on RT service curve.

V()

In linkshare criterion, arbitrates which packet to send next. Note that V() is function of a virtual time - see LINKSHARE CRITERION section for details. Virtual time 'vt' corresponds to packets' heads (vt = V^(-1)(w)). Based on LS service curve.

F()

An extension to linkshare criterion, used to limit at which speed linkshare criterion is allowed to dequeue. Fit-time 'ft' corresponds to packets' heads as well (ft = F^(-1)(w)). Based on UL service curve.

Be sure to make clean distinction between session's RT, LS and UL service curves and the above "utility" functions.

## REALTIME CRITERION
RT criterion ignores class hierarchy and guarantees precise bandwidth and delay allocation. We say that a packet is eligible for sending, when the current real time is later than the eligible time of the packet. From all eligible packets, the one most suited for sending is the one with the shortest deadline time. This sounds simple, but consider the following example:

Interface 10Mbit, two classes, both with two-piece linear service curves:

- 1st class - 2Mbit for 100ms, then 7Mbit (convex - 1st slope < 2nd slope)

- 2nd class - 7Mbit for 100ms, then 2Mbit (concave - 1st slope > 2nd slope)

Assume for a moment, that we only use D() for both finding eligible packets, and choosing the most fitting one, thus eligible time would be computed as D^(-1)(w) and deadline time would be computed as D^(-1)(w+l). If the 2nd class starts sending packets 1 second after the 1st class, it's of course impossible to guarantee 14Mbit, as the interface capability is only 10Mbit. The only workaround in this scenario is to allow the 1st class to send the packets earlier that would normally be allowed. That's where separate E() comes to help. Putting all the math aside (see HFSC paper for details), E() for RT concave service curve is just like D(), but for the RT convex service curve - it's constructed using only RT service curve's 2nd slope (in our example

7Mbit).

The effect of such E() - packets will be sent earlier, and at the same time D() will be updated - so the current deadline time calculated from it will be later. Thus, when the 2nd class starts sending packets later, both the 1st and the 2nd class will be eligible, but the 2nd session's deadline time will be smaller and its packets will be sent first. When the 1st class becomes idle at some later point, the 2nd class will be able to "buffer" up again for later active period of the 1st class.

A short remark - in a situation, where the total amount of bandwidth available on the interface is larger than the allocated total realtime parts (imagine a 10 Mbit interface, but 1Mbit/2Mbit and 2Mbit/1Mbit classes), the sole speed of the interface could suffice to guarantee the times.

Important part of RT criterion is that apart from updating its D() and E(), also V() used by LS criterion is updated. Generally the RT criterion is secondary to LS one, and used only if there's a risk of violating precise realtime requirements. Still, the "participation" in bandwidth distributed by LS criterion is there, so V() has to be updated along the way. LS criterion can than properly compensate for non-ideal fair sharing situation, caused by RT scheduling. If you use UL service curve its F() will be updated as well (UL service curve is an extension to LS one - see UPPERLIMIT CRITERION section).

Anyway - careless specification of LS and RT service curves can lead to potentially undesired situations (see CORNER CASES for examples). This wasn't the case in HFSC paper where LS and RT service curves couldn't be specified separately.

## LINKSHARING CRITERION
LS criterion's task is to distribute bandwidth according to specified class hierarchy. Contrary to RT criterion, there're no comparisons between current real time and virtual time - the decision is based solely on direct comparison of virtual times of all active subclasses - the one with the smallest vt wins and gets scheduled. One immediate conclusion from this fact is that absolute values don't matter - only ratios between them (so for example, two children classes with simple linear 1Mbit service curves will get the same treatment from LS criterion's perspective, as if they were 5Mbit). The other conclusion is, that in perfectly fluid system with linear curves, all virtual times across whole class hierarchy would be equal.

Why is VC defined in term of virtual time (and what is it)?

Imagine an example: class A with two children - A1 and A2, both with let's say 10Mbit SCs. If A2 is idle, A1 receives all the bandwidth of A (and update its V() in the process). When A2 becomes active, A1's virtual time is already far later than A2's one. Considering the type of decision made by LS criterion, A1 would become idle for a long time. We can workaround this situation by adjusting virtual time of the class becoming active - we do that by getting such time "up to date". HFSC uses a mean of the smallest and the biggest virtual time of currently active children fit for sending. As it's not real time anymore (excluding trivial case of situation where all classes become active at the same time, and never become idle), it's called virtual time.

Such approach has its price though. The problem is analogous to what was presented in previous section and is caused by non-linearity of service curves:

1)

either it's impossible to guarantee service curves and satisfy fairness during certain time periods:

Recall the example from RT section, slightly modified (with 3Mbit slopes instead of 2Mbit ones):

- 1st class - 3Mbit for 100ms, then 7Mbit (convex - 1st slope < 2nd slope)

- 2nd class - 7Mbit for 100ms, then 3Mbit (concave - 1st slope > 2nd slope)

They sum up nicely to 10Mbit - the interface's capacity. But if we wanted to only use LS for guarantees and fairness - it simply won't work. In LS context, only V() is used for making decision which class to schedule. If the 2nd class becomes active when the 1st one is in its second slope, the fairness will be preserved - ratio will be 1:1 (7Mbit:7Mbit), but LS itself is of course unable to guarantee the absolute values themselves - as it would have to go beyond of what the interface is capable of.

2)

and/or it's impossible to guarantee service curves of all classes at the same time [fairly or not]:

This is similar to the above case, but a bit more subtle. We will consider two subtrees, arbitrated by their common (root here) parent:

```
R (root) - 10Mbit
A  - 7Mbit, then 3Mbit
A1 - 5Mbit, then 2Mbit
A2 - 2Mbit, then 1Mbit
B  - 3Mbit, then 7Mbit
```

R arbitrates between left subtree (A) and right (B). Assume that A2 and B are constantly backlogged, and at some later point A1 becomes backlogged (when all other classes are in their 2nd linear part).

What happens now? B (choice made by R) will always get 7 Mbit as R is only (obviously) concerned with the ratio between its direct children. Thus A subtree gets 3Mbit, but its children would want (at the point when A1 became backlogged) 5Mbit + 1Mbit. That's of course impossible, as they can only get 3Mbit due to interface limitation.

In the left subtree - we have the same situation as previously (fair split between A1 and A2, but violated guarantees), but in the whole tree - there's no fairness (B got 7Mbit, but A1 and A2 have to fit together in 3Mbit) and there's no guarantees for all classes (only B got what it wanted). Even if we violated fairness in the A subtree and set A2's service curve to 0, A1 would still not get the required bandwidth.

## UPPERLIMIT CRITERION
UL criterion is an extensions to LS one, that permits sending packets only if current real time is later than fit-time ('ft'). So the modified LS criterion becomes: choose the smallest virtual time from all active children, such that fit-time < current real time also holds. Fit-time is calculated from F(), which is based on UL service curve. As you can see, its role is kinda similar to E() used in RT criterion. Also, for obvious reasons - you can't specify UL service curve without LS one.

The main purpose of the UL service curve is to limit HFSC to bandwidth available on the upstream router (think adsl home modem/router, and linux server as NAT/firewall/etc. with 100Mbit+ connection to mentioned modem/router). Typically, it's used to create a single class directly under root, setting a linear UL service curve to available bandwidth - and then creating your class structure from that class downwards. Of course, you're free to add a UL service curve (linear or not) to any class with LS criterion.

An important part about the UL service curve is that whenever at some point in time a class doesn't qualify for linksharing due to its fit-time, the next time it does qualify it will update its virtual time to the smallest virtual time of all active children fit for linksharing. This way, one of the main things the LS criterion tries to achieve - equality of all virtual times across whole hierarchy - is preserved (in perfectly fluid system with only linear curves, all virtual times would be equal).

Without that, 'vt' would lag behind other virtual times, and could cause problems. Consider an interface with a capacity of 10Mbit, and the following leaf classes (just in case you're skipping this text quickly - this example shows behavior that doesn't happen):

```
A - ls 5.0Mbit
B - ls 2.5Mbit
C - ls 2.5Mbit, ul 2.5Mbit
```

If B was idle, while A and C were constantly backlogged, A and C would normally (as far as LS criterion is concerned) divide bandwidth in 2:1 ratio. But due to UL service curve in place, C would get at most 2.5Mbit, and A would get the remaining 7.5Mbit. The longer the backlogged period, the more the virtual times of A and C would drift apart. If B became backlogged at some later point in time, its virtual time would be set to (A's vt + C's vt)/2, thus blocking A from sending any traffic until B's virtual time catches up with A.

## SEPARATE LS / RT SCs
Another difference from the original HFSC paper is that RT and LS SCs can be specified separately. Moreover, leaf classes are allowed to have only either RT SC or LS SC. For interior classes, only LS SCs make sense: any RT SC will be ignored.

## CORNER CASES
Separate service curves for LS and RT criteria can lead to certain traps that come from "fighting" between ideal linksharing and enforced realtime guarantees. Those situations didn't exist in original HFSC paper, where specifying separate LS / RT service curves was not discussed.

Consider an interface with a 10Mbit capacity, with the following leaf classes:

```
A - ls 5.0Mbit, rt 8Mbit
B - ls 2.5Mbit
C - ls 2.5Mbit
```

Imagine A and C are constantly backlogged. As B is idle, A and C would divide bandwidth in 2:1 ratio, considering LS service curve (so in theory - 6.66 and 3.33). Alas RT criterion takes priority, so A will get 8Mbit and LS will be able to compensate class C for only 2 Mbit - this will cause discrepancy between virtual times of A and C.

Assume this situation lasts for a long time with no idle periods, and suddenly B becomes active. B's virtual time will be updated to (A's vt + C's vt)/2, effectively landing in the middle between A's and C's virtual time. The effect - B, having no RT guarantees, will be punished and will not be allowed to transfer until C's virtual time catches up.

If the interface had a higher capacity, for example 100Mbit, this example would behave perfectly fine though.

Let's look a bit closer at the above example - it "cleverly" invalidates one of the basic things LS criterion tries to achieve - equality of all virtual times across class hierarchy. Leaf classes without RT service curves are literally left to their own fate (governed by messed up virtual times).

Also, it doesn't make much sense. Class A will always be guaranteed up to 8Mbit, and this is more than any absolute bandwidth that could happen from its LS criterion (excluding trivial case of only A being active). If the bandwidth taken by A is smaller than absolute value from LS criterion, the unused part will be automatically assigned to other active classes (as A has idling periods in such case). The only "advantage" is, that even in case of low bandwidth on average, bursts would be handled at the speed defined by RT criterion. Still, if extra speed is needed (e.g. due to latency), non linear service curves should be used in such case.

In the other words: the LS criterion is meaningless in the above example.

You can quickly "workaround" it by making sure each leaf class has RT service curve assigned (thus guaranteeing all of them will get some bandwidth), but it doesn't make it any more valid.

Keep in mind - if you use nonlinear curves and irregularities explained above happen only in the first segment, then there's little wrong with "overusing" RT curve a bit:

```
A - ls 5.0Mbit, rt 9Mbit/30ms, then 1Mbit
B - ls 2.5Mbit
C - ls 2.5Mbit
```

Here, the vt of A will "spike" in the initial period, but then A will never get more than 1Mbit until B & C catch up. Then everything will be back to normal.

## LINUX AND TIMER RESOLUTION
In certain situations, the scheduler can throttle itself and setup so called watchdog to wakeup dequeue function at some time later. In case of HFSC it happens when for example no packet is eligible for scheduling, and UL service curve is used to limit the speed at which LS criterion is allowed to dequeue packets. It's called throttling, and accuracy of it is dependent on how the kernel is compiled.

There're 3 important options in modern kernels, as far as timers' resolution goes: 'tickless system', 'high resolution timer support' and 'timer frequency'.

If you have 'tickless system' enabled, then the timer interrupt will trigger as slowly as possible, but each time a scheduler throttles itself (or any other part of the kernel needs better accuracy), the rate will be increased as needed / possible. The ceiling is either 'timer frequency' if 'high resolution timer support' is not available or not compiled in, or it's hardware dependent and can go far beyond the highest 'timer frequency' setting available.

If 'tickless system' is not enabled, the timer will trigger at a fixed rate specified by 'timer frequency' - regardless if high resolution timers are or aren't available.

This is important to keep those settings in mind, as in scenario like: no tickless, no HR timers, frequency set to 100hz - throttling accuracy would be at 10ms. It doesn't automatically mean you would be limited to ~0.8Mbit/s (assuming packets at ~1KB) - as long as your queues are prepared to cover for timer inaccuracy. Of course, in case of e.g. locally generated UDP traffic - appropriate socket size is needed as well. Short example to make it more understandable (assume hardcore anti-schedule settings - HZ=100, no HR timers, no tickless):

```
tc qdisc add dev eth0 root handle 1:0 hfsc default 1
tc class add dev eth0 parent 1:0 classid 1:1 hfsc rt m2 10Mbit
```

Assuming packet of ~1KB size and HZ=100, that averages to ~0.8Mbit - anything beyond it (e.g. the above example with specified rate over 10x larger) will require appropriate queuing and cause bursts every ~10 ms. As you can imagine, any HFSC's RT guarantees will be seriously invalidated by that. Aforementioned example is mainly important if you deal with old hardware - as is particularly popular for home server chores. Even then, you can easily set HZ=1000 and have very accurate scheduling for typical adsl speeds.

Anything modern (apic or even hpet msi based timers + 'tickless system') will provide enough accuracy for superb 1Gbit scheduling. For example, on one of my cheap dual-core AMD boards I have the following settings:

```
tc qdisc add dev eth0 parent root handle 1:0 hfsc default 1
tc class add dev eth0 parent 1:0 classid 1:1 hfsc rt m2 300mbit
```

And a simple:

```
nc -u dst.host.com 54321 </dev/zero
nc -l -p 54321 >/dev/null
```

...will yield the following effects over a period of ~10 seconds (taken from /proc/interrupts):

```
319: 42124229   0  HPET_MSI-edge  hpet2 (before)
319: 42436214   0  HPET_MSI-edge  hpet2 (after 10s.)
```

That's roughly 31000/s. Now compare it with HZ=1000 setting. The obvious drawback of it is that cpu load can be rather high with servicing that many timer interrupts. The example with 300Mbit RT service curve on 1Gbit link is particularly ugly, as it requires a lot of throttling with minuscule delays.

Also note that it's just an example showing the capabilities of current hardware. The above example (essentially a 300Mbit TBF emulator) is pointless on an internal interface to begin with: you will pretty much always want a regular LS service curve there, and in such a scenario HFSC simply doesn't throttle at all.

300Mbit RT service curve (selected columns from mpstat -P ALL 1):

```
10:56:43 PM  CPU  %sys     %irq   %soft   %idle
10:56:44 PM  all  20.10    6.53   34.67   37.19
10:56:44 PM    0  35.00    0.00   63.00    0.00
10:56:44 PM    1   4.95   12.87    6.93   73.27
```

So, in the rare case you need those speeds with only a RT service curve, or with a UL service curve: remember the drawbacks.

## CAVEAT: RANDOM ONLINE EXAMPLES
For reasons unknown (though well guessed), many examples you can google love to overuse UL criterion and stuff it in every node possible. This makes no sense and works against what HFSC tries to do (and does pretty damn well). Use UL where it makes sense: on the uppermost node to match upstream router's uplink capacity. Or in special cases, such as testing (limit certain subtree to some speed), or customers that must never get more than certain speed. In the last case you can usually achieve the same by just using a RT criterion without LS+UL on leaf nodes.

As for the router case - remember it's good to differentiate between "traffic to router" (remote console, web config, etc.) and "outgoing traffic", so for example:

```
tc qdisc add dev eth0 root handle 1:0 hfsc default 0x8002
tc class add dev eth0 parent 1:0 classid 1:999 hfsc rt m2 50Mbit
tc class add dev eth0 parent 1:0 classid 1:1 hfsc ls m2 2Mbit ul m2 2Mbit
```

... so "internet" tree under 1:1 and "router itself" as 1:999

## LAYER2 ADAPTATION
Please refer to tc-stab(8)

## SEE ALSO
tc(8), tc-hfsc(8), tc-stab(8)

Please direct bugreports and patches to: <netdev@vger.kernel.org>

## AUTHOR
Manpage created by Michal Soltys (soltys@ziu.info)


irda

package: irda-utils

title: irda(7)

summary: The Linux-IrDA protocol stack

text:
# irda(7)

## NAME
irda - The Linux-IrDA protocol stack

## SYNOPSIS
\#include <linux/irda.h>

stream_s = socket(PF_INET, SOCK_STREAM, 0);

seqpkt_s = socket(PF_INET, SOCK_SEQPACKET, 0);

dgram_s = socket(PF_INET, SOCK_DGRAM, IRDAPROTO_UNITDATA);

ultra_s = socket(PF_INET, SOCK_DGRAM, IRDAPROTO_ULTRA);

## DESCRIPTION
Linux-IrDA is a complete implementation of the various IrDA protocols and IrDA drivers for Linux.

The configuration of the low level of the IrDA stack (IrDA ports) and the various IrDA drivers are described in irattach(8).

The usage of the higher layers of the IrDA stack (IrCOMM, IrLPT, IrNET, IrLAN, OBEX...) are described in their respective man pages.

The core of the Linux-IrDA protocol stack is composed of the IrLAP, IrLMP, IrTTP and IrIAS protocols and is implemented as a kernel module. The programmer's interface for the IrDA stack is socket based. For more information on sockets, see socket(7).

Note that higher level IrDA protocols may offer a different programmer's interface. For example IrCOMM offers a TTY based interface and OBEX is available through a user space library.

## SOCKETS TYPE
The Linux-IrDA socket interface offers 4 types of sockets:

Stream socket - SOCK_STREAM, 0

Stream sockets provides a reliable, stream oriented, full duplex connection between two sockets on top of IrTTP, similar to TCP sockets. IrTTP guarantees that the data arrives in order and manages flow contol, IrLAP retransmits lost packets.

Stream sockets does not preserve record boundaries.

SeqPacket socket - SOCK_SEQPACKET, 0

SeqPacket sockets provides a reliable, datagram oriented, full duplex connection between two sockets on top of IrTTP. IrTTP guarantees that the data arrives in order and manages flow contol, IrLAP retransmits lost packets.

SeqPacket sockets preserve record boundaries. Large datagrams will be fragmented as needed.

Datagram socket - SOCK_DGRAM, IRDAPROTO_UNITDATA

SeqPacket sockets provides a reliable, datagram oriented, full duplex connection between two sockets on top of IrLMP. There is no guarantees that the data arrives in order and there is no flow contol, however IrLAP retransmits lost packets.

Datagram sockets preserve record boundaries. No fragmentation is provided, datagrams larger than the IrDA link MTU are truncated or discarded.

Ultra socket - SOCK_DGRAM, IRDAPROTO_ULTRA

Ultra sockets provides a connectionless, unreliable datagram packet service on top of IrLAP-Ultra. Ultra datagrams are sent and receive only when no IrLAP connection is established and otherwise discarded. They are always transmitted at 9600 bauds. Datagrams may be lost, reordered, and there is no flow control.

Ultra sockets preserve record boundaries. No fragmentation is provided, datagrams larger than the Ultra MTU (382 bytes) are truncated or discarded.

## ADDRESS FORMAT
An IrDA socket address is defined as a combination of an IrDA interface address and a service name. Service names are automatically resolved to lsap through the IrIAP protocol.

```
    struct sockaddr_irda {

        sa_family_t sir_family;   /* AF_IRDA */

        __u8        sir_lsap_sel; /* LSAP selector */

        __u32       sir_addr;     /* Device address */

        char        sir_name[25]; /* Usually <service>:IrDA:TinyTP */

    };
```

sin_family is always set to AF_IRDA. sir_lsap_sel is usually not used. sir_addr is the address of the peer and optional (and that case the first peer discoverd will be used). sir_name is the service name of the socket.

## SOCKET OPTIONS
IrDA sockets supports some protocol specific socket options that can be set with setsockopt(2) and read with getsockopt(2). The socket option level for IrDA is SOL_IRLMP.

Options that can be set:

IRLMP_IAS_SET

Set an entry in the local IAS database.

IRLMP_IAS_DEL

Delete an entry from the local IAS database.

IRLMP_MAX_SDU_SIZE

Set maximum receive MTU for SeqPacket sockets.

IRLMP_HINTS_SET

Set IrDA hint bits to be advertised to peers.

IRLMP_HINT_MASK_SET

Set IrDA hint bits filter to be used when performing discovery.

Options that can be get:

IRLMP_ENUMDEVICES

Perform link level discovery and return the content of the discovery log.

IRLMP_MAX_SDU_SIZE

Get maximum receive MTU.

IRLMP_IAS_GET

Get an entry from the local IAS database.

IRLMP_IAS_QUERY

Query an entry in IAS database of a peer using IrIAP.

IRLMP_WAITDEVICE

Block until a new device is discovered. Experimental feature, use with caution.

## AUTHOR
Jean Tourrilhes - jt@hpl.hp.com

## SEE ALSO
irattach(8), irdadump(8), irnet(4), irnetd(8).


package: javapackages-local

title: mvn_alias(7)

summary: add alias(es) for Maven artifact(s)

text:
# mvn_alias(7)

## NAME
mvn_alias - add alias(es) for Maven artifact(s)

## SYNOPSIS
%mvn_alias artifact-coordinates alias [alias ...]

## DESCRIPTION
mvn_alias macro causes instructions for artifact installation to be added to XMvn reactor configuration. It is used to specify alternative names (aliases) for Maven artifacts.

Specified artifact coordinates must match at least one artifact. If not then behavior is unspecified. It is possible to specify artifact coordinates matching multiple artifacts, so one call to mvn_alias can affect installation of more than one artifact.

## OPERANDS
artifact-coordinates

Artifact coordinates specify artifact(s) that this rule applies to. Coordinates are in format groupId:artifactId[:extension[:classifier]][:version]. If extension is specified then version must be specified too. If any part is omitted or equal to empty string then it matches any string. Wildcards and brace expansions are supported in each part. For more information see XMvn Configuration Reference.

alias

Coordinates specifying artifact alias (alternative name under which matching artifacts will be available). Coordinates are in format groupId:artifactId[:extension[:classifier]][:version]. If extension is specified then version must be specified too. If any part is omitted or equal to empty string then corresponding part from artifact-coordinates will be substituted. Backreferences are supported in form @n, where n is an integer corresponding to brace in artifact-coordinates.

## AUTHOR
Originally written by Mikolaj Izdebski. Versions 3.0.0 and later were written by Stanislav Ochotnicky.

## REPORTING BUGS
Bugs should be reported through Java Packages Tools issue tracker at Github: https://github.com/fedora-java/javapackages/issues.

## SEE ALSO
gradle_build(7), mvn_build(7), mvn_compat_version(7), mvn_config(7), mvn_file(7), mvn_package(7), xmvn(1).


title: mvn_artifact(7)

summary: request installation of Maven artifact

text:
# mvn_artifact(7)

## NAME
mvn_artifact - request installation of Maven artifact

## SYNOPSIS
%mvn_artifact [options] model [artifact-file]

%mvn_artifact [options] artifact-coordinates artifact-file

## DESCRIPTION
mvn_artifact macro marks specified Maven artifact to be installed by further call to mvn_install. Multiple calls to mvn_artifact and/or mvn_build can be made to request installation of multiple artifacts.

## OPTIONS
--skip-dependencies

Do not try to gather list of dependencies for given Maven artifact.

-Dproperty=value

Add artifact property

## OPERANDS
model

Path to raw project object model (POM) file to be associated and installed with artifact.

artifact-file

Path to file to be used as artifact file. If omitted then no artifact file is installed.

artifact-coordinates

Artifact coordinates specify artifact to be installed. If specified then no model file is installed with artifact. Coordinates are in format groupId:artifactId[:extension[:classifier]]:version. If extension is omitted then "jar" is used. If classifier is omitted then empty classifier is used. For more information see XMvn Configuration Reference.

## AUTHOR
Written by Michal Srb.

## REPORTING BUGS
Bugs should be reported through Java Packages Tools issue tracker at Github: https://github.com/fedora-java/javapackages/issues.

## SEE ALSO
gradle_build(7), mvn_build(7), mvn_install(7).


title: mvn_build(7)

summary: build Maven project with XMvn

text:
# mvn_build(7)

## NAME
mvn_build - build Maven project with XMvn

## SYNOPSIS
%mvn_build [options] [-- Maven-arguments]

## DESCRIPTION
mvn_build macro builds Maven project by calling XMvn and generates reactor structure information to be used by mvn_install.

By default Maven phase verify and goal javadoc:aggregate are executed, as well as some additional XMvn-specific goals or phases. If -f is specified then phase package is executed instead of verify. If -j is given then goal javadoc:aggregate is skipped.

Any arguments after -- are passed directly to XMvn. See xmvn(1) for more information on availability of XMvn options.

## OPTIONS
-d, --xmvn-debug

Enable XMvn debugging output. This option causes XMvn to write verbose debugging information to standard output. Debugging information includes at least details about artifact resolution from system repositories.

-f, --force

Skip compilation and execution of unit and integration tests, as well as resolution of build dependencies with scope test. This option causes Maven phase package to be executed instead of default phase verify, defines property maven.test.skip=true which disables compilation and execution of tests and causes XMvn to remove any project dependencies with scope test.

-i, --skip-install

Skip artifact installation. This option disables generation of reactor structure information so that future calls to mvn_install will not result in installation of artifacts produced in current Maven reactor.

-j, --skip-javadoc

Skip javadoc generation. This option skips running Maven Javadoc Plugin. Useful for packages which don’t want to produce Java API documentation.

-s, --singleton

Enable singleton packaging (one artifact per package). This option causes artifacts with identical artifactId to be installed as part of the same subpackage. This behavior can be further customized by adding more specific packaging rules with mvn_package.

-X, --debug

Enable Maven debugging output. Implies -d. This option causes Maven to write verbose debugging information to standard output.

## ENVIRONMENT
xmvn_bootstrap

Run XMvn in online mode. If xmvn_bootstrap RPM macro is defined to any value then XMvn is ran in online mode. Otherwise XMvn is ran in offline mode. Online mode of XMvn allows missing dependency artifacts to be fetched from remote repositories. This behavior is mostly useful when bootstrapping new packages, which dependecies have not yet been packaged.

## AUTHOR
Originally written by Mikolaj Izdebski. Versions 3.0.0 and later were written by Stanislav Ochotnicky.

## REPORTING BUGS
Bugs should be reported through Java Packages Tools issue tracker at Github: https://github.com/fedora-java/javapackages/issues.

## SEE ALSO
mvn_alias(7), mvn_compat_version(7), mvn_config(7), mvn_file(7), mvn_package(7), xmvn(1).


title: mvn_compat_version(7)

summary: set version(s) for Maven artifact(s)

text:
# mvn_compat_version(7)

## NAME
mvn_compat_version - set version(s) for Maven artifact(s)

## SYNOPSIS
%mvn_compat_version artifact-coordinates version [version ...]

## DESCRIPTION
mvn_compat_version macro causes instructions for artifact installation to be added to XMvn reactor configuration. It is used to specify versions for Maven artifacts.

Specified artifact coordinates must match at least one artifact. If not then behavior is unspecified. It is possible to specify artifact coordinates matching multiple artifacts, so one call to mvn_compat_version can affect installation of more than one artifact.

## OPERANDS
artifact-coordinates

Artifact coordinates specify artifact(s) that this rule applies to. Coordinates are in format groupId:artifactId[:extension[:classifier]][:version]. If extension is specified then version must be specified too. If any part is omitted or equal to empty string then it matches any string. Wildcards and brace expansions are supported in each part. For more information see XMvn Configuration Reference.

version

Strings specifying artifact version. Backreferences are supported in form @n, where n is an integer corresponding to brace in artifact-coordinates.

## AUTHOR
Written by Stanislav Ochotnicky.

## REPORTING BUGS
Bugs should be reported through Java Packages Tools issue tracker at Github: https://github.com/fedora-java/javapackages/issues.

## SEE ALSO
gradle_build(7), mvn_alias(7), mvn_build(7), mvn_config(7), mvn_file(7), mvn_package(7), xmvn(1).


title: mvn_config(7)

text:
# mvn_config(7)

## NAME
mvn_config - specify custom XMvn configuration option

## SYNOPSIS
%mvn_config key value

## DESCRIPTION
mvn_config macro causes custom configuration options to be added to XMvn reactor configuration.

## OPERANDS
key

Configuration option key (unique name). This is XPath-like address of XML configuration node - list of XML nodes delimited by /. If unknown key is given, behavior is unspecified. For list of available keys see XMvn Configuration Reference.

value

Value of specified option. Must be either plain text or XML content. If value format is inappropriate for particular option, behavior is unspecified.

## AUTHOR
Originally written by Mikolaj Izdebski. Versions 3.0.0 and later were written by Stanislav Ochotnicky.

## REPORTING BUGS
Bugs should be reported through Java Packages Tools issue tracker at Github: https://github.com/fedora-java/javapackages/issues.

## SEE ALSO
gradle_build(7), mvn_alias(7), mvn_build(7), mvn_compat_version(7), mvn_file(7), mvn_package(7), xmvn(1).


title: mvn_file(7)

text:
# mvn_file(7)

## NAME
mvn_file - set installation location(s) for Maven artifact(s)

## SYNOPSIS
%mvn_file artifact-coordinates primary-file [secondary-file ...]

## DESCRIPTION
mvn_file macro causes instructions for artifact installation to be added to XMvn reactor configuration. It is used to control locations of artifact files in file system. (The exact meaning of artifact location is dependant on particular implementation of XMvn repository into which artifacts will be installed.)

Specified artifact coordinates must match at least one artifact. If not then behavior is unspecified. It is possible to specify artifact coordinates matching multiple artifacts, so one call to mvn_file can affect installation of more than one artifact.

## OPERANDS
artifact-coordinates

Artifact coordinates specify artifact(s) that this rule applies to. Coordinates are in format groupId:artifactId[:extension[:classifier]][:version]. If extension is specified then version must be specified too. If any part is omitted or equal to empty string then it matches any string. Wildcards and brace expansions are supported in each part. For more information see XMvn Configuration Reference.

primary-file

Primary location of artifact file. This operand is passed directly to XMvn installer. Its exact meaning is specific to particular repository implementation used to install given artifact. Backreferences are supported in form @n, where n is an integer corresponding to brace in artifact-coordinates.

secondary-file

Secondary location of artifact file. There can be any number (zero or more) of secondary artifact files. These operands are passed directly to XMvn installer. Their exact meaning is specific to particular repository implementation used to install given artifact. Backreferences are supported in form @n, where n is an integer corresponding to brace in artifact-coordinates.

## AUTHOR
Originally written by Mikolaj Izdebski. Versions 3.0.0 and later were written by Stanislav Ochotnicky.

## REPORTING BUGS
Bugs should be reported through Java Packages Tools issue tracker at Github: https://github.com/fedora-java/javapackages/issues.

## SEE ALSO
gradle_build(7), mvn_alias(7), mvn_build(7), mvn_compat_version(7), mvn_config(7), mvn_package(7), xmvn(1).


title: mvn_install(7)

summary: install Maven artifacts

text:
# mvn_install(7)

## NAME
mvn_install - install Maven artifacts

## SYNOPSIS
%mvn_install [-X] [-J directory]

## DESCRIPTION
mvn_install macro installs Maven artifacts into %buildroot.

Specification of artifacts to be installed is taken from .xmvn-reactor file. This file can be populated using mvn_build and/or mvn_artifact macros.

Specification how artifacts should be installed is taken from installer settings section in XMvn configuration. See XMvn Configuration Reference for more information. Macros mvn_alias(7), mvn_build(7), mvn_compat_version(7), mvn_config(7), mvn_file(7) and mvn_package(7) are capable of writing configuration that can affect behavior of mvn_install.

## OPTIONS
-X

Enable debugging output. This option causes XMvn installer to write verbose debugging information to standard output.

-J directory

Specify alternative API documentation directory. By default API documentation is searched for in target/site/apidocs directory. The -J option allows to override this default location.

## AUTHOR
Written by Mikolaj Izdebski.

## REPORTING BUGS
Bugs should be reported through Java Packages Tools issue tracker at Github: https://github.com/fedora-java/javapackages/issues.

## SEE ALSO
gradle_build(7), mvn_alias(7), mvn_artifact(7), mvn_build(7), mvn_compat_version(7), mvn_config(7), mvn_file(7), mvn_package(7), xmvn(1).


title: mvn_package(7)

text:
# mvn_package(7)

## NAME
mvn_package - specify target package for Maven artifact(s)

## SYNOPSIS
%mvn_package artifact-coordinates [target-package]

## DESCRIPTION
mvn_package macro causes instructions for artifact installation to be added to XMvn reactor configuration. It is used to specify target package to which Maven artifacts should be installed.

Specified artifact coordinates must match at least one artifact. If not then behavior is unspecified. It is possible to specify artifact coordinates matching multiple artifacts, so one call to mvn_package can affect installation of more than one artifact.

## OPERANDS
artifact-coordinates

Artifact coordinates specify artifact(s) that this rule applies to. Coordinates are in format groupId:artifactId[:extension[:classifier]][:version]. If extension is specified then version must be specified too. If any part is omitted or equal to empty string then it matches any string. Wildcards and brace expansions are supported in each part. For more information see XMvn Configuration Reference.

target-package

Name of target (sub-)package to which matching artifacts will be installed. Backreferences are supported in form @n, where n is an integer corresponding to brace in artifact-coordinates. A special value of noinstall means that matching artifact(s) should not be installed to any package. Special value of default means that matching artifact(s) should be installed into main package. If target-package is omitted value of __default is assumed.

## AUTHOR
Originally written by Mikolaj Izdebski. Versions 3.0.0 and later were written by Stanislav Ochotnicky.

## REPORTING BUGS
Bugs should be reported through Java Packages Tools issue tracker at Github: https://github.com/fedora-java/javapackages/issues.

## SEE ALSO
gradle_build(7), mvn_alias(7), mvn_build(7), mvn_compat_version(7), mvn_config(7), mvn_file(7), xmvn(1).


title: pom_add_dep(7)

text:
# pom_add_dep(7)

## NAME
pom_add_dep - add dependency to Maven POM file or Ivy module

## SYNOPSIS
%pom_add_dep groupId:artifactId[:version[:scope]] [POM-location]... [extra-XML]

%pom_add_dep org:name[:rev[:conf[:transitive]]] [Ivy-module-location]... [extra-XML]

%pom_add_dep_mgmt groupId:articId[:version[:scope]] [POM-location]... [extra-XML]

## DESCRIPTION
These macros patch specified POM or Ivy file adding a dependency on given Maven artifact specified by artifact coordinates. pom_add_dep adds the dependency to <dependencies> XML node, while pom_add_dep_mgmt adds it to <dependencyManagement>.

groupId and artifactId are identifiers of Maven artifact on which dependency is to be added. They must be specified. If version is not specified then default value of "any" is used. If scope is not specified then no scope is defined (Maven defaults to "compile" in this case).

When modifying Ivy modules, the org, name and rev correspond to the Maven groupId and artifactId and version. Org and name must be specified, other attributes use defaults. The conf attribute specifies the configuration in which the dependency should apply. The transitive attribute specifies whether the dependency should also pull in it’s dependencies. It accepts boolean values - true or false. When unspecified Ivy defaults to true.

POM location can be either a full path to the POM or Ivy file, or a path to the directory containing pom.xml or ivy.xml. If POM location is not given then pom.xml or ivy.xml from current working directory is used. When both pom.xml and ivy.xml are present, pom.xml is processed. You can specify more file locations which will be processed.

Extra XML is additional XML code to be added into the <dependency> node. This parameter can be ommited, in which case no extra XML is appended.

## EXAMPLES
%pom_add_dep foo:bar baz - this call adds dependency on artifact foo:bar to baz/pom.xml file.

## AUTHOR
Written by Mikolaj Izdebski.

## REPORTING BUGS
Bugs should be reported through Java Packages Tools issue tracker at Github: https://github.com/fedora-java/javapackages/issues.

## SEE ALSO
pom_add_parent(7), pom_add_plugin(7), pom_disable_module(7), pom_remove_dep(7), pom_remove_parent(7), pom_remove_plugin(7), pom_change_dep(7), pom_set_parent(7), pom_xpath_inject(7), pom_xpath_remove(7), pom_xpath_replace(7), pom_xpath_set(7).


title: pom_add_parent(7)

summary: add parent POM reference to POM file

text:
# pom_add_parent(7)

## NAME
pom_add_parent - add parent POM reference to POM file

## SYNOPSIS
%pom_add_parent groupId:artifactId[:version] [POM-location]...

## DESCRIPTION
This macro patches specified POM file adding a reference to parent POM with specified groupId, artifactId and version.

groupId and artifactId are identifiers of Maven group and artifact of the POM to be referenced as parent POM. They must be specified. If version is not specified then default value of "any" is used.

POM location can be either a full path to the POM file, or a path to the directory containing pom.xml. If POM location is not given then pom.xml from current working directory is used. You can specify more file locations which will be processed.

## EXAMPLES
%pom_add_parent foo:bar baz - this call adds reference to parent POM artifact foo:bar to baz/pom.xml file.

## AUTHOR
Written by Mikolaj Izdebski.

## REPORTING BUGS
Bugs should be reported through Java Packages Tools issue tracker at Github: https://github.com/fedora-java/javapackages/issues.

## SEE ALSO
pom_add_dep(7), pom_add_plugin(7), pom_disable_module(7), pom_remove_dep(7), pom_remove_parent(7), pom_remove_plugin(7), pom_change_dep(7), pom_set_parent(7), pom_xpath_inject(7), pom_xpath_remove(7), pom_xpath_replace(7), pom_xpath_set(7).


title: pom_add_plugin(7)

summary: add plugin invocation to POM file

text:
# pom_add_plugin(7)

## NAME
pom_add_plugin - add plugin invocation to POM file

## SYNOPSIS
%pom_add_plugin groupId:artifactId[:version] [POM-location]... [extra-XML]

## DESCRIPTION
This macro patches specified POM file adding plugin invocation of given groupId and artifactId.

groupId and artifactId are identifiers of Maven plugin artifact of which invocation is to be added. groupId may be ommited, in which case value of "org.apache.maven.plugins" is used as default. artifactId must be specified. If version is not specified then default value of "any" is used.

POM location can be either a full path to the POM file, or a path to the directory containing pom.xml. If POM location is not given then pom.xml from current working directory is used. You can specify more file locations which will be processed.

Extra XML is additional XML code to be added into the <plugin> node. This parameter can be ommited, in which case no extra XML is appended.

## EXAMPLES
%pom_add_plugin com.example:plugin foo - this call adds invocation of plugin com.example:plugin to foo/pom.xml.

%pom_add_plugin :maven-compiler-plugin . "<target>1.5</target>" - this call adds invocation of Maven Compiler Plugin with target configured to 1.5.

## AUTHOR
Written by Mikolaj Izdebski.

## REPORTING BUGS
Bugs should be reported through Java Packages Tools issue tracker at Github: https://github.com/fedora-java/javapackages/issues.

## SEE ALSO
pom_add_dep(7), pom_add_parent(7), pom_disable_module(7), pom_remove_dep(7), pom_remove_parent(7), pom_remove_plugin(7), pom_set_parent(7), pom_xpath_inject(7), pom_xpath_remove(7), pom_xpath_replace(7), pom_xpath_set(7).


title: pom_change_dep(7)

text:
# pom_change_dep(7)

## NAME
pom_change_dep - change dependency in Maven POM file or Ivy module

## SYNOPSIS
%pom_change_dep [OPTIONS] SOURCE_ARTIFACT CHANGED_ARTIFACT [POM-location]... [extra-XML]

%pom_change_dep [OPTIONS] SOURCE_ARTIFACT CHANGED_ARTIFACT [Ivy-module-location]... [extra-XML]

## OPTIONS
-r

Work in recursive mode. That means that given dependency is also changed in all enabled submodules of given POM file(s). Has no effect if the file is not Maven POM.

-f

Do not throw an error when one of the specified files doesn’t contain given dependency.

## DESCRIPTION
These macros patch specified POM or Ivy file changing a dependency on given Maven artifact specified by artifact coordinates to artifact specified by second set of Maven coordinates. The artifact specification has same format as %pom_add_dep. The omitted or empty parts in second artifact specification cause the original value to be left unmodified. Supplying a special value of - for given part causes that part of artifact specification to be deleted.

POM location can be either a full path to the POM or Ivy file, or a path to the directory containing pom.xml or ivy.xml. If POM location is not given then pom.xml or ivy.xml from current working directory is used. When both pom.xml and ivy.xml are present, pom.xml is processed. You can specify more file locations which will be processed.

Extra XML is additional XML code to be added into the <dependency> node. This parameter can be ommited, in which case no extra XML is appended.

## EXAMPLES
pom_change_dep foo: com.example.foo: - this call changes groupId of all dependencies which have groupId foo to com.example.foo. Their artifactId, versions and other possible parts are left unmodified.

## AUTHOR
Written by Michael Simacek.

## REPORTING BUGS
Bugs should be reported through Java Packages Tools issue tracker at Github: https://github.com/fedora-java/javapackages/issues.

## SEE ALSO
pom_add_dep(7), pom_add_parent(7), pom_add_plugin(7), pom_disable_module(7), pom_remove_dep(7), pom_remove_parent(7), pom_remove_plugin(7), pom_set_parent(7), pom_xpath_inject(7), pom_xpath_remove(7), pom_xpath_replace(7), pom_xpath_set(7).


title: pom_disable_module(7)

text:
# pom_disable_module(7)

## NAME
pom_disable_module - disable given project module in POM file

## SYNOPSIS
%pom_disable_module module-name [POM-location]...

## DESCRIPTION
This macro patches specified POM file not to contain reference to given project module.

Module name is the exact name of the module to be disabled. It must not be ommited.

POM location can be either a full path to the POM file, or a path to the directory containing pom.xml. If POM location is not given then pom.xml from current working directory is used. You can specify more file locations which will be processed.

## EXAMPLES
%pom_disable_module nonfree - this call removes aggregated module nonfree from POM file in current working directory.

## AUTHOR
Written by Mikolaj Izdebski.

## REPORTING BUGS
Bugs should be reported through Java Packages Tools issue tracker at Github: https://github.com/fedora-java/javapackages/issues.

## SEE ALSO
pom_add_dep(7), pom_add_parent(7), pom_add_plugin(7), pom_remove_dep(7), pom_remove_parent(7), pom_remove_plugin(7), pom_change_dep(7), pom_set_parent(7), pom_xpath_inject(7), pom_xpath_remove(7), pom_xpath_replace(7), pom_xpath_set(7).


title: pom_remove_dep(7)

text:
# pom_remove_dep(7)

## NAME
pom_remove_dep - remove dependency on Maven artifact from POM file

## SYNOPSIS
%pom_remove_dep [OPTIONS] [groupId]:[artifactId][:version[:scope]] [POM-location]...

%pom_remove_dep [OPTIONS] [org]:[name][:rev[:conf[:transitive]]] [Ivy-module-location]...

## OPTIONS
-r

Work in recursive mode. That means that dependency is also removed from all enabled submodules of given POM file(s).

-f

Do not throw an error when one of the specified files doesn’t contain given dependency.

## DESCRIPTION
This macro patches specified POM file not to contain dependencies on given Maven artifact.

groupId and artifactId are identifiers of Maven group and artifact of the module on which dependency is to be removed. If they are ommited then all identifiers are matched.

When modifying Ivy modules, the org and name correspond to the Maven groupId and artifactId.

POM location can be either a full path to the POM or Ivy file, or a path to the directory containing pom.xml or ivy.xml. If POM location is not given then pom.xml or ivy.xml from current working directory is used. When both pom.xml and ivy.xml are present, pom.xml is processed. You can specify more file locations. If the dependency is not found in all of given files, the command raises an error. This can be overriden with the -f option.

## EXAMPLES
%pom_remove_dep com.example: - this call removes dependency on all artifacts with groupId com.example from POM in current working directory.

%pom_remove_dep boo:bar target/location - this call removes dependency on artifacts with groupId foo and artifactId bar from target/location/pom.xml.

## AUTHOR
Written by Mikolaj Izdebski.

## REPORTING BUGS
Bugs should be reported through Java Packages Tools issue tracker at Github: https://github.com/fedora-java/javapackages/issues.

## SEE ALSO
pom_add_dep(7), pom_add_parent(7), pom_add_plugin(7), pom_disable_module(7), pom_remove_parent(7), pom_remove_plugin(7), pom_change_dep(7), pom_set_parent(7), pom_xpath_inject(7), pom_xpath_remove(7), pom_xpath_replace(7), pom_xpath_set(7).


title: pom_remove_parent(7)

text:
# pom_remove_parent(7)

## NAME
pom_remove_parent - remove parent POM reference from POM file

## SYNOPSIS
%pom_remove_parent [POM-location]...

## DESCRIPTION
This macro patches specified POM file removing reference to parent POM.

POM location can be either a full path to the POM file, or a path to the directory containing pom.xml. If POM location is not given then pom.xml from current working directory is used. You can specify more file locations which will be processed.

## EXAMPLES
%pom_remove_parent target/location - this call removes parent POM reference from target/location/pom.xml.

## AUTHOR
Written by Mikolaj Izdebski.

## REPORTING BUGS
Bugs should be reported through Java Packages Tools issue tracker at Github: https://github.com/fedora-java/javapackages/issues.

## SEE ALSO
pom_add_dep(7), pom_add_parent(7), pom_add_plugin(7), pom_disable_module(7), pom_remove_dep(7), pom_remove_plugin(7), pom_change_dep(7), pom_set_parent(7), pom_xpath_inject(7), pom_xpath_remove(7), pom_xpath_replace(7), pom_xpath_set(7).


title: pom_remove_plugin(7)

text:
# pom_remove_plugin(7)

## NAME
pom_remove_plugin - remove Maven plugin invocation from POM file

## SYNOPSIS
%pom_remove_plugin [OPTIONS] [groupId]:[artifactId][:version[:scope]] [POM-location]...

## OPTIONS
-r

Work in recursive mode. That means that plugin is also removed from all enabled submodules of given POM file(s).

-f

Do not throw an error when one of the specified files doesn’t contain given dependency.

## DESCRIPTION
This macro patches specified POM file not to contain invocations of given Maven plugin.

groupId and artifactId are identifiers of Maven group and artifact of the plugin which invocation is to be removed. If they are ommited then all identifiers are matched.

POM location can be either a full path to the POM file, or a path to the directory containing pom.xml. If POM location is not given then pom.xml from current working directory is used. You can specify more file locations which will be processed. You can specify more file locations.

## EXAMPLES
%pom_remove_plugin :maven-shade-plugin - this call removes invocation of Maven Shade Plugin from POM in current working directory.

## AUTHOR
Written by Mikolaj Izdebski.

## REPORTING BUGS
Bugs should be reported through Java Packages Tools issue tracker at Github: https://github.com/fedora-java/javapackages/issues.

## SEE ALSO
pom_add_dep(7), pom_add_parent(7), pom_add_plugin(7), pom_disable_module(7), pom_remove_dep(7), pom_remove_parent(7), pom_change_dep(7), pom_set_parent(7), pom_xpath_inject(7), pom_xpath_remove(7), pom_xpath_replace(7), pom_xpath_set(7).


title: pom_set_parent(7)

summary: set parent POM reference in POM file

text:
# pom_set_parent(7)

## NAME
pom_set_parent - set parent POM reference in POM file

## SYNOPSIS
%pom_set_parent groupId:artifactId[:version] [POM-location]...

## DESCRIPTION
This macro patches specified POM file setting reference to parent POM to specified groupId, artifactId and version.

This macros first removes parent POM reference and then adds a new one. It’s (more or less) equivalent to call to %pom_remove_parent followed by invocation of %pom_add_parent. See pom_remove_parent(7) and pom_add_parent(7) for more information about parameters.

POM location can be either a full path to the POM file, or a path to the directory containing pom.xml. If POM location is not given then pom.xml from current working directory is used. You can specify more file locations which will be processed.

## EXAMPLES
%pom_set_parent com.example:example-parent module - this call sets parent POM of module/pom.xml to com.example:example-parent.

## AUTHOR
Written by Mikolaj Izdebski.

## REPORTING BUGS
Bugs should be reported through Java Packages Tools issue tracker at Github: https://github.com/fedora-java/javapackages/issues.

## SEE ALSO
pom_add_dep(7), pom_add_parent(7), pom_add_plugin(7), pom_disable_module(7), pom_remove_dep(7), pom_remove_parent(7), pom_remove_plugin(7), pom_change_dep(7), pom_xpath_inject(7), pom_xpath_remove(7), pom_xpath_replace(7), pom_xpath_set(7).


title: pom_xpath_disable(7)

text:
# pom_xpath_disable(7)

## NAME
pom_xpath_disable - Disable all modules whose POM files satisfy given XPath condition

## SYNOPSIS
%pom_xpath_disable XPath-expression [POM-location]...

## DESCRIPTION
This macro recursively walks all enabled submodules of given POM and evaluates given XPath expression on them. If the expression returns a true value, matching submodule is disabled. Values considered true are defined by XPath specification as either true boolean value (i.e. returned by comparisons), non-empty node set, non-empty string or non-zero number.

If the main module (specified by POM-location or pom.xml by default) also satisfies the condition, processing is aborted prior to making any changes and an error is raised. When none of the modules satisfy it, an error is also raised.

POM location can be either a full path to the POM file, or a path to the directory containing pom.xml. If POM location is not given then pom.xml from current working directory is used. You can specify more file locations which will be processed.

## EXAMPLES
%pom_xpath_disable "/pom:project/pom:classifier = 'test'" - this call disables all modules with classifier test

%pom_xpath_disable /pom:project/pom:packaging - this call disables all sumbodules that explicitly specify packaging

## AUTHOR
Written by Michael Simacek.

## REPORTING BUGS
Bugs should be reported through Java Packages Tools issue tracker at Github: https://github.com/fedora-java/javapackages/issues.

## SEE ALSO
pom_add_dep(7), pom_add_parent(7), pom_add_plugin(7), pom_remove_dep(7), pom_remove_parent(7), pom_remove_plugin(7), pom_change_dep(7), pom_set_parent(7), pom_xpath_inject(7), pom_xpath_remove(7), pom_xpath_replace(7), pom_xpath_set(7). pom_disable_module(7).


title: pom_xpath_inject(7)

summary: inject code into XML file

text:
# pom_xpath_inject(7)

## NAME
pom_xpath_inject - inject code into XML file

## SYNOPSIS
%pom_xpath_inject XPath XML-code [XML-file-location]...

## DESCRIPTION
This macro patches specified XML file appending given code as children of all XML nodes described by the XPath expression.

XPath is an expression describing a set of XML nodes in the XML file to which child code is to be appended. It must be a properly formated XPath 1.0 expression, as described in http://www.w3.org/TR/xpath/.

Maven POM files use specific XML namespace http://maven.apache.org/POM/4.0.0 as default. This namespace needs to be explicitly specified in XPath expressions by prefixing all node names with pom: (i.e. pom:modelVersion).

Many other XML formats also use namespaces which you have to explicitly specify. This script will use the namespace prefix names from the xmlns declarations in the document’s root element. So if the document begins with <root xmlns:my="myurl.com"> you would select the root node with XPath expression /my:root. If the document specifies a default namespace (e.g. xmlns="myurl.com") use the prefix named default to acces elements in that namespace.

XML location can be either a full path to the XML, or a path to the directory containing pom.xml or ivy.xml. If XML location is not given then pom.xml or ivy.xml from current working directory is used. When both pom.xml and ivy.xml are present, pom.xml is processed. You can specify more file locations.

## EXAMPLES
%pom_xpath_inject pom:project "<packaging>war</packaging>" - this call sets packaging of POM in current working directory to war.

%pom_xpath inject configurations '<conf name="test"/>' - this adds a new configuration to the Ivy file in current working directory.

## AUTHOR
Written by Mikolaj Izdebski.

## REPORTING BUGS
Bugs should be reported through Java Packages Tools issue tracker at Github: https://github.com/fedora-java/javapackages/issues.

## SEE ALSO
pom_add_dep(7), pom_add_parent(7), pom_add_plugin(7), pom_disable_module(7), pom_remove_dep(7), pom_remove_parent(7), pom_remove_plugin(7), pom_change_dep(7), pom_set_parent(7), pom_xpath_remove(7), pom_xpath_replace(7), pom_xpath_set(7).


title: pom_xpath_remove(7)

summary: remove a node from XML file

text:
# pom_xpath_remove(7)

## NAME
pom_xpath_remove - remove a node from XML file

## SYNOPSIS
%pom_xpath_remove [OPTIONS] XPath [XML-file-location]...

## OPTIONS
-r

Work in recursive mode. That means that given node is also removed from all enabled submodules of given POM file(s). Has no effect if the file is not Maven POM.

-f

Do not throw an error when one of the specified files doesn’t contain given node.

## DESCRIPTION
This macro patches specified POM file removing all XML nodes described by the XPath expression. This also works on attributes and text nodes.

XPath is an expression describing a set of XML nodes to be removed from the POM file. It must be a properly formated XPath 1.0 expression, as described in http://www.w3.org/TR/xpath/.

Maven POM files use specific XML namespace http://maven.apache.org/POM/4.0.0 as default. This namespace needs to be explicitly specified in XPath expressions by prefixing all node names with pom (i.e. pom:modelVersion).

Many other XML formats also use namespaces which you have to explicitly specify. This script will use the namespace prefix names from the xmlns declarations in the document’s root element. So if the document begins with <root xmlns:my="myurl.com"> you would select the root node with XPath expression /my:root. If the document specifies a default namespace (eg xmlns="myurl.com") use the prefix named default to acces elements in that namespace.

XML location can be either a full path to the XML, or a path to the directory containing pom.xml or ivy.xml. If XML location is not given then pom.xml or ivy.xml from current working directory is used. When both pom.xml and ivy.xml are present, pom.xml is processed. You can specify more file locations.

## EXAMPLES
%pom_xpath_remove pom:project/pom:reporting - this call removes reporting section from POM in current working directory.

%pom_xpath_remove 'ivy:configure' build.xml - this call disables loading of ivy configuration in build.xml file. Note the use of ivy namespace which was declared in the document as xmlns:ivy="antlib:org.apache.ivy.ant".

## AUTHOR
Written by Mikolaj Izdebski.

## REPORTING BUGS
Bugs should be reported through Java Packages Tools issue tracker at Github: https://github.com/fedora-java/javapackages/issues.

## SEE ALSO
pom_add_dep(7), pom_add_parent(7), pom_add_plugin(7), pom_disable_module(7), pom_remove_dep(7), pom_remove_parent(7), pom_remove_plugin(7), pom_change_dep(7), pom_set_parent(7), pom_xpath_inject(7), pom_xpath_replace(7), pom_xpath_set(7).


title: pom_xpath_replace(7)

text:
# pom_xpath_replace(7)

## NAME
pom_xpath_replace - replace XML node from XML file with given code

## SYNOPSIS
%pom_xpath_replace XPath XML-code [XML-file-location]...

## OPTIONS
-r

Work in recursive mode. That means that given node is also replaced in all enabled submodules of given POM file(s). Has no effect if the file is not Maven POM.

-f

Do not throw an error when one of the specified files doesn’t contain given node.

## DESCRIPTION
This macro patches specified POM file removing all XML nodes described by the XPath expression and injecting given XML code in their place.

XPath is an expression describing a set of XML nodes to be removed from the POM file. It must be a properly formated XPath 1.0 expression, as described in http://www.w3.org/TR/xpath/.

Maven POM files use specific XML namespace http://maven.apache.org/POM/4.0.0 as default. This namespace needs to be explicitly specified in XPath expressions by prefixing all node names with pom (i.e. pom:modelVersion).

Many other XML formats also use namespaces which you have to explicitly specify. This script will use the namespace prefix names from the xmlns declarations in the document’s root element. So if the document begins with <root xmlns:my="myurl.com"> you would select the root node with XPath expression /my:root. If the document specifies a default namespace (eg xmlns="myurl.com") use the prefix named default to acces elements in that namespace.

XML location can be either a full path to the XML, or a path to the directory containing pom.xml or ivy.xml. If XML location is not given then pom.xml or ivy.xml from current working directory is used. When both pom.xml and ivy.xml are present, pom.xml is processed. You can specify more file locations.

## AUTHOR
Written by Mikolaj Izdebski.

## REPORTING BUGS
Bugs should be reported through Java Packages Tools issue tracker at Github: https://github.com/fedora-java/javapackages/issues.

## SEE ALSO
pom_add_dep(7), pom_add_parent(7), pom_add_plugin(7), pom_disable_module(7), pom_remove_dep(7), pom_remove_parent(7), pom_remove_plugin(7), pom_change_dep(7), pom_set_parent(7), pom_xpath_inject(7), pom_xpath_remove(7), pom_xpath_set(7).


title: pom_xpath_set(7)

summary: set contents of XML node from XML file

text:
# pom_xpath_set(7)

## NAME
pom_xpath_set - set contents of XML node from XML file

## SYNOPSIS
%pom_xpath_set XPath new-contents [XML-file-location]

## DESCRIPTION
This macro patches specified POM file replacing contents of all XML nodes described by the XPath expression with given new text content. This works on both elements and attributes.

XPath is an expression describing a set of XML nodes to be removed from the POM file. It must be a properly formated XPath 1.0 expression, as described in http://www.w3.org/TR/xpath/.

Maven POM files use specific XML namespace http://maven.apache.org/POM/4.0.0 as default. This namespace needs to be explicitly specified in XPath expressions by prefixing all node names with pom (i.e. pom:modelVersion).

Many other XML formats also use namespaces which you have to explicitly specify. This script will use the namespace prefix names from the xmlns declarations in the document’s root element. So if the document begins with <root xmlns:my="myurl.com"> you would select the root node with XPath expression /my:root. If the document specifies a default namespace (eg xmlns="myurl.com") use the prefix named default to acces elements in that namespace.

XML location can be either a full path to the XML, or a path to the directory containing pom.xml or ivy.xml. If XML location is not given then pom.xml or ivy.xml from current working directory is used. When both pom.xml and ivy.xml are present, pom.xml is processed. You can specify more file locations.

## AUTHOR
Written by Mikolaj Izdebski.

## REPORTING BUGS
Bugs should be reported through Java Packages Tools issue tracker at Github: https://github.com/fedora-java/javapackages/issues.

## SEE ALSO
pom_add_dep(7), pom_add_parent(7), pom_add_plugin(7), pom_disable_module(7), pom_remove_dep(7), pom_remove_parent(7), pom_remove_plugin(7), pom_set_parent(7), pom_xpath_inject(7), pom_xpath_remove(7), pom_xpath_replace(7).


asymmetric-key

package: keyutils

title: asymmetric-key(7)

text:
# asymmetric-key(7)

## NAME
asymmetric - Kernel key type for holding asymmetric keys

## OVERVIEW
A kernel key of asymmetric type acts as a handle to an asymmetric key as used for public-key cryptography. The key material itself may be held inside the kernel or it may be held in hardware with operations being offloaded. This prevents direct user access to the cryptographic material.

Keys may be any asymmetric type (RSA, ECDSA, ...) and may have both private and public components present or just the public component.

Asymmetric keys can be made use of by both the kernel and userspace. The kernel can make use of them for module signature verification and kexec image verification for example. Userspace is provided with a set of keyctl(KEYCTL_PKEY_*) calls for querying and using the key. These are wrapped by libkeyutils as functions named keyctl_pkey_*().

An asymmetric-type key can be loaded by the keyctl utility using a command line like:

```
openssl x509 -in key.x509 -outform DER |
keyctl padd asymmetric foo @s
```

## DESCRIPTION
The asymmetric-type key can be viewed as a container that comprises of a number of components:

Parsers

The asymmetric key parsers attempt to identify the content of the payload blob and extract useful data from it with which to instantiate the key. The parser is only used when adding, instantiating or updating a key and isn't thereafter associated with the key.

Available parsers include ones that can deal with DER-encoded X.509, DER-encoded PKCS#8 and DER-encoded TPM-wrapped blobs.

Public and private keys

These are the cryptographic components of the key pair. The public half should always be available, but the private half might not be. What operations are available can be queried, as can the size of the key. The key material may or may not actually reside in the kernel.

Identifiers

In addition to the normal key description (which can be generated by the parser), a number of supplementary identifiers may be available that can be searched for. These may be obtained, for example, by hashing the public key material or from the subjectKeyIdentifier in an X.509 certificate.

Identifier-based searches are selected by passing as the description to keyctl_search() a string constructed of hex characters prefixed with either "id:" or "ex:". The "id:" prefix indicates that a partial tail match is permissible whereas "ex:" requires an exact match on the full string. The hex characters indicate the data to match.

Subtype

This is the driver inside the kernel that accesses the key material and performs operations on it. It might be entirely software-based or it may offload the operations to a hardware key store, such as a TPM.

Note that expiry times from the payload are ignored as these patches may be used during boot before the system clock is set.

## PARSERS
The asymmetric key parsers can handle keys in a number of forms:

X.509

DER-encoded X.509 certificates can be accepted. Two identifiers are constructed: one from from the certificate issuer and serial number and the other from the subjectKeyIdentifier, if present. If left blank, the key description will be filled in from the subject field plus either the subjectKeyIdentifier or the serialNumber. Only the public key is filled in and only the encrypt and verify operations are supported.

The signature on the X.509 certificate may be checked by the keyring it is being added to and it may also be rejected if the key is blacklisted.

PKCS#8

Unencrypted DER-encoded PKCS#8 key data containers can be accepted. Currently no identifiers are constructed. The private key and the public key are loaded from the PKCS#8 blobs. Encrypted PKCS#8 is not currently supported.

TPM-Wrapped keys

DER-encoded TPM-wrapped TSS key blobs can be accepted. Currently no identifiers are constructed. The public key is extracted from the blob but the private key is expected to be resident in the TPM. Encryption and signature verification is done in software, but decryption and signing are offloaded to the TPM so as not to expose the private key.

This parser only supports TPM-1.2 wrappings and enc=pkcs1 encoding type. It also uses a hard-coded null SRK password; password-protected SRKs are not yet supported.

## USERSPACE API
In addition to the standard keyutils library functions, such as keyctl_update(), there are five calls specific to the asymmetric key type (though they are open to being used by other key types also):

keyctl_pkey_query()

keyctl_pkey_encrypt()

keyctl_pkey_decrypt()

keyctl_pkey_sign()

keyctl_pkey_verify()

The query function can be used to retrieve information about an asymmetric key, such as the key size, the amount of space required by buffers for the other operations and which operations are actually supported.

The other operations form two pairs: encrypt/decrypt and create/verify signature. Not all of these operations will necessarily be available; typically, encrypt and verify only require the public key to be available whereas decrypt and sign require the private key as well.

All of these operations take an information string parameter that supplies additional information such as encoding type/form and the password(s) needed to unlock/unwrap the key. This takes the form of a comma-separated list of "key[=value]" pairs, the exact set of which depends on the subtype driver used by a particular key.

Available parameters include:

enc=<type>

The encoding type for use in an encrypted blob or a signature. An example might be "enc=pkcs1".

hash=<name>

The name of the hash algorithm that was used to digest the data to be signed. Note that this is only used to construct any encoding that is used in a signature. The data to be signed or verified must have been parsed by the caller and the hash passed to keyctl_pkey_sign() or keyctl_pkey_verify() beforehand. An example might be "hash=sha256".

Note that not all parameters are used by all subtypes.

## RESTRICTED KEYRINGS
An additional keyutils function, keyctl_restrict_keyring(), can be used to gate a keyring so that a new key can only be added to the affected keyring if (a) it's an asymmetric key, (b) it's validly signed by a key in some appropriate keyring and (c) it's not blacklisted.

```
 keyctl_restrict_keyring(keyring, "asymmetric",

                         "key_or_keyring:<signing-key>[:chain]");
```

Where <signing-key> is the ID of a key or a ring of keys that act as the authority to permit a new key to be added to the keyring. The chain flag indicates that keys that have been added to the keyring may also be used to verify new keys. Authorising keys must themselves be asymmetric-type keys that can be used to do a signature verification on the key being added.

Note that there are various system keyrings visible to the root user that may permit additional keys to be added. These are typically gated by keys that already exist, preventing unauthorised keys from being used for such things as module verification.

## BLACKLISTING
When the attempt is made to add a key to the kernel, a hash of the public key is checked against the blacklist. This is a system keyring named .blacklist and contains keys of type blacklist. If the blacklist contains a key whose description matches the hash of the new key, that new key will be rejected with error EKEYREJECTED.

The blacklist keyring may be loaded from multiple sources, including a list compiled into the kernel and the UEFI dbx variable. Further hashes may also be blacklisted by the administrator. Note that blacklisting is not retroactive, so an asymmetric key that is already on the system cannot be blacklisted by adding a matching blacklist entry later.

## VERSIONS
The asymmetric key type first appeared in v3.7 of the Linux kernel, the restriction function in v4.11 and the public key operations in v4.20.

## SEE ALSO
keyctl(1), add_key(2), keyctl(3), keyctl_pkey_encrypt(3), keyctl_pkey_query(3), keyctl_pkey_sign(3), keyrings(7), keyutils(7)