kumquat-buildroot/docs/manual/makedev-syntax.txt

104 lines
3.1 KiB
Plaintext
Raw Normal View History

// -*- mode:doc; -*-
// vim: set syntax=asciidoc:
[[makedev-syntax]]
manual: use one-line titles instead of two-line titles (trivial) Asciidoc supports two syntaxes for section titles: two-line titles (title plus underline consisting of a particular symbol), and one-line titles (title prefixed with a specific number of = signs). The two-line title underlines are: Level 0 (top level): ====================== Level 1: ---------------------- Level 2: ~~~~~~~~~~~~~~~~~~~~~~ Level 3: ^^^^^^^^^^^^^^^^^^^^^^ Level 4 (bottom level): ++++++++++++++++++++++ and the one-line title prefixes: = Document Title (level 0) = == Section title (level 1) == === Section title (level 2) === ==== Section title (level 3) ==== ===== Section title (level 4) ===== The buildroot manual is currenly using the two-line titles, but this has multiple disadvantages: - asciidoc also uses some of the underline symbols for other purposes (like preformatted code, example blocks, ...), which makes it difficult to do mass replacements, such as a planned follow-up patch that needs to move all sections one level down. - it is difficult to remember which level a given underline symbol (=-~^+) corresponds to, while counting = signs is easy. This patch changes all two-level titles to one-level titles in the manual. The bulk of the change was done with the following Python script, except for the level 1 titles (-----) as these underlines are also used for literal code blocks. This patch only changes the titles, no other changes. In adding-packages-directory.txt, I did add missing newlines between some titles and their content. ---------------------------------------------------------------------------- #!/usr/bin/env python import sys import mmap import re for input in sys.argv[1:]: f = open(input, 'r+') f.flush() s = mmap.mmap(f.fileno(), 0) # Level 0 (top level): ====================== = # Level 1: ---------------------- == # Level 2: ~~~~~~~~~~~~~~~~~~~~~~ === # Level 3: ^^^^^^^^^^^^^^^^^^^^^^ ==== # Level 4 (bottom level): ++++++++++++++++++++++ ===== def replace_title(s, symbol, replacement): pattern = re.compile(r'(.+\n)\%s{2,}\n' % symbol, re.MULTILINE) return pattern.sub(r'%s \1' % replacement, s) new = s new = replace_title(new, '=', '=') new = replace_title(new, '+', '=====') new = replace_title(new, '^', '====') new = replace_title(new, '~', '===') #new = replace_title(new, '-', '==') s.seek(0) s.write(new) s.resize(s.tell()) s.close() f.close() ---------------------------------------------------------------------------- Signed-off-by: Thomas De Schampheleire <thomas.de.schampheleire@gmail.com> Signed-off-by: Peter Korsgaard <peter@korsgaard.com>
2014-05-02 07:47:30 +02:00
== Makedev syntax documentation
The makedev syntax is used in several places in Buildroot to
define changes to be made for permissions, or which device files to
create and how to create them, in order to avoid calls to mknod.
This syntax is derived from the makedev utility, and more complete
documentation can be found in the +package/makedevs/README+ file.
It takes the form of a space separated list of fields, one file per
line; the fields are:
|===========================================================
|name |type |mode |uid |gid |major |minor |start |inc |count
|===========================================================
There are a few non-trivial blocks:
- +name+ is the path to the file you want to create/modify
- +type+ is the type of the file, being one of:
* f: a regular file
* d: a directory
* r: a directory recursively
* c: a character device file
* b: a block device file
* p: a named pipe
- +mode+ are the usual permissions settings (only numerical values
are allowed)
- +uid+ and +gid+ are the UID and GID to set on this file; can be
either numerical values or actual names
- +major+ and +minor+ are here for device files, set to +-+ for other
files
- +start+, +inc+ and +count+ are for when you want to create a batch
of files, and can be reduced to a loop, beginning at +start+,
incrementing its counter by +inc+ until it reaches +count+
Let's say you want to change the permissions of a given file; using
this syntax, you will need to write:
----
/usr/bin/foo f 755 0 0 - - - - -
/usr/bin/bar f 755 root root - - - - -
/data/buz f 644 buz-user buz-group - - - - -
----
Alternatively, if you want to change owner/permission of a directory
recursively, you can write (to set UID to foo, GID to bar and access
rights to rwxr-x--- for the directory /usr/share/myapp and all files
and directories below it):
----
/usr/share/myapp r 750 foo bar - - - - -
----
On the other hand, if you want to create the device file +/dev/hda+
and the corresponding 15 files for the partitions, you will need for
+/dev/hda+:
----
/dev/hda b 640 root root 3 0 0 0 -
----
and then for device files corresponding to the partitions of
+/dev/hda+, +/dev/hdaX+, +X+ ranging from 1 to 15:
----
/dev/hda b 640 root root 3 1 1 1 15
----
Extended attributes are supported if
+BR2_ROOTFS_DEVICE_TABLE_SUPPORTS_EXTENDED_ATTRIBUTES+ is enabled.
This is done by adding a line starting with +|xattr+ after
the line describing the file. Right now, only capability
is supported as extended attribute.
|=====================
| \|xattr | capability
|=====================
- +|xattr+ is a "flag" that indicate an extended attribute
- +capability+ is a capability to add to the previous file
If you want to add the capability cap_sys_admin to the binary foo,
you will write :
----
/usr/bin/foo f 755 root root - - - - -
|xattr cap_sys_admin+eip
----
You can add several capabilities to a file by using several +|xattr+ lines.
If you want to add the capability cap_sys_admin and cap_net_admin to the
binary foo, you will write :
----
/usr/bin/foo f 755 root root - - - - -
|xattr cap_sys_admin+eip
|xattr cap_net_admin+eip
----