From 93f9a2080a5e4be3bdb225e170e754c6a7b9143a Mon Sep 17 00:00:00 2001 From: Michael Shigorin Date: Mon, 8 Feb 2016 20:07:56 +0300 Subject: [PATCH] doc: added mkimage-profiles(7) This initial page might lack a lot, don't be shy to blame me! (thanks ldv@ for having skimmed it through though) --- doc/Makefile | 11 ++- doc/mkimage-profiles.7.in | 141 ++++++++++++++++++++++++++++++++++++++ 2 files changed, 150 insertions(+), 2 deletions(-) create mode 100644 doc/mkimage-profiles.7.in diff --git a/doc/Makefile b/doc/Makefile index d518c8f9..0248ef34 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -28,14 +28,14 @@ HTML_ARGS = -a data-uri --icons -r $(RESOURCE_FILES) -r . \ --xsltproc-opts='$(XSLT_ARGS)' $(COMMON_ARGS) # most convenient deliverables -DOCS_OUT = $(PROJECT).pdf $(PROJECT).html docbook-xsl.css +DOCS_OUT = mkimage-profiles.7 $(PROJECT).pdf $(PROJECT).html docbook-xsl.css # intermediate files DOCS_TMP = $(PROJECT).fo $(PROJECT).xml .PHONY: all prep chunked xhtml pdf clean -all: chunked xhtml pdf +all: man chunked xhtml pdf # NB: destination defined externally publish: all @@ -46,6 +46,13 @@ publish: all prep: @if [ -n "$(BUILDDIR)" ]; then mkdir -p "$(BUILDDIR)"; fi +man: + @VERSION="$$(sed -rn 's/^Version: ([0-9.]+).*$$/\1/p' \ + ../.gear/mkimage-profiles.spec)"; \ + sed -e "s,@VERSION@,$$VERSION,g" \ + < mkimage-profiles.7.in \ + > mkimage-profiles.7 + chunked xhtml: prep @echo "** building $@ book" @$(A2X) -f $@ $(HTML_ARGS) diff --git a/doc/mkimage-profiles.7.in b/doc/mkimage-profiles.7.in new file mode 100644 index 00000000..5a2154fc --- /dev/null +++ b/doc/mkimage-profiles.7.in @@ -0,0 +1,141 @@ +.\" Copyright (C) 2010-2016 Michael Shigorin +.\" +.\" Documentation for mkimage-profiles project. +.\" +.\" This file is free software; you can redistribute it and/or modify +.\" it under the terms of the GNU General Public License as published by +.\" the Free Software Foundation; either version 2 of the License, or +.\" (at your option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public License +.\" along with this program; if not, write to the Free Software +.\" Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301, USA. +.\" +.TH "MKIMAGE-PROFILES" "7" "February 2016" "mkimage-profiles @VERSION@" "ALT Linux" +.SH "NAME" +mkimage-profiles \- ALT Linux distribution family metaprofile +.SH "SYNOPSIS" +.B make +.IR "" [ options ] +.I "" [ ... ] +.SH "DESCRIPTION" +.BR mkimage-profiles +builds operating environment images based on ALT Linux package repositories. + +Run +.BR make\ help +to obtain list of available goals. +.SH "PREREQUISITES" +mkimage-profiles only needs +.BR make(1) +and +.BR rsync(1) +to generate the build profile; +.BR mkimage +is used to actually run the build (which involves +.BR hasher(7) +quite a few times). + +.BR git(1) +will be used if available so that the generated profile is an annotated +git repository; +.BR graphviz(1) +can be used to obtain build dependency graphs. +.SH "RATIONALE" +Long time ago when Linux distribution images were worked upon by hand +there was little need for generalization and sharing the common base. + +Building several "generic" ALT Linux distros in a team and maintaining +their educational flavours at the same time proved the need to be able +to describe what's common and what's different in a way that doesn't +resemble more or less complete forks. + +Enter mkimage-profiles: choose what's closest to your dream image +and add what's missing, or roll on your own using the rich library +of existing parts and bits. +.SH "REQUIREMENTS" +The next-generation image build system for ALT Linux must: +.TP +1. +provide reasonable means to describe common/differing aspects within +image families; +.TP +2. +ensure reproducible build results; +.TP +3. +support distribution family maintenance workflows +observed in the wild (e.g., with +.BR mkimage-profiles-desktop +or earlier); +.TP +4. +help out with diagnosing build problems. +.SH "ARCHITECTURE" +.BR mkimage-profiles +implements four steps to achieve the above goals: +.TP +1. +initialize the off-tree mkimage profile (BUILDDIR); +.TP +2. +build up distribution's configuration there; +.TP +3. +copy over the needed subprofiles/features/lists/groups; +.TP +4. +build the ISO/VE/VM image. +.PP +This results in a compact "as-needed" style per-image profile that can +be actually studied in a short amount of time and might get included +into the generated image as a tarball for better reproducibility. +.SH "EXAMPLES" +.BR make\ syslinux.iso +should result in a minimal bootable ISO image. + +Another example is Regular Builds project yielding weekly images: +.BR http://en.altlinux.org/regular +.SH "AUTHOR" +Written by Michael Shigorin +.SH "REPORTING BUGS" +Report bugs to http://bugzilla.altlinux.org +.br +(Sisyphus project, mkimage-profiles component). +.SH "COPYRIGHT" +Copyright \(co) 2010-2016 Michael Shigorin +.br +This is free software; see the source for copying conditions. +There is NO WARRANTY; not even for MERCHANTABILITY or +FITNESS FOR A PARTICULAR PURPOSE. +.SH "FURTHER READING" +First and foremost: +.BR /usr/share/mkimage-profiles/QUICKSTART + +Please refer to +.BR README +files in the tree starting with the toplevel one for more +information; these can be assembled into a handbook using +.BR asciidoc(1) +(available at +.BR http://nightly.altlinux.org/docs/ +as weekly HTML/PDF updates). + +Specific topics are covered within +.BR doc/ +subdirectory; e.g. +.BR make +options are described in +.BR doc/params.txt +file. +.SH "SEE ALSO" +.br +.BR hsh(1), +.BR mkimage, +.br +.BR http://www.vimeo.com/23522095