From 387b74f15929efbdce79a6fbf12448f90bb83766 Mon Sep 17 00:00:00 2001 From: Gunnar Wrobel Date: Tue, 11 Sep 2007 05:53:25 +0000 Subject: Import layman. --- doc/.svn.ignore | 3 + doc/Makefile | 41 ++++ doc/layman.8.xml | 601 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 645 insertions(+) create mode 100644 doc/.svn.ignore create mode 100644 doc/Makefile create mode 100644 doc/layman.8.xml (limited to 'doc') diff --git a/doc/.svn.ignore b/doc/.svn.ignore new file mode 100644 index 0000000..ff0e9f9 --- /dev/null +++ b/doc/.svn.ignore @@ -0,0 +1,3 @@ +*.html +*.8 +semantic.cache diff --git a/doc/Makefile b/doc/Makefile new file mode 100644 index 0000000..64b28af --- /dev/null +++ b/doc/Makefile @@ -0,0 +1,41 @@ +# +# layman/doc/Makefile +# Simple Makefile to rebuild the documentation from the +# docbook XML sources +# +# Copyright (c) 1999-2005 Gentoo Foundation +# Released under v2 of the GNU GPL +# +# Author(s) Stuart Herbert +# Renat Lumpau +# Gunnar Wrobel +# +# ======================================================================== + +MAN_PAGES = layman.8 +HTML_PAGES = layman.8.html + +TMPFILE=./layman.man + +all: man html + +html: $(HTML_PAGES) + +man: $(MAN_PAGES) + +clean: + rm -f $(MAN_PAGES) + rm -f $(HTML_PAGES) + +%.html: %.xml + @echo HTML $@ + @xmlto html-nochunks $< + +%: %.xml + @echo MAN $@ + @xmlto man $< +# +# fix up the blank lines that docbook leaves behind +# + @cat $@ | sed -e 's/$$/.fred/g;' | tr -d '\n' | sed -e 's/.fred.fred\./.fred./g;' | sed -e 's/.fred/\n/g;' > $(TMPFILE) + @mv $(TMPFILE) $@ diff --git a/doc/layman.8.xml b/doc/layman.8.xml new file mode 100644 index 0000000..c966786 --- /dev/null +++ b/doc/layman.8.xml @@ -0,0 +1,601 @@ + + +
+ + + layman + + + + Gunnar + Wrobel + +
+ wrobel@gentoo.org + + + +
+ + + + + + 2006 + Gunnar Wrobel + + + +
+ Reference + + + + layman + February 2006 + Gentoo Linux + + + layman + 8 + + + layman + + manage your local repository of gentoo overlays + + + + + + layman + + -a + --add + + + ALL + overlay + + + + + layman + + -d + --delete + + + ALL + overlay + + + + + layman + + -s + --sync + + + ALL + overlay + + + + + layman + + -S + --sync-all + + + + + layman + + -L + --list + + + + + layman + + -l + --list-local + + + + + layman + + -f + --fetch + + + + + layman + + -n + --nofetch + + + + + layman + + -k + --nocheck + + + + + layman + + -q + --quiet + + + + + layman + + -Q + --quietness + + 0-4 + + + + + + + + Description + + layman is a script that allows you to + add, remove and update gentoo overlays from a variety of + sources. + + + + + WARNING + + layman makes it easy to retrieve and + update overlays for gentoo. In addition it makes it TRIVIAL + to break your system. + + + The main portage tree provides you with high quality ebuilds + that are all maintained by gentoo developers. This will not + be the case for most of the overlays you can get by using + layman. Thus you are removing the + security shield that the standard tree provides for + you. You should keep that in mind when installing ebuilds + from an overlay. + + + To ensure the security of your system you MUST read the + source of the ebuild you are about to install. + + + + + + + Handling overlays + + layman intends to provide easy + maintenance of gentoo overlays while not requiring any + configuration. + + + + + Remote overlay lists + + layman allows you to fetch an overlay + without the need to modify any configuration files. In + order for this to be possible the script needs an external + list of possible overlay sources. There will be a + centralized list available here, + but nothing will prevent you from using or publishing your + own list of overlays. The location of the remote lists can + also be modified using the option + when running layman. + + + To get a new overlay added to the central list provided + for layman, send a mail to + overlays@gentoo.org. Gentoo developers may + add their overlay entries directly into the list which can + be accessed over the CVS repository for the Gentoo + website. + + + You can also use several lists at the same time. Just + add one url per line to the overlays variable in your + configuration file. layman will merge the + contents of all lists. + + + layman also allows you to define + local files in this list. Just make sure you prepend these + pathnames in standard URL notation + with file://. + + + If you need to use a proxy for access to the internet, + you can use the corresponding variable in + the layman configuration file. Layman + will also respect the http_proxy + environment variable in case you set it. + + + + + + + Local cache + + layman stores a local copy of the + fetched remote list. It will be stored in + /usr/portage/local/layman/cache.xml + by default. There exists only one such cache file and it + will be overwritten every time you + run layman. + + + + + + + Handling <filename>/etc/make.conf</filename> + + Since layman is designed to + automatically handle the inclusion of overlays into your + system it needs to be able to modify + the PORTDIR_OVERLAY variable in your + /etc/make.conf file. But + /etc/make.conf is a very central and + essential configuration file for a gentoo + system. Automatically modifying this file would be + somewhat dangerous. You can + allow layman to do this by setting + the make_conf variable in the + configuration file to /etc/make.conf. + + + A much safer and in fact recommended solution to the + problem is to let layman handle an + external file that only contains + the PORTDIR_OVERLAY variable and is + sourced within the + standard /etc/make.conf file. Just add the following line to the end of your + /etc/make.conf file: + + + source /usr/portage/local/layman/make.conf + + /usr/portage/local/layman/make.conf + is the default provided in the layman + configuration. Change this filename in case you decide to + store it somewhere else. + + + The file does not necessarily need to exist at the + beginning. If it is missing, layman will create it for you. + + + There is also no need to remove the + original PORTDIR_OVERLAY variable from + the make.conf file. Layman will simply add new overlays to + this variable and all your old entries will remain in there. + + + + + + + Adding, removing and updating overlays + + Once a remote list of overlays has been fetched, + layman allows to add overlays from the + remote list to your system. The script will try to fetch + the overlay. If this is successful the overlay information + will be copied from the cache to the list of locally + installed overlays. In addition + layman will modify the + PORTDIR_OVERLAY variable to include the + new overlay path. + + + Removing the overlay with layman will + delete the overlay without leaving any traces behind. + + + In order to update all overlays managed by + layman you can run the script with the + option or + the flag. + + + + + + + List overlays + + layman provides the + and + options to print a list of available respectively + installed overlays. + + + Listing will prepend all fully supported overlays + with a green asterisk, all non-official overlays with a + yellow asterisk and all overlays that you will not be able + to use since you do not have the necessary tools installed + with a red asterisk. + + + In the default mode layman will be strict about + listing overlays and only present you with overlays that + are fully supported. In addition it will complain about + overlays that are missing a description field or a contact + attribute. This type of behaviour has been added with + layman-1.0.7 and if you'd like to return to the old + behaviour you may use the k option flag or set the nocheck + option in the configuration file. + + + + + + + Overlay types + + Currently layman supports overlays that + are exported via rsync, + subversion, bzr, + darcs, git, + mercurial or provided + as tar packages. + + + + + + + + + Actions + + List of possible layman actions. + + + + + + + Fetches the remote list of overlays. You will + usually NOT need to explicitely specify this option. The + fetch operation will be performed automatically once you + run the sync, sync-all, or list action. You can prevent + this automatic fetching using the --nofetch option. + + + + + overlay + overlay + + Add the given overlay from the cached remote list to + your locally installed overlays. Specify "ALL" to add + all overlays from the remote list. + + + + + overlay + overlay + + Remove the given overlay from your locally installed + overlays. Specify "ALL" to remove all overlays + + + + + overlay + overlay + + Update the specified overlay. Use "ALL" as + parameter to synchronize all overlays + + + + + + + + Update all overlays. Shortcut for -s ALL. + + + + + + + + List the contents of the remote list. + + + + + + + + List the locally installed overlays. + + + + + + + + + Options + + List of available layman options. + + + + + path + path + + Path to an alternative configuration file. + + + + + url + url + + Specifies the location of additional overlay + lists. You can use this flag several times and the + specified urls will get appended to the list of urls you + specified in your config file. You may also specify + local file urls by prepending the path with + file:// + + + + + + + + Prevents layman from + automatically fetching the remote lists of overlays. The + default behaviour for layman is to + update all remote lists if you run the sync, list or + fetch operation. + + + + + + + + Prevents layman from checking + the remote lists of overlays for complete overlay + definitions. The default behaviour for layman is to + reject overlays that do not provide a description or a + contact attribute. + + + + + + + + Makes layman completely quiet. + This option is dangerous: If the processes spawned by + layman when adding or synchronizing overlays require + any input layman will hang without telling you + why. This might happen for example if your overlay + resides in subversion and the SSL certificate of + the server needs acceptance. + + + + + LEVEL + LEVEL + + Makes layman less verbose. + Choose a value between 0 and 4 with 0 being completely + quiet. Once you set this below 3, the same warning as + given for --quiet applies. + + + + + LEVEL + LEVEL + + Use this option in combination with + the --add. It will modify the + priority of the added overlay and thus influence the + order of entries in the make.conf file. The lower the + priority, the earlier in the list the entry will be + mentioned. Use a value between 0 and 100. The default + value is 50. + + + + + + + + + + Examples + + + + Installing an overlay + + layman -f -a wrobel + This would add the overlay with the id + wrobel to your list of installed + overlays. + + + + + + Syncing your overlays + + layman -s ALL + This updates all overlays + + + + + + Performing several actions at the same time + + layman -f -a wrobel -a webapps-experimental + This fetches the remote list and immediately adds two + overlays + + + + + + + + Files + + + + + /etc/layman/layman.cfg + + Configuration file, holding the defaults for + layman + + + + + + + + +
+
-- cgit v1.2.3-1-g7c22