diff --git a/Makefile b/Makefile new file mode 100644 index 0000000..1a29d84 --- /dev/null +++ b/Makefile @@ -0,0 +1,7 @@ +.PHONY: all clean + +all: index.txt + asciidoc index.txt + +clean: + rm -f index.html diff --git a/classTextile.php b/classTextile.php deleted file mode 100644 index 4c6d30d..0000000 --- a/classTextile.php +++ /dev/null @@ -1,1135 +0,0 @@ -TextileThis($string); - * - */ - -/* -$Id: classTextile.php 216 2006-10-17 22:31:53Z zem $ -$LastChangedRevision: 216 $ -*/ - -/* - -_____________ -T E X T I L E - -A Humane Web Text Generator - -Version 2.0 - -Copyright (c) 2003-2004, Dean Allen -All rights reserved. - -Thanks to Carlo Zottmann for refactoring -Textile's procedural code into a class framework - -Additions and fixes Copyright (c) 2006 Alex Shiels http://thresholdstate.com/ - -_____________ -L I C E N S E - -Redistribution and use in source and binary forms, with or without -modification, are permitted provided that the following conditions are met: - -* Redistributions of source code must retain the above copyright notice, - this list of conditions and the following disclaimer. - -* Redistributions in binary form must reproduce the above copyright notice, - this list of conditions and the following disclaimer in the documentation - and/or other materials provided with the distribution. - -* Neither the name Textile nor the names of its contributors may be used to - endorse or promote products derived from this software without specific - prior written permission. - -THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" -AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE -IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE -ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE -LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR -CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF -SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS -INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN -CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) -ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE -POSSIBILITY OF SUCH DAMAGE. - -_________ -U S A G E - -Block modifier syntax: - - Header: h(1-6). - Paragraphs beginning with 'hn. ' (where n is 1-6) are wrapped in header tags. - Example: h1. Header... ->

Header...

- - Paragraph: p. (also applied by default) - Example: p. Text ->

Text

- - Blockquote: bq. - Example: bq. Block quotation... ->
Block quotation...
- - Blockquote with citation: bq.:http://citation.url - Example: bq.:http://textism.com/ Text... - ->
Text...
- - Footnote: fn(1-100). - Example: fn1. Footnote... ->

Footnote...

- - Numeric list: #, ## - Consecutive paragraphs beginning with # are wrapped in ordered list tags. - Example:
  1. ordered list
- - Bulleted list: *, ** - Consecutive paragraphs beginning with * are wrapped in unordered list tags. - Example: - -Phrase modifier syntax: - - _emphasis_ -> emphasis - __italic__ -> italic - *strong* -> strong - **bold** -> bold - ??citation?? -> citation - -deleted text- -> deleted - +inserted text+ -> inserted - ^superscript^ -> superscript - ~subscript~ -> subscript - @code@ -> computer code - %(bob)span% -> span - - ==notextile== -> leave text alone (do not format) - - "linktext":url -> linktext - "linktext(title)":url -> linktext - - !imageurl! -> - !imageurl(alt text)! -> alt text - !imageurl!:linkurl -> - -ABC(Always Be Closing) -> ABC - - -Table syntax: - - Simple tables: - - |a|simple|table|row| - |And|Another|table|row| - - |_. A|_. table|_. header|_.row| - |A|simple|table|row| - - Tables with attributes: - - table{border:1px solid black}. - {background:#ddd;color:red}. |{}| | | | - - -Applying Attributes: - - Most anywhere Textile code is used, attributes such as arbitrary css style, - css classes, and ids can be applied. The syntax is fairly consistent. - - The following characters quickly alter the alignment of block elements: - - < -> left align ex. p<. left-aligned para - > -> right align h3>. right-aligned header 3 - = -> centred h4=. centred header 4 - <> -> justified p<>. justified paragraph - - These will change vertical alignment in table cells: - - ^ -> top ex. |^. top-aligned table cell| - - -> middle |-. middle aligned| - ~ -> bottom |~. bottom aligned cell| - - Plain (parentheses) inserted between block syntax and the closing dot-space - indicate classes and ids: - - p(hector). paragraph ->

paragraph

- - p(#fluid). paragraph ->

paragraph

- - (classes and ids can be combined) - p(hector#fluid). paragraph ->

paragraph

- - Curly {brackets} insert arbitrary css style - - p{line-height:18px}. paragraph ->

paragraph

- - h3{color:red}. header 3 ->

header 3

- - Square [brackets] insert language attributes - - p[no]. paragraph ->

paragraph

- - %[fr]phrase% -> phrase - - Usually Textile block element syntax requires a dot and space before the block - begins, but since lists don't, they can be styled just using braces - - #{color:blue} one ->
    - # big
  1. one
    2. - # list
  2. big
    3. -
  3. list
    4. -
- - Using the span tag to style a phrase - - It goes like this, %{color:red}the fourth the fifth% - -> It goes like this, the fourth the fifth - -*/ - -// define these before including this file to override the standard glyphs -@define('txt_quote_single_open', '‘'); -@define('txt_quote_single_close', '’'); -@define('txt_quote_double_open', '“'); -@define('txt_quote_double_close', '”'); -@define('txt_apostrophe', '’'); -@define('txt_prime', '′'); -@define('txt_prime_double', '″'); -@define('txt_ellipsis', '…'); -@define('txt_emdash', '—'); -@define('txt_endash', '–'); -@define('txt_dimension', '×'); -@define('txt_trademark', '™'); -@define('txt_registered', '®'); -@define('txt_copyright', '©'); - -class Textile -{ - var $hlgn; - var $vlgn; - var $clas; - var $lnge; - var $styl; - var $cspn; - var $rspn; - var $a; - var $s; - var $c; - var $pnct; - var $rel; - var $fn; - - var $shelf = array(); - var $restricted = false; - var $noimage = false; - var $lite = false; - var $url_schemes = array(); - var $glyph = array(); - var $hu = ''; - - var $ver = '2.0.0'; - var $rev = '$Rev: 216 $'; - -// ------------------------------------------------------------- - function Textile() - { - $this->hlgn = "(?:\<(?!>)|(?|\<\>|\=|[()]+(?! ))"; - $this->vlgn = "[\-^~]"; - $this->clas = "(?:\([^)]+\))"; - $this->lnge = "(?:\[[^]]+\])"; - $this->styl = "(?:\{[^}]+\})"; - $this->cspn = "(?:\\\\\d+)"; - $this->rspn = "(?:\/\d+)"; - $this->a = "(?:{$this->hlgn}|{$this->vlgn})*"; - $this->s = "(?:{$this->cspn}|{$this->rspn})*"; - $this->c = "(?:{$this->clas}|{$this->styl}|{$this->lnge}|{$this->hlgn})*"; - - $this->pnct = '[\!"#\$%&\'()\*\+,\-\./:;<=>\?@\[\\\]\^_`{\|}\~]'; - $this->urlch = '[\w"$\-_.+!*\'(),";\/?:@=&%#{}|\\^~\[\]`]'; - - $this->url_schemes = array('http','https','ftp','mailto'); - - $this->btag = array('bq', 'bc', 'notextile', 'pre', 'h[1-6]', 'fn\d+', 'p'); - - $this->glyph = array( - 'quote_single_open' => txt_quote_single_open, - 'quote_single_close' => txt_quote_single_close, - 'quote_double_open' => txt_quote_double_open, - 'quote_double_close' => txt_quote_double_close, - 'apostrophe' => txt_apostrophe, - 'prime' => txt_prime, - 'prime_double' => txt_prime_double, - 'ellipsis' => txt_ellipsis, - 'emdash' => txt_emdash, - 'endash' => txt_endash, - 'dimension' => txt_dimension, - 'trademark' => txt_trademark, - 'registered' => txt_registered, - 'copyright' => txt_copyright, - ); - - if (defined('hu')) - $this->hu = hu; - - } - -// ------------------------------------------------------------- - function TextileThis($text, $lite='', $encode='', $noimage='', $strict='', $rel='') - { - if ($rel) - $this->rel = ' rel="'.$rel.'" '; - $this->lite = $lite; - $this->noimage = $noimage; - - if ($encode) { - $text = $this->incomingEntities($text); - $text = str_replace("x%x%", "&", $text); - return $text; - } else { - - if(!$strict) { - $text = $this->cleanWhiteSpace($text); - } - - $text = $this->getRefs($text); - - if (!$lite) { - $text = $this->block($text); - } - - $text = $this->retrieve($text); - - // just to be tidy - $text = str_replace("
", "
\n", $text); - - return $text; - } - } - -// ------------------------------------------------------------- - function TextileRestricted($text, $lite=1, $noimage=1, $rel='nofollow') - { - $this->restricted = true; - $this->lite = $lite; - $this->noimage = $noimage; - if ($rel) - $this->rel = ' rel="'.$rel.'" '; - - // escape any raw html - $text = $this->encode_html($text, 0); - - $text = $this->cleanWhiteSpace($text); - $text = $this->getRefs($text); - - if ($lite) { - $text = $this->blockLite($text); - } - else { - $text = $this->block($text); - } - - $text = $this->retrieve($text); - - // just to be tidy - $text = str_replace("
", "
\n", $text); - - return $text; - } - -// ------------------------------------------------------------- - function pba($in, $element = "") // "parse block attributes" - { - $style = ''; - $class = ''; - $lang = ''; - $colspan = ''; - $rowspan = ''; - $id = ''; - $atts = ''; - - if (!empty($in)) { - $matched = $in; - if ($element == 'td') { - if (preg_match("/\\\\(\d+)/", $matched, $csp)) $colspan = $csp[1]; - if (preg_match("/\/(\d+)/", $matched, $rsp)) $rowspan = $rsp[1]; - } - - if ($element == 'td' or $element == 'tr') { - if (preg_match("/($this->vlgn)/", $matched, $vert)) - $style[] = "vertical-align:" . $this->vAlign($vert[1]) . ";"; - } - - if (preg_match("/\{([^}]*)\}/", $matched, $sty)) { - $style[] = rtrim($sty[1], ';') . ';'; - $matched = str_replace($sty[0], '', $matched); - } - - if (preg_match("/\[([^]]+)\]/U", $matched, $lng)) { - $lang = $lng[1]; - $matched = str_replace($lng[0], '', $matched); - } - - if (preg_match("/\(([^()]+)\)/U", $matched, $cls)) { - $class = $cls[1]; - $matched = str_replace($cls[0], '', $matched); - } - - if (preg_match("/([(]+)/", $matched, $pl)) { - $style[] = "padding-left:" . strlen($pl[1]) . "em;"; - $matched = str_replace($pl[0], '', $matched); - } - - if (preg_match("/([)]+)/", $matched, $pr)) { - // $this->dump($pr); - $style[] = "padding-right:" . strlen($pr[1]) . "em;"; - $matched = str_replace($pr[0], '', $matched); - } - - if (preg_match("/($this->hlgn)/", $matched, $horiz)) - $style[] = "text-align:" . $this->hAlign($horiz[1]) . ";"; - - if (preg_match("/^(.*)#(.*)$/", $class, $ids)) { - $id = $ids[2]; - $class = $ids[1]; - } - - if ($this->restricted) - return ($lang) ? ' lang="' . $lang .'"':''; - - return join('',array( - ($style) ? ' style="' . join("", $style) .'"':'', - ($class) ? ' class="' . $class .'"':'', - ($lang) ? ' lang="' . $lang .'"':'', - ($id) ? ' id="' . $id .'"':'', - ($colspan) ? ' colspan="' . $colspan .'"':'', - ($rowspan) ? ' rowspan="' . $rowspan .'"':'' - )); - } - return ''; - } - -// ------------------------------------------------------------- - function hasRawText($text) - { - // checks whether the text has text not already enclosed by a block tag - $r = trim(preg_replace('@<(p|blockquote|div|form|table|ul|ol|pre|h\d)[^>]*?>.*@s', '', trim($text))); - $r = trim(preg_replace('@<(hr|br)[^>]*?/>@', '', $r)); - return '' != $r; - } - -// ------------------------------------------------------------- - function table($text) - { - $text = $text . "\n\n"; - return preg_replace_callback("/^(?:table(_?{$this->s}{$this->a}{$this->c})\. ?\n)?^({$this->a}{$this->c}\.? ?\|.*\|)\n\n/smU", - array(&$this, "fTable"), $text); - } - -// ------------------------------------------------------------- - function fTable($matches) - { - $tatts = $this->pba($matches[1], 'table'); - - foreach(preg_split("/\|$/m", $matches[2], -1, PREG_SPLIT_NO_EMPTY) as $row) { - if (preg_match("/^($this->a$this->c\. )(.*)/m", ltrim($row), $rmtch)) { - $ratts = $this->pba($rmtch[1], 'tr'); - $row = $rmtch[2]; - } else $ratts = ''; - - $cells = array(); - foreach(explode("|", $row) as $cell) { - $ctyp = "d"; - if (preg_match("/^_/", $cell)) $ctyp = "h"; - if (preg_match("/^(_?$this->s$this->a$this->c\. )(.*)/", $cell, $cmtch)) { - $catts = $this->pba($cmtch[1], 'td'); - $cell = $cmtch[2]; - } else $catts = ''; - - $cell = $this->graf($this->span($cell)); - - if (trim($cell) != '') - $cells[] = "\t\t\t$cell"; - } - $rows[] = "\t\t\n" . join("\n", $cells) . ($cells ? "\n" : "") . "\t\t"; - unset($cells, $catts); - } - return "\t\n" . join("\n", $rows) . "\n\t\n\n"; - } - -// ------------------------------------------------------------- - function lists($text) - { - return preg_replace_callback("/^([#*]+$this->c .*)$(?![^#*])/smU", array(&$this, "fList"), $text); - } - -// ------------------------------------------------------------- - function fList($m) - { - $text = explode("\n", $m[0]); - foreach($text as $line) { - $nextline = next($text); - if (preg_match("/^([#*]+)($this->a$this->c) (.*)$/s", $line, $m)) { - list(, $tl, $atts, $content) = $m; - $nl = ''; - if (preg_match("/^([#*]+)\s.*/", $nextline, $nm)) - $nl = $nm[1]; - if (!isset($lists[$tl])) { - $lists[$tl] = true; - $atts = $this->pba($atts); - $line = "\t<" . $this->lT($tl) . "l$atts>\n\t\t
  • " . $this->graf($content); - } else { - $line = "\t\t
  • " . $this->graf($content); - } - - if(strlen($nl) <= strlen($tl)) $line .= "
    • "; - foreach(array_reverse($lists) as $k => $v) { - if(strlen($k) > strlen($nl)) { - $line .= "\n\tlT($k) . "l>"; - if(strlen($k) > 1) - $line .= ""; - unset($lists[$k]); - } - } - } - $out[] = $line; - } - return join("\n", $out); - } - -// ------------------------------------------------------------- - function lT($in) - { - return preg_match("/^#+/", $in) ? 'o' : 'u'; - } - -// ------------------------------------------------------------- - function doPBr($in) - { - return preg_replace_callback('@<(p)([^>]*?)>(.*)()@s', array(&$this, 'doBr'), $in); - } - -// ------------------------------------------------------------- - function doBr($m) - { - $content = preg_replace("@(.+)(?|
    )\n(?![#*\s|])@", '$1
    ', $m[3]); - return '<'.$m[1].$m[2].'>'.$content.$m[4]; - } - -// ------------------------------------------------------------- - function block($text) - { - $find = $this->btag; - $tre = join('|', $find); - - $text = explode("\n\n", $text); - - $tag = 'p'; - $atts = $cite = $graf = $ext = ''; - - foreach($text as $line) { - $anon = 0; - if (preg_match("/^($tre)($this->a$this->c)\.(\.?)(?::(\S+))? (.*)$/s", $line, $m)) { - // last block was extended, so close it - if ($ext) - $out[count($out)-1] .= $c1; - // new block - list(,$tag,$atts,$ext,$cite,$graf) = $m; - list($o1, $o2, $content, $c2, $c1) = $this->fBlock(array(0,$tag,$atts,$ext,$cite,$graf)); - - // leave off c1 if this block is extended, we'll close it at the start of the next block - if ($ext) - $line = $o1.$o2.$content.$c2; - else - $line = $o1.$o2.$content.$c2.$c1; - } - else { - // anonymous block - $anon = 1; - if ($ext or !preg_match('/^ /', $line)) { - list($o1, $o2, $content, $c2, $c1) = $this->fBlock(array(0,$tag,$atts,$ext,$cite,$line)); - // skip $o1/$c1 because this is part of a continuing extended block - if ($tag == 'p' and !$this->hasRawText($content)) { - $line = $content; - } - else { - $line = $o2.$content.$c2; - } - } - else { - $line = $this->graf($line); - } - } - - $line = $this->doPBr($line); - $line = preg_replace('/
    /', '
    ', $line); - - if ($ext and $anon) - $out[count($out)-1] .= "\n".$line; - else - $out[] = $line; - - if (!$ext) { - $tag = 'p'; - $atts = ''; - $cite = ''; - $graf = ''; - } - } - if ($ext) $out[count($out)-1] .= $c1; - return join("\n\n", $out); - } - - - -// ------------------------------------------------------------- - function fBlock($m) - { - // $this->dump($m); - list(, $tag, $atts, $ext, $cite, $content) = $m; - $atts = $this->pba($atts); - - $o1 = $o2 = $c2 = $c1 = ''; - - if (preg_match("/fn(\d+)/", $tag, $fns)) { - $tag = 'p'; - $fnid = empty($this->fn[$fns[1]]) ? $fns[1] : $this->fn[$fns[1]]; - $atts .= ' id="fn' . $fnid . '"'; - if (strpos($atts, 'class=') === false) - $atts .= ' class="footnote"'; - $content = '' . $fns[1] . ' ' . $content; - } - - if ($tag == "bq") { - $cite = $this->checkRefs($cite); - $cite = ($cite != '') ? ' cite="' . $cite . '"' : ''; - $o1 = "\t\n"; - $o2 = "\t\t"; - $c2 = "

    "; - $c1 = "\n\t"; - } - elseif ($tag == 'bc') { - $o1 = ""; - $o2 = ""; - $c2 = ""; - $c1 = ""; - $content = $this->shelve($this->encode_html(rtrim($content, "\n")."\n")); - } - elseif ($tag == 'notextile') { - $content = $this->shelve($content); - $o1 = $o2 = ''; - $c1 = $c2 = ''; - } - elseif ($tag == 'pre') { - $content = $this->shelve($this->encode_html(rtrim($content, "\n")."\n")); - $o1 = ""; - $o2 = $c2 = ''; - $c1 = ""; - } - else { - $o2 = "\t<$tag$atts>"; - $c2 = ""; - } - - $content = $this->graf($content); - - return array($o1, $o2, $content, $c2, $c1); - } - -// ------------------------------------------------------------- - function graf($text) - { - // handle normal paragraph text - if (!$this->lite) { - $text = $this->noTextile($text); - $text = $this->code($text); - } - - $text = $this->links($text); - if (!$this->noimage) - $text = $this->image($text); - - if (!$this->lite) { - $text = $this->lists($text); - $text = $this->table($text); - } - - $text = $this->span($text); - $text = $this->footnoteRef($text); - $text = $this->glyphs($text); - return rtrim($text, "\n"); - } - -// ------------------------------------------------------------- - function span($text) - { - $qtags = array('\*\*','\*','\?\?','-','__','_','%','\+','~','\^'); - $pnct = ".,\"'?!;:"; - - foreach($qtags as $f) { - $text = preg_replace_callback("/ - (?:^|(?<=[\s>$pnct])|([{[])) - ($f)(?!$f) - ({$this->c}) - (?::(\S+))? - ([^\s$f]+|\S[^$f\n]*[^\s$f\n]) - ([$pnct]*) - $f - (?:$|([\]}])|(?=[[:punct:]]{1,2}|\s)) - /x", array(&$this, "fSpan"), $text); - } - return $text; - } - -// ------------------------------------------------------------- - function fSpan($m) - { - $qtags = array( - '*' => 'strong', - '**' => 'b', - '??' => 'cite', - '_' => 'em', - '__' => 'i', - '-' => 'del', - '%' => 'span', - '+' => 'ins', - '~' => 'sub', - '^' => 'sup', - ); - - list(,, $tag, $atts, $cite, $content, $end) = $m; - $tag = $qtags[$tag]; - $atts = $this->pba($atts); - $atts .= ($cite != '') ? 'cite="' . $cite . '"' : ''; - - $out = "<$tag$atts>$content$end"; - -// $this->dump($out); - - return $out; - - } - -// ------------------------------------------------------------- - function links($text) - { - return preg_replace_callback('/ - (?:^|(?<=[\s>.$pnct\(])|([{[])) # $pre - " # start - (' . $this->c . ') # $atts - ([^"]+) # $text - \s? - (?:\(([^)]+)\)(?="))? # $title - ": - ('.$this->urlch.'+) # $url - (\/)? # $slash - ([^\w\/;]*) # $post - (?:([\]}])|(?=\s|$|\))) - /Ux', array(&$this, "fLink"), $text); - } - -// ------------------------------------------------------------- - function fLink($m) - { - list(, $pre, $atts, $text, $title, $url, $slash, $post) = $m; - - $url = $this->checkRefs($url); - - $atts = $this->pba($atts); - $atts .= ($title != '') ? ' title="' . $this->encode_html($title) . '"' : ''; - - if (!$this->noimage) - $text = $this->image($text); - - $text = $this->span($text); - $text = $this->glyphs($text); - - $url = $this->relURL($url); - - $out = 'rel . '>' . $text . '' . $post; - - // $this->dump($out); - return $this->shelve($out); - - } - -// ------------------------------------------------------------- - function getRefs($text) - { - return preg_replace_callback("/(?<=^|\s)\[(.+)\]((?:http:\/\/|\/)\S+)(?=\s|$)/U", - array(&$this, "refs"), $text); - } - -// ------------------------------------------------------------- - function refs($m) - { - list(, $flag, $url) = $m; - $this->urlrefs[$flag] = $url; - return ''; - } - -// ------------------------------------------------------------- - function checkRefs($text) - { - return (isset($this->urlrefs[$text])) ? $this->urlrefs[$text] : $text; - } - -// ------------------------------------------------------------- - function relURL($url) - { - $parts = parse_url($url); - if ((empty($parts['scheme']) or @$parts['scheme'] == 'http') and - empty($parts['host']) and - preg_match('/^\w/', @$parts['path'])) - $url = $this->hu.$url; - if ($this->restricted and !empty($parts['scheme']) and - !in_array($parts['scheme'], $this->url_schemes)) - return '#'; - return $url; - } - -// ------------------------------------------------------------- - function image($text) - { - return preg_replace_callback("/ - (?:[[{])? # pre - \! # opening ! - (\<|\=|\>)?? # optional alignment atts - ($this->c) # optional style,class atts - (?:\. )? # optional dot-space - ([^\s(!]+) # presume this is the src - \s? # optional space - (?:\(([^\)]+)\))? # optional title - \! # closing - (?::(\S+))? # optional href - (?:[\]}]|(?=\s|$)) # lookahead: space or end of string - /Ux", array(&$this, "fImage"), $text); - } - -// ------------------------------------------------------------- - function fImage($m) - { - list(, $algn, $atts, $url) = $m; - $atts = $this->pba($atts); - $atts .= ($algn != '') ? ' align="' . $this->iAlign($algn) . '"' : ''; - $atts .= (isset($m[4])) ? ' title="' . $m[4] . '"' : ''; - $atts .= (isset($m[4])) ? ' alt="' . $m[4] . '"' : ' alt=""'; - $size = @getimagesize($url); - if ($size) $atts .= " $size[3]"; - - $href = (isset($m[5])) ? $this->checkRefs($m[5]) : ''; - $url = $this->checkRefs($url); - - $url = $this->relURL($url); - - $out = array( - ($href) ? '' : '', - '', - ($href) ? '' : '' - ); - - return join('',$out); - } - -// ------------------------------------------------------------- - function code($text) - { - $text = $this->doSpecial($text, '', '', 'fCode'); - $text = $this->doSpecial($text, '@', '@', 'fCode'); - $text = $this->doSpecial($text, '
    ', '
    ', 'fPre'); - return $text; - } - -// ------------------------------------------------------------- - function fCode($m) - { - @list(, $before, $text, $after) = $m; - if ($this->restricted) - // $text is already escaped - return $before.$this->shelve(''.$text.'').$after; - else - return $before.$this->shelve(''.$this->encode_html($text).'').$after; - } - -// ------------------------------------------------------------- - function fPre($m) - { - @list(, $before, $text, $after) = $m; - if ($this->restricted) - // $text is already escaped - return $before.'
    '.$this->shelve($text).'
    '.$after; - else - return $before.'
    '.$this->shelve($this->encode_html($text)).'
    '.$after; - } -// ------------------------------------------------------------- - function shelve($val) - { - $i = uniqid(rand()); - $this->shelf[$i] = $val; - return $i; - } - -// ------------------------------------------------------------- - function retrieve($text) - { - if (is_array($this->shelf)) - do { - $old = $text; - $text = strtr($text, $this->shelf); - } while ($text != $old); - - return $text; - } - -// ------------------------------------------------------------- -// NOTE: deprecated - function incomingEntities($text) - { - return preg_replace("/&(?![#a-z0-9]+;)/i", "x%x%", $text); - } - -// ------------------------------------------------------------- -// NOTE: deprecated - function encodeEntities($text) - { - return (function_exists('mb_encode_numericentity')) - ? $this->encode_high($text) - : htmlentities($text, ENT_NOQUOTES, "utf-8"); - } - -// ------------------------------------------------------------- -// NOTE: deprecated - function fixEntities($text) - { - /* de-entify any remaining angle brackets or ampersands */ - return str_replace(array(">", "<", "&"), - array(">", "<", "&"), $text); - } - -// ------------------------------------------------------------- - function cleanWhiteSpace($text) - { - $out = str_replace("\r\n", "\n", $text); - $out = preg_replace("/\n{3,}/", "\n\n", $out); - $out = preg_replace("/\n *\n/", "\n\n", $out); - $out = preg_replace('/"$/', "\" ", $out); - return $out; - } - -// ------------------------------------------------------------- - function doSpecial($text, $start, $end, $method='fSpecial') - { - return preg_replace_callback('/(^|\s|[[({>])'.preg_quote($start, '/').'(.*?)'.preg_quote($end, '/').'(\s|$|[\])}])?/ms', - array(&$this, $method), $text); - } - -// ------------------------------------------------------------- - function fSpecial($m) - { - // A special block like notextile or code - @list(, $before, $text, $after) = $m; - return $before.$this->shelve($this->encode_html($text)).$after; - } - -// ------------------------------------------------------------- - function noTextile($text) - { - $text = $this->doSpecial($text, '', '', 'fTextile'); - return $this->doSpecial($text, '==', '==', 'fTextile'); - - } - -// ------------------------------------------------------------- - function fTextile($m) - { - @list(, $before, $notextile, $after) = $m; - #$notextile = str_replace(array_keys($modifiers), array_values($modifiers), $notextile); - return $before.$this->shelve($notextile).$after; - } - -// ------------------------------------------------------------- - function footnoteRef($text) - { - return preg_replace('/\b\[([0-9]+)\](\s)?/Ue', - '$this->footnoteID(\'\1\',\'\2\')', $text); - } - -// ------------------------------------------------------------- - function footnoteID($id, $t) - { - if (empty($this->fn[$id])) - $this->fn[$id] = uniqid(rand()); - $fnid = $this->fn[$id]; - return ''.$id.''.$t; - } - -// ------------------------------------------------------------- - function glyphs($text) - { - // fix: hackish - $text = preg_replace('/"\z/', "\" ", $text); - $pnc = '[[:punct:]]'; - - $glyph_search = array( - '/(\w)\'(\w)/', // apostrophe's - '/(\s)\'(\d+\w?)\b(?!\')/', // back in '88 - '/(\S)\'(?=\s|'.$pnc.'|<|$)/', // single closing - '/\'/', // single opening - '/(\S)\"(?=\s|'.$pnc.'|<|$)/', // double closing - '/"/', // double opening - '/\b([A-Z][A-Z0-9]{2,})\b(?:[(]([^)]*)[)])/', // 3+ uppercase acronym - '/\b([A-Z][A-Z\'\-]+[A-Z])(?=[\s.,\)>])/', // 3+ uppercase - '/\b( )?\.{3}/', // ellipsis - '/(\s?)--(\s?)/', // em dash - '/\s-(?:\s|$)/', // en dash - '/(\d+)( ?)x( ?)(?=\d+)/', // dimension sign - '/\b ?[([]TM[])]/i', // trademark - '/\b ?[([]R[])]/i', // registered - '/\b ?[([]C[])]/i', // copyright - ); - - extract($this->glyph, EXTR_PREFIX_ALL, 'txt'); - - $glyph_replace = array( - '$1'.$txt_apostrophe.'$2', // apostrophe's - '$1'.$txt_apostrophe.'$2', // back in '88 - '$1'.$txt_quote_single_close, // single closing - $txt_quote_single_open, // single opening - '$1'.$txt_quote_double_close, // double closing - $txt_quote_double_open, // double opening - '$1', // 3+ uppercase acronym - '$1', // 3+ uppercase - '$1'.$txt_ellipsis, // ellipsis - '$1'.$txt_emdash.'$2', // em dash - ' '.$txt_endash.' ', // en dash - '$1$2'.$txt_dimension.'$3', // dimension sign - $txt_trademark, // trademark - $txt_registered, // registered - $txt_copyright, // copyright - ); - - $text = preg_split("/(<.*>)/U", $text, -1, PREG_SPLIT_DELIM_CAPTURE); - foreach($text as $line) { - if (!preg_match("/<.*>/", $line)) { - $line = preg_replace($glyph_search, $glyph_replace, $line); - } - $glyph_out[] = $line; - } - return join('', $glyph_out); - } - -// ------------------------------------------------------------- - function iAlign($in) - { - $vals = array( - '<' => 'left', - '=' => 'center', - '>' => 'right'); - return (isset($vals[$in])) ? $vals[$in] : ''; - } - -// ------------------------------------------------------------- - function hAlign($in) - { - $vals = array( - '<' => 'left', - '=' => 'center', - '>' => 'right', - '<>' => 'justify'); - return (isset($vals[$in])) ? $vals[$in] : ''; - } - -// ------------------------------------------------------------- - function vAlign($in) - { - $vals = array( - '^' => 'top', - '-' => 'middle', - '~' => 'bottom'); - return (isset($vals[$in])) ? $vals[$in] : ''; - } - -// ------------------------------------------------------------- -// NOTE: deprecated - function encode_high($text, $charset = "UTF-8") - { - return mb_encode_numericentity($text, $this->cmap(), $charset); - } - -// ------------------------------------------------------------- -// NOTE: deprecated - function decode_high($text, $charset = "UTF-8") - { - return mb_decode_numericentity($text, $this->cmap(), $charset); - } - -// ------------------------------------------------------------- -// NOTE: deprecated - function cmap() - { - $f = 0xffff; - $cmap = array( - 0x0080, 0xffff, 0, $f); - return $cmap; - } - -// ------------------------------------------------------------- - function encode_html($str, $quotes=1) - { - $a = array( - '&' => '&', - '<' => '<', - '>' => '>', - ); - if ($quotes) $a = $a + array( - "'" => ''', - '"' => '"', - ); - - return strtr($str, $a); - } - -// ------------------------------------------------------------- - function textile_popup_help($name, $helpvar, $windowW, $windowH) - { - return ' ' . $name . '
    '; - - return $out; - } - -// ------------------------------------------------------------- -// NOTE: deprecated - function txtgps($thing) - { - if (isset($_POST[$thing])) { - if (get_magic_quotes_gpc()) { - return stripslashes($_POST[$thing]); - } - else { - return $_POST[$thing]; - } - } - else { - return ''; - } - } - -// ------------------------------------------------------------- -// NOTE: deprecated - function dump() - { - foreach (func_get_args() as $a) - echo "\n
    ",(is_array($a)) ? print_r($a) : $a, "
    \n"; - } - -// ------------------------------------------------------------- - - function blockLite($text) - { - $this->btag = array('bq', 'p'); - return $this->block($text."\n\n"); - } - - -} // end class - -?> diff --git a/docinfo.html b/docinfo.html new file mode 100644 index 0000000..665c7eb --- /dev/null +++ b/docinfo.html @@ -0,0 +1,2 @@ + diff --git a/faq.html b/faq.html index eb29acc..ec49ea5 100644 --- a/faq.html +++ b/faq.html @@ -1,92 +1,14 @@ - - -slackroll: Frequently Asked Questions - - - - -
    slackroll
    -
    Frequently Asked Questions
    -
    Also available: Introduction and tutorial RSS feed
    - -

    Packages with nonstandard names

    - -

    Question: While attempting to setup slackroll I get ERROR: Nonstandard package name: <package>. How can I solve this problem?

    - -

    Answer: It seems some people are using packages that don’t follow the Slackware package name convention of name-version-arch-build. I think it is wrong to have a package that doesn’t follow the convention. slackroll needs to parse the package names to extract the different components. These packages make it very difficult or impossible, so they are rejected. There is no way to analyze those names properly in a predictable way. The problem should be solved by removing that package, renaming the package archive to have a standard name and then installing it again.

    - -

    Some examples of invalid package names I have seen reported are pyfloppy-1.6-noarch.2AS, gammapage-0.5.i486-1AS and scons-0.96.1-1.noarch.

    - -

    Remember: it doesn’t matter if it’s an official package or a foreign or custom one. It should follow the naming convention.

    - -

    Saving the list of URLs

    - -

    Question: Using the urls or urls-upgrades operation I want to save the URL list to a text file. However, if I use shell redirections and slackroll prompts me to select a specific package version, I can’t see the questions. Is there an easy way of doing this?

    - -

    Answer: Yes. Pipe the output of slackroll to tee urls.txt and then edit the file to remove the extra lines.

    - -

    Coordinating with rsync

    - -

    Question: I normally get my packages using rsync, so as to keep a local copy of the remote tree. Can I coordinate this with slackroll?

    - -

    Answer: Yes. I would use a script like the following one, replacing the chunks in curly braces by the appropriate contents.

    - -
    -
-SLACKROLL_DIR=/var/slackroll
-LOCAL_MIRROR_DIR={ path to local copy of the remote trees }
-{ rsync command(s) }
-cd $SLACKROLL_DIR
-slackroll update
-rm -f packages/*
-for pkg in $( slackroll remote-paths ); do
-    ln -sf $LOCAL_MIRROR_DIR/$pkg ./packages
-done
-
-
    - -

    This will synchronize your local copy of the remote trees and then populate the slackroll package cache with symbolic links to the package archives located inside your local copy of the Slackware remote trees. From the point of view of slackroll, it’s like if it had already downloaded every package.

    - -

    Environment variables

    - -

    Question: Which environment variables affect slackroll?

    - -

    Answer: TMPDIR lets you specify a temporary directory that will be used to download files before they are moved to their final locations, which is /var/slackroll/tmp by default. PAGER lets you specify a pager program, which is less by default. VISUAL lets you specify a visual editor, which is used to edit single files and is vim by default. SRDIFF lets you specify the diff tool that will be used to edit and compare pairs of files, which is vimdiff by default.

    - -

    Syntax highlighting in vimdiff

    - -

    Question: Is it possible to disable syntax highlighting in vim, but only when it’s running in diff mode?

    - -

    Answer: Yes. Add this to your ~/.vimrc file, taken from the vim help documents:

    - -
    -
-if &diff
-	syntax off
-endif
-
-
    - -

    Most frequently used operations

    - -

    Question: slackroll has a lot of operations available. Some of them are mentioned in the tutorial but, in a few words, which operations do you use more frequently?

    - -

    Answer: There is a first group of operations everybody will be running very frequently: update, changelog, list-transient and upgrade. If you use a few foreign packages you install and upgrade by hand, you could put install-foreign in that first group too. Some users, specially the ones running slackware-current like I do, would have a second group of common operations they run from time to time: clean-cache, install, remove, remove-unavailable, install-new and not-installed.

    - -

    Comparing slackroll to other tools

    - -

    Question: What are the differences between slackroll and other tools like slapt-get, swaret or slackpkg?

    - -

    Answer: That’s a hard question which is better answered by exposing the features of slackroll. In any case, it should be clarified that you can run two types of Slackware installations. On the one hand you have stable releases. If you are going to run a stable release any tool will probably be useful enough for you, including slackroll. This is because stable releases are easy to manage, given that the only events they are exposed to are the release of patches. Any of the existing tools can easily tell you which patches have been released and let you automate the download and installation process. It is extremely rare, but not impossible, for a package to be added to or removed from the tree of a stable release.

    - -

    On the other hand, you can be running the rolling release of Slackware which serves as the testing tree, called slackware(64)-current, or using third-party repositories. In this case, in my humble opinion, slackroll is the best tool. This is because slackroll lets you track almost any event happening in the remote trees, be it packages being added, removed or upgraded, including the events of a foreign package getting a remote version and the removal of a package for which a customized version was installed. This is possible thanks to its package states foundation and the preference for working with two different states (foreign and frozen) instead of relying on a blacklisting mechanism. No other tool, as far as I know, can deal with as many events as slackroll. I’m unable to imagine an event that is not covered by slackroll.

    - -

    Apart from the type of Slackware installation you’re running, there’s the issue of using third-party repositories. Starting with version 43 and inspired by community forks of slackpkg, slackroll added support for external repositories, and performs a decent job at handling them. This makes it a viable alternative to slapt-get in those situations. Some of those repositories provide dependency information for packages, which slapt-get can use, while slackroll doesn’t use it.

    - -

    Compared to the shell-based swaret (there was a new swaret being developed in Perl), slackroll lacks tracking binary dependencies, but it compensates that lack by letting you search for files in remote packages with the manifest-related operations. Apart from that, swaret is incredibly slow and CPU hungry even when it’s only downloading files from the network, and doesn’t come close to tracking as many events as slackroll. slackroll is, in my humble opinion, a clear winner over swaret unless you absolutely love the binary dependency detection and resolution it provides. For me that’s a minor feature. The Perl implementation was supposed to be basically the same, but solving the high CPU usage problem. If that’s the case, slackroll would still be a much better option, in my opinion, because swaret still doesn’t do glibc upgrades properly, does not detect removed packages, etc.

    - -

    slackroll’s closest friend is slackpkg, included in the /extra/ tree. You can think of it like a very much improved slackpkg that works faster, detects more corner cases and has more features. If you run slackpkg, do not hesitate to give slackroll a try. The main difference between slackpkg and slackroll is that the latter, like many other package management tools, keeps a persistent database of packages on disk. For example, slackpkg uses a reliable method of parsing the change log to detect when a package has been added, while slackroll downloads FILELIST.TXT and notices which packages are new because it didn’t have information on them before. This method also works with third-party repositories. Another example is slackpkg’s clean-system operation, which prompts you about packages with are not in any official package set. This operation helps you remove packages that have been removed from the official Slackware tree, but you need to blacklist your own packages if you don’t want them to appear in the list. slackroll, on the other hand, can be told those packages are foreign and it remembers that information.

    - -

    Finally, in general, slackroll is at least as fast or faster than any of the above tools, specially faster than the ones that are big shell scripts (slackpkg and swaret). It downloads less meta-data than any other, because it only needs FILELIST.TXT and, for convenience, the new entries from the change log (indeed, it only downloads the new entries). It detects more events, which is specially useful when running Slackware’s rolling release, slackware(64)-current. And it has some useful features no other tool has, like the operations to detect orphan files, broken symlinks and missing files. You won’t have to run grep on the contents of /var/log/packages anymore, because it has a local search operation. It lets you download and search the MANIFEST list for specific files if, for example, you’re missing a library. It also lets you choose which package version to install when there are several ones available. It lets you upgrade individual packages or every upgrade-able package, install new packages, remove old ones, search for package names or packages with a given tree component, list alternative versions of packages, detect and warn you about activity in glibc packages (giving them priority while upgrading too), etc.

    - + + + + + + + Page Redirection + + + If you are not redirected automatically, follow this link + diff --git a/faq.php b/faq.php deleted file mode 100644 index 683f667..0000000 --- a/faq.php +++ /dev/null @@ -1,34 +0,0 @@ - - -slackroll: Frequently Asked Questions - - - - -
    slackroll
    -
    Frequently Asked Questions
    -
    Also available: Introduction and tutorial RSS feed
    - -TextileThis($contents); - -// For untrusted user input, use TextileRestricted instead: -// echo $textile->TextileRestricted($in); - - -?> - - - diff --git a/faq.textile b/faq.textile deleted file mode 100644 index 7cf4f29..0000000 --- a/faq.textile +++ /dev/null @@ -1,80 +0,0 @@ -h1. Packages with nonstandard names - -*Question*: While attempting to setup @slackroll@ I get ERROR: Nonstandard package name: <package>. How can I solve this problem? - -*Answer*: It seems some people are using packages that don't follow the Slackware package name convention of _name-version-arch-build_. I think it is wrong to have a package that doesn't follow the convention. @slackroll@ needs to parse the package names to extract the different components. These packages make it very difficult or impossible, so they are rejected. There is no way to analyze those names properly in a predictable way. The problem should be solved by removing that package, renaming the package archive to have a standard name and then installing it again. - -Some examples of invalid package names I have seen reported are @pyfloppy-1.6-noarch.2AS@, @gammapage-0.5.i486-1AS@ and @scons-0.96.1-1.noarch@. - -Remember: it doesn't matter if it's an official package or a foreign or custom one. It should follow the naming convention. - -h1. Saving the list of URLs - -*Question*: Using the @urls@ or @urls-upgrades@ operation I want to save the URL list to a text file. However, if I use shell redirections and @slackroll@ prompts me to select a specific package version, I can't see the questions. Is there an easy way of doing this? - -*Answer*: Yes. Pipe the output of @slackroll@ to @tee urls.txt@ and then edit the file to remove the extra lines. - -h1. Coordinating with rsync - -*Question*: I normally get my packages using rsync, so as to keep a local copy of the remote tree. Can I coordinate this with @slackroll@? - -*Answer*: Yes. I would use a script like the following one, replacing the chunks in curly braces by the appropriate contents. - -
    -
-SLACKROLL_DIR=/var/slackroll
-LOCAL_MIRROR_DIR={ path to local copy of the remote trees }
-{ rsync command(s) }
-cd $SLACKROLL_DIR
-slackroll update
-rm -f packages/*
-for pkg in $( slackroll remote-paths ); do
-    ln -sf $LOCAL_MIRROR_DIR/$pkg ./packages
-done
-
-
    - -This will synchronize your local copy of the remote trees and then populate the @slackroll@ package cache with symbolic links to the package archives located inside your local copy of the Slackware remote trees. From the point of view of @slackroll@, it's like if it had already downloaded every package. - -h1. Environment variables - -*Question*: Which environment variables affect @slackroll@? - -*Answer*: @TMPDIR@ lets you specify a temporary directory that will be used to download files before they are moved to their final locations, which is @/var/slackroll/tmp@ by default. @PAGER@ lets you specify a pager program, which is @less@ by default. @VISUAL@ lets you specify a visual editor, which is used to edit single files and is @vim@ by default. @SRDIFF@ lets you specify the diff tool that will be used to edit and compare pairs of files, which is @vimdiff@ by default. - -h1. Syntax highlighting in vimdiff - -*Question*: Is it possible to disable syntax highlighting in @vim@, but only when it's running in diff mode? - -*Answer*: Yes. Add this to your @~/.vimrc@ file, taken from the @vim@ help documents: - -
    -
-if &diff
-	syntax off
-endif
-
-
    - -h1. Most frequently used operations - -*Question*: @slackroll@ has a lot of operations available. Some of them are mentioned in the tutorial but, in a few words, which operations do you use more frequently? - -*Answer*: There is a first group of operations everybody will be running very frequently: @update@, @changelog@, @list-transient@ and @upgrade@. If you use a few foreign packages you install and upgrade by hand, you could put @install-foreign@ in that first group too. Some users, specially the ones running @slackware-current@ like I do, would have a second group of common operations they run from time to time: @clean-cache@, @install@, @remove@, @remove-unavailable@, @install-new@ and @not-installed@. - - -h1. Comparing @slackroll@ to other tools - -*Question*: What are the differences between @slackroll@ and other tools like @slapt-get@, @swaret@ or @slackpkg@? - -*Answer*: That's a hard question which is better answered by exposing the features of @slackroll@. In any case, it should be clarified that you can run two types of Slackware installations. On the one hand you have stable releases. If you are going to run a stable release any tool will probably be useful enough for you, including @slackroll@. This is because stable releases are easy to manage, given that the only events they are exposed to are the release of patches. Any of the existing tools can easily tell you which patches have been released and let you automate the download and installation process. It is extremely rare, but not impossible, for a package to be added to or removed from the tree of a stable release. - -On the other hand, you can be running the rolling release of Slackware which serves as the testing tree, called slackware(64)-current, or using third-party repositories. In this case, in my humble opinion, @slackroll@ is the best tool. This is because @slackroll@ lets you track almost any event happening in the remote trees, be it packages being added, removed or upgraded, including the events of a foreign package getting a remote version and the removal of a package for which a customized version was installed. This is possible thanks to its package states foundation and the preference for working with two different states (foreign and frozen) instead of relying on a blacklisting mechanism. No other tool, as far as I know, can deal with as many events as @slackroll@. I'm unable to imagine an event that is not covered by @slackroll@. - -Apart from the type of Slackware installation you're running, there's the issue of using third-party repositories. Starting with version 43 and inspired by community forks of @slackpkg@, @slackroll@ added support for external repositories, and performs a decent job at handling them. This makes it a viable alternative to *slapt-get* in those situations. Some of those repositories provide dependency information for packages, which @slapt-get@ can use, while @slackroll@ doesn't use it. - -Compared to the shell-based *swaret* (there was a new @swaret@ being developed in Perl), @slackroll@ lacks tracking binary dependencies, but it compensates that lack by letting you search for files in remote packages with the manifest-related operations. Apart from that, @swaret@ is incredibly slow and CPU hungry even when it's only downloading files from the network, and doesn't come close to tracking as many events as @slackroll@. @slackroll@ is, in my humble opinion, a clear winner over @swaret@ unless you absolutely love the binary dependency detection and resolution it provides. For me that's a minor feature. The Perl implementation was supposed to be basically the same, but solving the high CPU usage problem. If that's the case, @slackroll@ would still be a much better option, in my opinion, because @swaret@ still doesn't do @glibc@ upgrades properly, does not detect removed packages, etc. - -@slackroll@'s closest friend is *slackpkg*, included in the @/extra/@ tree. You can think of it like a very much improved @slackpkg@ that works faster, detects more corner cases and has more features. If you run @slackpkg@, do not hesitate to give @slackroll@ a try. The main difference between @slackpkg@ and @slackroll@ is that the latter, like many other package management tools, keeps a persistent database of packages on disk. For example, @slackpkg@ uses a reliable method of parsing the change log to detect when a package has been added, while @slackroll@ downloads FILELIST.TXT and notices which packages are new because it didn't have information on them before. This method also works with third-party repositories. Another example is @slackpkg@'s clean-system operation, which prompts you about packages with are not in any official package set. This operation helps you remove packages that have been removed from the official Slackware tree, but you need to blacklist your own packages if you don't want them to appear in the list. @slackroll@, on the other hand, can be told those packages are foreign and it _remembers_ that information. - -Finally, in general, @slackroll@ is at least as fast or faster than any of the above tools, specially faster than the ones that are big shell scripts (@slackpkg@ and @swaret@). It downloads less meta-data than any other, because it only needs @FILELIST.TXT@ and, for convenience, the new entries from the change log (indeed, it only downloads the new entries). It detects more events, which is specially useful when running Slackware's rolling release, _slackware(64)-current_. And it has some useful features no other tool has, like the operations to detect orphan files, broken symlinks and missing files. You won't have to run @grep@ on the contents of @/var/log/packages@ anymore, because it has a local search operation. It lets you download and search the MANIFEST list for specific files if, for example, you're missing a library. It also lets you choose which package version to install when there are several ones available. It lets you upgrade individual packages or every upgrade-able package, install new packages, remove old ones, search for package names or packages with a given tree component, list alternative versions of packages, detect and warn you about activity in @glibc@ packages (giving them priority while upgrading too), etc. diff --git a/generate b/generate deleted file mode 100755 index 89f0c86..0000000 --- a/generate +++ /dev/null @@ -1,4 +0,0 @@ -#!/bin/sh -php tutorial.php >tutorial.html -php faq.php >faq.html -cp tutorial.html index.html diff --git a/index.html b/index.html index 33ac8ab..1b2d5aa 100644 --- a/index.html +++ b/index.html @@ -1,166 +1,1345 @@ - - -slackroll: Introduction and Tutorial - - - - -
    slackroll
    -
    Introduction and Tutorial
    -
    Also available: FAQ RSS feed
    - -

    Target audience

    - -

    slackroll is a package or update manager for Slackware systems. It does not provide dependency checking and uses pkgtools to install or upgrade packages. It’s designed to work with official mirrors and third-party repositories. If you have a Slackware system mainly composed of official packages, unofficial packages and a few custom packages, slackroll can help you manage it and keep in touch with the remote trees. It tries to know when new packages appear, when packages are removed and when packages are upgraded.

    - -

    Before you start

    - -

    So you have decided to try slackroll. Let me introduce a few concepts so you don’t get lost.

    - -

    Packages

    - -

    In the following text I’m going to be talking about packages. For package, we are going to understand a named piece of software, without having any specific version unless I explicitly mention it. A package can be bash or kdewebdev or gcc-gfortran, for example.

    - -

    States

    - -

    Each package is in one of several possible states. The program tries to keep a persistent database that associates each package with its state. When it runs, it analyzes the list of packages present in your system, the list of remote packages, and tries to keep the persistent database updated by introducing new entries, deleting old ones and changing the state of some of those entries.

    - -

    There are several possible states for a package, divided in two groups. First, we have transient states. As a user, your job is to make sure no packages remain in those states for long periods of time. Second, we have the normal states, in which the different packages should normally be.

    - -

    Transient states (to be avoided)

    - -

    NEW

    - -

    A package is in this state when it’s present in a remote tree and it wasn’t present before. If you detect you have packages in this state you should decide if you want to install them or mark them as not installed. This state lets you see which packages are being added to remote trees.

    - -

    UNAVAILABLE

    - -

    Sorry if this name is somehow confusing. A package is in this state when it’s present in your system, but not in a remote tree. You should decide if you want to remove them from your system or mark them as foreign packages. This state lets you see which packages are being removed from remote trees.

    - -

    OUTDATED

    - -

    A package is outdated if it’s present in your system and in a remote tree, but the local version does not match any relevant remote one. The program will try to upgrade these packages.

    - -

    Normal states

    - -

    INSTALLED

    - -

    A package is installed if it’s present in your system and in the remote tree, and the local version is not outdated. Very common state, as you can suppose.

    - -

    NOT INSTALLED

    - -

    A package is not installed if it’s a known package which is not present in your system but exists in a remote tree. It’s also a very common state.

    - -

    FROZEN

    - -

    No package will enter the frozen state unless you mark it so. It should be used for packages present in your system and in a remote tree, but that you don’t want to upgrade automatically. This state can be used for packages which are not meant to be upgraded automatically or ever, like aaa_elflibs and others, and probably for customized versions of official packages. For example, my custom build of freetype is marked as frozen. You must pay attention to these packages, as upgrades to them will be silently ignored. You may find the list-versions and list-outdated-frozen operations useful to detect version mismatches between your local copy and the ones in remote trees. Having a package in the frozen state does not prevent you from using the install operation to download and install a different version. If the package ever disappears from the remote trees, it will be marked as unavailable and you will probably see it. You could continue to use it by marking it as foreign if you wish.

    - -

    FOREIGN

    - -

    No package will enter the foreign state unless you mark it so. It should be used for packages that exist in your system but do not have a known remote origin. For example, the slackroll package in my system is marked as foreign. A foreign package will be marked as installed or outdated if it ever appears in a remote tree, usually becoming a candidate for upgrading. Hopefully, you’ll notice this fact. You could still use your own version instead of the remote one by marking it as frozen.

    - -

    Remote trees

    - -

    slackroll works with two types of remote trees. It needs a mirror, which is a URL pointing to a replica of the official Slackware package tree for the Slackware version you’re using. There can be only one mirror and it’s selected with the set-mirror operation, as you will see later.

    - -

    In addition, slackroll can work with a number of additional third-party repositories. These are managed with the add-repo, list-repos and remove-repo operations, and they will be explained later.

    - -

    Get slackroll

    - -

    slackroll is a self-contained Python script released to the public domain. You can download the source code of the master branch or any tagged releases as a ZIP archive from Github, or by cloning the repository. Once you have access to the plain source files, run the SlackBuild script from the source directory as root. This will create a package you can install with installpkg for the first time. In the future, you can use upgradepkg or even slackroll itself to install newer package versions. Continue reading for more details.

    - -

    Getting started

    - -

    slackroll requires python, pkgtools, gnupg (or gnupg2), an editor and diff tool (which are vim and vimdiff by default (provided by package vim), and a pager (less by default) to operate properly.

    - -

    It should be noted that you can start using slackroll whenever you want, but my advice is to do it when your system is under control and there are no upgrades pending. This will give you a chance of configuring the program and setting the package states properly without making serious mistakes.

    - -

    You should first choose a Slackware mirror. In case your mirror of choice offers access using both FTP and HTTP, prefer HTTP. Take into account slackroll will store downloaded packages in a subdirectory of /var/slackroll, so you will probably need to have a good amount of space available for them in there. Set the mirror URL with the set-mirror operation. For example:

    - -

    -slackroll set-mirror 'http://example.org/slackware-current/' -

    - -

    Great. You are ready to start. Retrieve the remote GPG key to add it to your key ring. Having the GPG key is required, and it should be safe to do this step even if the key is already in your key ring. You can also get the key from the Slackware CD or DVD. The GPG key and the official package signatures will be downloaded from a primary mirror instead of the mirror you chose, in order to increase security.

    - -

    -slackroll import-key -

    - -

    Retrieve information about the remote packages. You’ll have to perform this step every time a remote tree changes.

    - -

    -slackroll update -

    - -

    Finally, you could start checking if there are new packages, unavailable packages or upgrades. However, the first time you use slackroll, any package not installed in your system will be marked as new, every foreign package will be marked as unavailable, and every customized package will probably be a candidate for upgrading if you try to do so. If you have your system under control (and I hope you do!), you can in most cases blindly mark all new packages as not installed. There’s a command to do it, being a common first operation.

    - -

    -slackroll new-not-installed -

    - -

    In most cases, you can also mark any unavailable packages as foreign. However, the number of foreign packages is usually quite low, and forgetting to uninstall a package which has been removed is a very common mistake, so my advice is to review the list of unavailable packages by hand, detecting which ones may not be foreign packages and need to be uninstalled.

    - -

    -slackroll list-unavailable -

    - -

    Once you’ve got rid of old packages (using removepkg or the remove operation), mark the rest as foreign packages.

    - -

    -slackroll unavailable-foreign -

    - -

    Some people like to “blacklist” packages so they are not upgraded normally. Almost always, you want to do this with the package aaa_elflibs if it’s present in your system, and maybe with some other packages. If you don’t want them to be upgraded normally, they belong to the frozen state. Mark them as frozen. The same applies to customized builds of official packages.

    - -

    -slackroll frozen aaa_elflibs -

    - -

    The frozen operation accepts a list of packages as its arguments. You don’t need to issue a separate command for each one of them.

    - -

    Regarding customized versions of official packages, there are at least three ways of dealing with them. Some people prefer to give them version names that match the official ones, despite being customized builds, and keep them in the installed state. The program will want to upgrade them automatically in that case, and maybe the official version will overwrite the custom one after an upgrade, before you rebuild it, if you don’t mark it as frozen in the mean time. Some other people prefer to do the same but putting the package permanently in the frozen state. In that case, list-outdated-frozen is useful to detect version mismatches between your local copy and the remote ones. Finally, some other people prefer to give them custom version names, normally via personalized build numbers that usually include some packager initials, and mark them as frozen. In that case, list-versions can help you see if your local copy needs to be rebuilt for a new version.

    - -

    Normal operation

    - -

    First off, slackroll help will give you a summary of the most common operations, plus some advice. You can read a brief description of every supported operation by running slackroll help all. Finally, you can get specific help for an operation using slackroll help OPERATION, where OPERATION is the name of the operation you want to get help for.

    - -

    This program is not a perfect tool. I think it can handle almost every situation and be told to do exactly what you want, but reading the change log and subscribing to the slackware-security mailing list is highly recommended.

    - -

    In any case, the most frequent command you will probably run is slackroll update, which should be run whenever the remote tree is changed. Then, you should read the change log with the changelog operation if there are new entries and, finally, the list-transient operation will provide a summary of activity. There should be no packages in transient states after you’re finished dealing with the changes.

    - -

    Watch out for upgrades in the glibc-solibs, sed and pkgtools packages. They should (almost) always be the first ones to be installed or upgraded in that order, even before new packages. You can use the upgrade-key-packages operation to upgrade them first. The program will try to inform you about changes in those packages with a noticeable warning.

    - -

    New packages should either be installed selectively with the install operation or all at the same time with install-new. New packages which will not be installed should be put in the not-installed state with not-installed.

    - -

    Outdated packages should be upgraded, normally using the upgrade operation.

    - -

    Unavailable packages could either be foreign packages that you forgot to mark as such, and should be marked with foreign, or packages which have been removed from the remote tree. In that case, remove or remove-unavailable are the operations you will be looking for.

    - -

    When installing or upgrading foreign packages, you can use installpkg or upgradepkg and then mark them as foreign if needed. However, you can also install them using the install-foreign operation to save time and avoid problems in the future.

    - -

    Also, remember to run the clean-cache operation from time to time to get rid of old and outdated package archives stored in the package cache.

    - -

    The order described above is the order in which you should proceed in most cases. However, sometimes it’s not the correct order. That’s why it’s important to read the change log to detect possible special cases and read comments by Patrick Volkerding. If you break that order, slackroll will emit a warning, but it’s only a warning. The choice of what to do is on you.

    - -

    Kernel upgrades

    - -

    When kernel packages have pending upgrades, you can use two operations created specifically to handle the situation. kernel-upgrade will install the new kernel packages using installpkg instead of upgradepkg and then help you configure your boot loader for the new kernel. This means that, for a small time period, you will have two versions of the kernel packages installed. After a successful reboot to the new kernel, you can use the kernel-clean operation to remove the previous versions of those packages.

    - -

    Third-party repositories

    - -

    As mentioned previously, slackroll can also work with a number of third-party repositories that would normally contain known but unofficial packages for the Slackware version you’re running. If you’re going to work with third-party repositories, I recommend adding them after the initial setup phase described in this tutorial.

    - -

    You can add a new repository with the add-repo operation. Once you’ve added all the third-party repositories you want, run the update operation to retrieve information about remote packages and the list-transient operation to check the summary of activity.

    - -

    For slackroll to be able to work with a third-party repository, the repository needs to provide a FILELIST.TXT file in the repository root, and packages need to be signed with external .asc files like the official ones. These package signatures will be verified by the program when downloading packages, which means the signature key needs to be in the superuser’s keyring. It’s very important to note the import-key operation will not download GPG keys from third-party repositories as a security measure. You need to download the keys by yourself and import them with gpg --import KEY_FILE, where KEY_FILE is the path to the GPG key file. Then, you will be able to download and install packages from the repository.

    - -

    The list of third-party repositories can be printed with the list-repos operation, and you can remove a repository from the list with the remove-repo operation, by providing the repo number as listed with list-repos.

    - -

    Feedback, questions, bug reports

    - -

    I’m all open for good bug reports and general feedback but I’m, as always, reluctant to change the main program concepts, like adding dependency support or probably adding more package states. I also know the program currently can’t be used to upgrade the system in non-interactive mode (like calling it from a cron entry). That is very unlikely to change, because when there’s an upgrade, there’s no easy way to decide which version should be installed if a package has a version in the main tree, another one in /extra/ and another one in /testing/, so it’s always going to need user input.

    - -

    If you have a question, you should first read the FAQ. For other questions, comments or suggestions, contact me by email, or report an issue in the issue tracker. Keep in mind I’m using the program under slackware64-current. If you detect a problem under another version, please report it as soon as possible because it may go unnoticed to me.

    - - + + + + + + + +slackroll: package or update manager for Slackware systems + + + + + + +
    +
    +

    Target audience

    +
    +

    slackroll is a package or update manager for Slackware systems. It does not +provide dependency checking and uses pkgtools to install or upgrade +packages. It’s designed to work with official mirrors and third-party +repositories. If you have a Slackware system mainly composed of official +packages, unofficial packages and a few custom packages, slackroll can help +you manage it and keep in touch with the remote trees. It tries to know when +new packages appear, when packages are removed and when packages are upgraded.

    +
    +
    +
    +

    Before you start

    +
    +

    So you have decided to try slackroll. Let me introduce a few concepts so you +don’t get lost.

    +
    +

    Packages

    +

    In the following text I’m going to be talking about packages. For package, we +are going to understand a named piece of software, without having any +specific version unless I explicitly mention it. A package can be bash or +kdewebdev or gcc-gfortran, for example.

    +
    +
    +

    States

    +

    Each package is in one of several possible states. The program tries to keep a +persistent database that associates each package with its state. When it runs, +it analyzes the list of packages present in your system, the list of remote +packages, and tries to keep the persistent database updated by introducing new +entries, deleting old ones and changing the state of some of those entries.

    +

    There are several possible states for a package, divided in two groups. First, +we have transient states. As a user, your job is to make sure no packages +remain in those states for long periods of time. Second, we have the normal +states, in which the different packages should normally be.

    +
    +
    +

    Transient states (to be avoided)

    +
    +

    NEW

    +

    A package is in this state when it’s present in a remote tree and it wasn’t +present before. If you detect you have packages in this state you should +decide if you want to install them or mark them as not installed. This state +lets you see which packages are being added to remote trees.

    +
    +
    +

    UNAVAILABLE

    +

    Sorry if this name is somehow confusing. A package is in this state when it’s +present in your system, but not in a remote tree. You should decide if you +want to remove them from your system or mark them as foreign packages. This +state lets you see which packages are being removed from remote trees.

    +
    +
    +

    OUTDATED

    +

    A package is outdated if it’s present in your system and in a remote tree, but +the local version does not match any relevant remote one. The program will try +to upgrade these packages.

    +
    +
    +
    +

    Normal states

    +
    +

    INSTALLED

    +

    A package is installed if it’s present in your system and in the remote tree, +and the local version is not outdated. Very common state, as you can suppose.

    +
    +
    +

    NOT INSTALLED

    +

    A package is not installed if it’s a known package which is not present in +your system but exists in a remote tree. It’s also a very common state.

    +
    +
    +

    FROZEN

    +

    No package will enter the frozen state unless you mark it so. It should be +used for packages present in your system and in a remote tree, but that you +don’t want to upgrade automatically. This state can be used for packages which +are not meant to be upgraded automatically or ever, like aaa_elflibs and +others, and probably for customized versions of official packages. For +example, my custom build of freetype is marked as frozen. You must pay +attention to these packages, as upgrades to them will be silently ignored. You +may find the list-versions and list-outdated-frozen operations useful to +detect version mismatches between your local copy and the ones in remote +trees. Having a package in the frozen state does not prevent you from using +the install operation to download and install a different version. If the +package ever disappears from the remote trees, it will be marked as +unavailable and you will probably see it. You could continue to use it by +marking it as foreign if you wish.

    +
    +
    +

    FOREIGN

    +

    No package will enter the foreign state unless you mark it so. It should be +used for packages that exist in your system but do not have a known remote +origin. For example, the slackroll package in my system is marked as +foreign. A foreign package will be marked as installed or outdated if it ever +appears in a remote tree, usually becoming a candidate for upgrading. +Hopefully, you’ll notice this fact. You could still use your own version +instead of the remote one by marking it as frozen.

    +
    +
    +
    +

    Remote trees

    +

    slackroll works with two types of remote trees. It needs a mirror, which +is a URL pointing to a replica of the official Slackware package tree for the +Slackware version you’re using. There can be only one mirror and it’s selected +with the set-mirror operation, as you will see later.

    +

    In addition, slackroll can work with a number of additional third-party +repositories. These are managed with the add-repo, list-repos and +remove-repo operations, and they will be explained later.

    +
    +
    +
    +
    +

    Get slackroll

    +
    +

    slackroll is a +self-contained Python script released to the public domain. You can download a +premade package if available from Github, or grab the source code of the +master branch or any tagged releases as a ZIP archive or by cloning the +repository.

    +

    If you use the source, run the SlackBuild script from the source directory as +root. This will create a package you can install with installpkg for the +first time. In the future, you can use upgradepkg or even slackroll itself +to install newer package versions. Continue reading for more details.

    +
    +
    +
    +

    Getting started

    +
    +

    slackroll requires python, pkgtools, gnupg (or gnupg2), an editor +and diff tool (which are vim and vimdiff by default (provided by package +vim), and a pager (less by default) to operate properly.

    +

    It should be noted that you can start using slackroll whenever you want, but +my advice is to do it when your system is under control and there are no +upgrades pending. This will give you a chance of configuring the program and +setting the package states properly without making serious mistakes.

    +

    You should first choose a Slackware mirror. In case your mirror of choice +offers access using both FTP and HTTP, prefer HTTP. Take into account +slackroll will store downloaded packages in a subdirectory of +/var/slackroll, so you will probably need to have a good amount of space +available for them in there. Set the mirror URL with the set-mirror +operation. For example:

    +
    +
    +
    slackroll set-mirror
+'http://example.org/slackware-current/'
    +
    +

    Great. You are ready to start. Retrieve the remote GPG key to add it to your +key ring. Having the GPG key is required, and it should be safe to do this +step even if the key is already in your key ring. You can also get the key +from the Slackware CD or DVD. The GPG key and the official package signatures +will be downloaded from a primary mirror instead of the mirror you chose, in +order to increase security.

    +
    +
    +
    slackroll import-key
    +
    +

    Retrieve information about the remote packages. You’ll have to perform this +step every time a remote tree changes.

    +
    +
    +
    slackroll update
    +
    +

    Finally, you could start checking if there are new packages, unavailable +packages or upgrades. However, the first time you use slackroll, any package +not installed in your system will be marked as new, every foreign package will +be marked as unavailable, and every customized package will probably be a +candidate for upgrading if you try to do so. If you have your system under +control (and I hope you do!), you can in most cases blindly mark all new +packages as not installed. There’s a command to do it, being a common first +operation.

    +
    +
    +
    slackroll new-not-installed
    +
    +

    In most cases, you can also mark any unavailable packages as foreign. +However, the number of foreign packages is usually quite low, and forgetting +to uninstall a package which has been removed is a very common mistake, so my +advice is to review the list of unavailable packages by hand, detecting which +ones may not be foreign packages and need to be uninstalled.

    +
    +
    +
    slackroll list-unavailable
    +
    +

    Once you’ve got rid of old packages (using removepkg or the remove +operation), mark the rest as foreign packages.

    +
    +
    +
    slackroll unavailable-foreign
    +
    +

    Some people like to “blacklist” packages so they are not upgraded normally. +Almost always, you want to do this with the package aaa_elflibs if it’s +present in your system, and maybe with some other packages. If you don’t want +them to be upgraded normally, they belong to the frozen state. Mark them as +frozen. The same applies to customized builds of official packages.

    +
    +
    +
    slackroll frozen aaa_elflibs
    +
    +

    The frozen operation accepts a list of packages as its arguments. You don’t +need to issue a separate command for each one of them.

    +

    Regarding customized versions of official packages, there are at least three +ways of dealing with them. Some people prefer to give them version names that +match the official ones, despite being customized builds, and keep them in the +installed state. The program will want to upgrade them automatically in that +case, and maybe the official version will overwrite the custom one after an +upgrade, before you rebuild it, if you don’t mark it as frozen in the mean +time. Some other people prefer to do the same but putting the package +permanently in the frozen state. In that case, list-outdated-frozen is +useful to detect version mismatches between your local copy and the remote +ones. Finally, some other people prefer to give them custom version names, +normally via personalized build numbers that usually include some packager +initials, and mark them as frozen. In that case, list-versions can help you +see if your local copy needs to be rebuilt for a new version.

    +
    +
    +
    +

    Normal operation

    +
    +

    First off, slackroll help will give you a summary of the most common +operations, plus some advice. You can read a brief description of every +supported operation by running slackroll help all. Finally, you can get +specific help for an operation using slackroll help OPERATION, where +OPERATION is the name of the operation you want to get help for.

    +

    This program is not a perfect tool. I think it can handle almost every +situation and be told to do exactly what you want, but reading the change log +and subscribing to the slackware-security mailing list is highly +recommended.

    +

    In any case, the most frequent command you will probably run is slackroll +update, which should be run whenever the remote tree is changed. Then, you +should read the change log with the changelog operation if there are new +entries and, finally, the list-transient operation will provide a summary of +activity. There should be no packages in transient states after you’re +finished dealing with the changes.

    +

    Watch out for upgrades in the glibc-solibs, sed and pkgtools packages. +They should (almost) always be the first ones to be installed or upgraded in +that order, even before new packages. You can use the upgrade-key-packages +operation to upgrade them first. The program will try to inform you about +changes in those packages with a noticeable warning.

    +

    New packages should either be installed selectively with the install +operation or all at the same time with install-new. New packages which will +not be installed should be put in the not-installed state with +not-installed.

    +

    Outdated packages should be upgraded, normally using the upgrade operation.

    +

    Unavailable packages could either be foreign packages that you forgot to mark +as such, and should be marked with foreign, or packages which have been +removed from the remote tree. In that case, remove or remove-unavailable +are the operations you will be looking for.

    +

    When installing or upgrading foreign packages, you can use installpkg or +upgradepkg and then mark them as foreign if needed. However, you can also +install them using the install-foreign operation to save time and avoid +problems in the future.

    +

    Also, remember to run the clean-cache operation from time to time to get rid +of old and outdated package archives stored in the package cache.

    +

    The order described above is the order in which you should proceed in most +cases. However, sometimes it’s not the correct order. That’s why it’s +important to read the change log to detect possible special cases and read +comments by Patrick Volkerding. If you break that order, slackroll will emit a +warning, but it’s only a warning. The choice of what to do is on you.

    +
    +

    Kernel upgrades

    +

    When kernel packages have pending upgrades, you can use two operations created +specifically to handle the situation. kernel-upgrade will install the new +kernel packages using installpkg instead of upgradepkg and then help you +configure your boot loader for the new kernel. This means that, for a small +time period, you will have two versions of the kernel packages installed. +After a successful reboot to the new kernel, you can use the kernel-clean +operation to remove the previous versions of those packages.

    +
    +
    +

    Third-party repositories

    +

    As mentioned previously, slackroll can also work with a number of +third-party repositories that would normally contain known but unofficial +packages for the Slackware version you’re running. If you’re going to work +with third-party repositories, I recommend adding them after the initial setup +phase described in this tutorial.

    +

    You can add a new repository with the add-repo operation. Once you’ve added +all the third-party repositories you want, run the update operation to +retrieve information about remote packages and the list-transient operation +to check the summary of activity.

    +

    For slackroll to be able to work with a third-party repository, the +repository needs to provide a FILELIST.TXT file in the repository root, and +packages need to be signed with external .asc files like the official ones. +These package signatures will be verified by the program when downloading +packages, which means the signature key needs to be in the superuser’s +keyring. It’s very important to note the import-key operation will not +download GPG keys from third-party repositories as a security measure. You +need to download the keys by yourself and import them with gpg --import +KEY_FILE, where KEY_FILE is the path to the GPG key file. Then, you will be +able to download and install packages from the repository.

    +

    The list of third-party repositories can be printed with the list-repos +operation, and you can remove a repository from the list with the +remove-repo operation, by providing the repo number as listed with +list-repos.

    +
    +
    +
    +
    +

    Feedback

    +
    +

    I’m all open for good bug reports and general feedback but I’m, as always, +reluctant to change the main program concepts, like adding dependency support +or probably adding more package states. I also know the program currently +can’t be used to upgrade the system in non-interactive mode (like calling it +from a cron entry). That is very unlikely to change, because when there’s an +upgrade, there’s no easy way to decide which version should be installed if a +package has a version in the main tree, another one in /extra/ and another +one in /testing/, so it’s always going to need user input.

    +

    If you have a question, you should first read the FAQ. For other questions, +comments or suggestions, contact me by +email, or report an issue in the +issue tracker. Keep in mind I’m +using the program under slackware64-current. If you detect a problem under +another version, please report it as soon as possible because it may go +unnoticed to me.

    +
    +
    +
    +

    Frequently Asked Questions

    +
    +
    +

    Packages with nonstandard names

    +

    Question: While attempting to setup slackroll I get ERROR: Nonstandard +package name: <package>. How can I solve this problem?

    +

    Answer: It seems some people are using packages that don’t follow the +Slackware package name convention of name-version-arch-build. I think it is +wrong to have a package that doesn’t follow the convention. slackroll needs +to parse the package names to extract the different components. These packages +make it very difficult or impossible, so they are rejected. There is no way to +analyze those names properly in a predictable way. The problem should be +solved by removing that package, renaming the package archive to have a +standard name and then installing it again.

    +

    Some examples of invalid package names I have seen reported are +pyfloppy-1.6-noarch.2AS, gammapage-0.5.i486-1AS and +scons-0.96.1-1.noarch.

    +

    Remember: it doesn’t matter if it’s an official package or a foreign or custom +one. It should follow the naming convention.

    +
    +
    +

    Saving the list of URLs

    +

    Question: Using the urls or urls-upgrades operation I want to save the +URL list to a text file. However, if I use shell redirections and slackroll +prompts me to select a specific package version, I can’t see the questions. Is +there an easy way of doing this?

    +

    Answer: Yes. Pipe the output of slackroll to tee urls.txt and then edit +the file to remove the extra lines.

    +
    +
    +

    Coordinating with rsync

    +

    Question: I normally get my packages using rsync, so as to keep a local copy +of the remote tree. Can I coordinate this with slackroll?

    +

    Answer: Yes. I would use a script like the following one, replacing the +chunks in curly braces by the appropriate contents.

    +
    +
    +
    SLACKROLL_DIR=/var/slackroll
+LOCAL_MIRROR_DIR={ path to local copy of the remote trees }
+{ rsync command(s) }
+cd $SLACKROLL_DIR
+slackroll update
+rm -f packages/*
+for pkg in $( slackroll remote-paths ); do
+    ln -sf $LOCAL_MIRROR_DIR/$pkg ./packages
+done
    +
    +

    This will synchronize your local copy of the remote trees and then populate +the slackroll package cache with symbolic links to the package archives +located inside your local copy of the Slackware remote trees. From the point +of view of slackroll, it’s like if it had already downloaded every package.

    +
    +
    +

    Environment variables

    +

    Question: Which environment variables affect slackroll?

    +

    Answer: TMPDIR lets you specify a temporary directory that will be used to +download files before they are moved to their final locations, which is +/var/slackroll/tmp by default. PAGER lets you specify a pager program, +which is less by default. VISUAL lets you specify a visual editor, which +is used to edit single files and is vim by default. SRDIFF lets you +specify the diff tool that will be used to edit and compare pairs of files, +which is vimdiff by default.

    +
    +
    +

    Syntax highlighting in vimdiff

    +

    Question: Is it possible to disable syntax highlighting in vim, but only +when it’s running in diff mode?

    +

    Answer: Yes. Add this to your ~/.vimrc file, taken from the vim help +documents:

    +
    +
    +
    if &diff
+        syntax off
+endif
    +
    +
    +
    +

    Most frequently used operations

    +

    Question: slackroll has a lot of operations available. Some of them are +mentioned in the tutorial but, in a few words, which operations do you use +more frequently?

    +

    Answer: There is a first group of operations everybody will be running very +frequently: update, changelog, list-transient and upgrade. If you use +a few foreign packages you install and upgrade by hand, you could put +install-foreign in that first group too. Some users, specially the ones +running slackware-current like I do, would have a second group of common +operations they run from time to time: clean-cache, install, remove, +remove-unavailable, install-new and not-installed.

    +
    +
    +

    Comparing slackroll to other tools

    +

    Question: What are the differences between slackroll and other tools like +slapt-get, swaret or slackpkg?

    +

    Answer: That’s a hard question which is better answered by exposing the +features of slackroll. In any case, it should be clarified that you can run +two types of Slackware installations. On the one hand you have stable +releases. If you are going to run a stable release any tool will probably be +useful enough for you, including slackroll. This is because stable releases +are easy to manage, given that the only events they are exposed to are the +release of patches. Any of the existing tools can easily tell you which +patches have been released and let you automate the download and installation +process. It is extremely rare, but not impossible, for a package to be added +to or removed from the tree of a stable release.

    +

    On the other hand, you can be running the rolling release of Slackware which +serves as the testing tree, called slackware(64)-current, or using third-party +repositories. In this case, in my humble opinion, slackroll is the best +tool. This is because slackroll lets you track almost any event happening in +the remote trees, be it packages being added, removed or upgraded, including +the events of a foreign package getting a remote version and the removal of a +package for which a customized version was installed. This is possible thanks +to its package states foundation and the preference for working with two +different states (foreign and frozen) instead of relying on a blacklisting +mechanism. No other tool, as far as I know, can deal with as many events as +slackroll. I’m unable to imagine an event that is not covered by +slackroll.

    +

    Apart from the type of Slackware installation you’re running, there’s the +issue of using third-party repositories. Starting with version 43 and inspired +by community forks of slackpkg, slackroll added support for external +repositories, and performs a decent job at handling them. This makes it a +viable alternative to slapt-get in those situations. Some of those +repositories provide dependency information for packages, which slapt-get +can use, while slackroll doesn’t use it.

    +

    Compared to the shell-based swaret (there was a new swaret being developed +in Perl), slackroll lacks tracking binary dependencies, but it compensates +that lack by letting you search for files in remote packages with the +manifest-related operations. Apart from that, swaret is incredibly slow and +CPU hungry even when it’s only downloading files from the network, and doesn’t +come close to tracking as many events as slackroll. slackroll is, in my +humble opinion, a clear winner over swaret unless you absolutely love the +binary dependency detection and resolution it provides. For me that’s a minor +feature. The Perl implementation was supposed to be basically the same, but +solving the high CPU usage problem. If that’s the case, slackroll would +still be a much better option, in my opinion, because swaret still doesn’t +do glibc upgrades properly, does not detect removed packages, etc.

    +

    slackroll's closest friend is slackpkg, included in the /extra/ tree. +You can think of it like a very much improved slackpkg that works faster, +detects more corner cases and has more features. If you run slackpkg, do not +hesitate to give slackroll a try. The main difference between slackpkg and +slackroll is that the latter, like many other package management tools, +keeps a persistent database of packages on disk. For example, slackpkg uses +a reliable method of parsing the change log to detect when a package has been +added, while slackroll downloads FILELIST.TXT and notices which packages are +new because it didn’t have information on them before. This method also works +with third-party repositories. Another example is slackpkg's clean-system +operation, which prompts you about packages with are not in any official +package set. This operation helps you remove packages that have been removed +from the official Slackware tree, but you need to blacklist your own packages +if you don’t want them to appear in the list. slackroll, on the other hand, +can be told those packages are foreign and it remembers that information.

    +

    Finally, in general, slackroll is at least as fast or faster than any of the +above tools, specially faster than the ones that are big shell scripts +(slackpkg and swaret). It downloads less meta-data than any other, because +it only needs FILELIST.TXT and, for convenience, the new entries from the +change log (indeed, it only downloads the new entries). It detects more +events, which is specially useful when running Slackware’s rolling release, +slackware(64)-current. And it has some useful features no other tool has, +like the operations to detect orphan files, broken symlinks and missing files. +You won’t have to run grep on the contents of /var/log/packages anymore, +because it has a local search operation. It lets you download and search the +MANIFEST list for specific files if, for example, you’re missing a library. It +also lets you choose which package version to install when there are several +ones available. It lets you upgrade individual packages or every upgrade-able +package, install new packages, remove old ones, search for package names or +packages with a given tree component, list alternative versions of packages, +detect and warn you about activity in glibc packages (giving them priority +while upgrading too), etc.

    +
    +
    +
    +
    +
    + + + diff --git a/index.txt b/index.txt new file mode 100644 index 0000000..feffd4c --- /dev/null +++ b/index.txt @@ -0,0 +1,521 @@ +slackroll +========= +:title: slackroll: package or update manager for Slackware systems +:description: Package or update manager for Slackware systems +:keywords: slackroll,slackware,package manager,update manager +:lang: en +:encoding: utf-8 +:doctype: article +:docinfo1: +:toc2: +:theme: flask + +== Target audience == + +`slackroll` is a package or update manager for Slackware systems. It does not +provide dependency checking and uses `pkgtools` to install or upgrade +packages. It's designed to work with official mirrors and third-party +repositories. If you have a Slackware system mainly composed of official +packages, unofficial packages and a few custom packages, `slackroll` can help +you manage it and keep in touch with the remote trees. It tries to know when +new packages appear, when packages are removed and when packages are upgraded. + +== Before you start == + +So you have decided to try `slackroll`. Let me introduce a few concepts so you +don't get lost. + +=== Packages === + +In the following text I'm going to be talking about packages. For package, we +are going to understand a _named piece of software_, without having any +specific version unless I explicitly mention it. A package can be `bash` or +`kdewebdev` or `gcc-gfortran`, for example. + +=== States === + +Each package is in one of several possible states. The program tries to keep a +persistent database that associates each package with its state. When it runs, +it analyzes the list of packages present in your system, the list of remote +packages, and tries to keep the persistent database updated by introducing new +entries, deleting old ones and changing the state of some of those entries. + +There are several possible states for a package, divided in two groups. First, +we have *transient states*. As a user, your job is to make sure no packages +remain in those states for long periods of time. Second, we have the normal +states, in which the different packages should normally be. + +=== Transient states (to be avoided) === + +==== NEW ==== + +A package is in this state when it's present in a remote tree and it wasn't +present before. If you detect you have packages in this state you should +decide if you want to install them or mark them as not installed. This state +lets you see which packages are being added to remote trees. + +==== UNAVAILABLE ==== + +Sorry if this name is somehow confusing. A package is in this state when it's +present in your system, but not in a remote tree. You should decide if you +want to remove them from your system or mark them as foreign packages. This +state lets you see which packages are being removed from remote trees. + +==== OUTDATED ==== + +A package is outdated if it's present in your system and in a remote tree, but +the local version does not match any relevant remote one. The program will try +to upgrade these packages. + +=== Normal states === + +==== INSTALLED ==== + +A package is installed if it's present in your system and in the remote tree, +and the local version is not outdated. Very common state, as you can suppose. + +==== NOT INSTALLED ==== + +A package is not installed if it's a known package which is not present in +your system but exists in a remote tree. It's also a very common state. + +==== FROZEN ==== + +No package will enter the frozen state unless you mark it so. It should be +used for packages present in your system and in a remote tree, but that you +don't want to upgrade automatically. This state can be used for packages which +are not meant to be upgraded automatically or ever, like `aaa_elflibs` and +others, and probably for customized versions of official packages. For +example, my custom build of `freetype` is marked as frozen. You must pay +attention to these packages, as upgrades to them will be silently ignored. You +may find the `list-versions` and `list-outdated-frozen` operations useful to +detect version mismatches between your local copy and the ones in remote +trees. Having a package in the frozen state does not prevent you from using +the install operation to download and install a different version. If the +package ever disappears from the remote trees, it will be marked as +unavailable and you will probably see it. You could continue to use it by +marking it as foreign if you wish. + +==== FOREIGN ==== + +No package will enter the foreign state unless you mark it so. It should be +used for packages that exist in your system but do not have a known remote +origin. For example, the `slackroll` package in my system is marked as +foreign. A foreign package will be marked as installed or outdated if it ever +appears in a remote tree, usually becoming a candidate for upgrading. +Hopefully, you'll notice this fact. You could still use your own version +instead of the remote one by marking it as frozen. + +=== Remote trees === + +`slackroll` works with two types of remote trees. It needs a *mirror*, which +is a URL pointing to a replica of the official Slackware package tree for the +Slackware version you're using. There can be only one mirror and it's selected +with the `set-mirror` operation, as you will see later. + +In addition, `slackroll` can work with a number of additional *third-party +repositories*. These are managed with the `add-repo`, `list-repos` and +`remove-repo` operations, and they will be explained later. + +== Get slackroll == + +link:https://github.com/rg3/slackroll/releases/latest[slackroll] is a +self-contained Python script released to the public domain. You can download a +premade package if available from Github, or grab the source code of the +master branch or any tagged releases as a ZIP archive or by cloning the +repository. + +If you use the source, run the SlackBuild script from the source directory as +root. This will create a package you can install with `installpkg` for the +first time. In the future, you can use `upgradepkg` or even `slackroll` itself +to install newer package versions. Continue reading for more details. + +== Getting started == + +`slackroll` requires `python`, `pkgtools`, `gnupg` (or `gnupg2`), an editor +and diff tool (which are `vim` and `vimdiff` by default (provided by package +`vim`), and a pager (`less` by default) to operate properly. + +It should be noted that you can start using `slackroll` whenever you want, but +my advice is to do it when your system is under control and there are no +upgrades pending. This will give you a chance of configuring the program and +setting the package states properly without making serious mistakes. + +You should first choose a Slackware mirror. In case your mirror of choice +offers access using both FTP and HTTP, prefer HTTP. Take into account +`slackroll` will store downloaded packages in a subdirectory of +`/var/slackroll`, so you will probably need to have a good amount of space +available for them in there. Set the mirror URL with the `set-mirror` +operation. For example: + +----------------------------------------- +slackroll set-mirror +'http://example.org/slackware-current/' +----------------------------------------- + +Great. You are ready to start. Retrieve the remote GPG key to add it to your +key ring. Having the GPG key is required, and it should be safe to do this +step even if the key is already in your key ring. You can also get the key +from the Slackware CD or DVD. The GPG key and the official package signatures +will be downloaded from a primary mirror instead of the mirror you chose, in +order to increase security. + +----------------------------------------- +slackroll import-key +----------------------------------------- + +Retrieve information about the remote packages. You'll have to perform this +step every time a remote tree changes. + +----------------------------------------- +slackroll update +----------------------------------------- + +Finally, you could start checking if there are new packages, unavailable +packages or upgrades. However, the first time you use `slackroll`, any package +not installed in your system will be marked as new, every foreign package will +be marked as unavailable, and every customized package will probably be a +candidate for upgrading if you try to do so. If you have your system under +control (and I hope you do!), you can in most cases blindly mark all new +packages as not installed. There's a command to do it, being a common first +operation. + +----------------------------------------- +slackroll new-not-installed +----------------------------------------- + +In most cases, you can also mark any unavailable packages as foreign. +However, the number of foreign packages is usually quite low, and forgetting +to uninstall a package which has been removed is a very common mistake, so my +advice is to review the list of unavailable packages by hand, detecting which +ones may not be foreign packages and need to be uninstalled. + +----------------------------------------- +slackroll list-unavailable +----------------------------------------- + +Once you've got rid of old packages (using *removepkg* or the `remove` +operation), mark the rest as foreign packages. + +----------------------------------------- +slackroll unavailable-foreign +----------------------------------------- + +Some people like to ``blacklist'' packages so they are not upgraded normally. +Almost always, you want to do this with the package `aaa_elflibs` if it's +present in your system, and maybe with some other packages. If you don't want +them to be upgraded normally, they belong to the frozen state. Mark them as +frozen. The same applies to customized builds of official packages. + +----------------------------------------- +slackroll frozen aaa_elflibs +----------------------------------------- + +The frozen operation accepts a list of packages as its arguments. You don't +need to issue a separate command for each one of them. + +Regarding customized versions of official packages, there are at least three +ways of dealing with them. Some people prefer to give them version names that +match the official ones, despite being customized builds, and keep them in the +installed state. The program will want to upgrade them automatically in that +case, and maybe the official version will overwrite the custom one after an +upgrade, before you rebuild it, if you don't mark it as frozen in the mean +time. Some other people prefer to do the same but putting the package +permanently in the frozen state. In that case, `list-outdated-frozen` is +useful to detect version mismatches between your local copy and the remote +ones. Finally, some other people prefer to give them custom version names, +normally via personalized build numbers that usually include some packager +initials, and mark them as frozen. In that case, `list-versions` can help you +see if your local copy needs to be rebuilt for a new version. + +== Normal operation == + +First off, `slackroll help` will give you a summary of the most common +operations, plus some advice. You can read a brief description of every +supported operation by running `slackroll help all`. Finally, you can get +specific help for an operation using `slackroll help OPERATION`, where +`OPERATION` is the name of the operation you want to get help for. + +This program is not a perfect tool. I think it can handle almost every +situation and be told to do exactly what you want, but reading the change log +and subscribing to the `slackware-security` mailing list is highly +recommended. + +In any case, the most frequent command you will probably run is `slackroll +update`, which should be run whenever the remote tree is changed. Then, you +should read the change log with the `changelog` operation if there are new +entries and, finally, the `list-transient` operation will provide a summary of +activity. There should be no packages in transient states after you're +finished dealing with the changes. + +Watch out for upgrades in the `glibc-solibs`, `sed` and `pkgtools` packages. +They should (almost) always be the first ones to be installed or upgraded in +that order, even before new packages. You can use the `upgrade-key-packages` +operation to upgrade them first. The program will try to inform you about +changes in those packages with a noticeable warning. + +New packages should either be installed selectively with the `install` +operation or all at the same time with `install-new`. New packages which will +not be installed should be put in the not-installed state with +`not-installed`. + +Outdated packages should be upgraded, normally using the `upgrade` operation. + +Unavailable packages could either be foreign packages that you forgot to mark +as such, and should be marked with `foreign`, or packages which have been +removed from the remote tree. In that case, `remove` or `remove-unavailable` +are the operations you will be looking for. + +When installing or upgrading foreign packages, you can use *installpkg* or +*upgradepkg* and then mark them as foreign if needed. However, you can also +install them using the `install-foreign` operation to save time and avoid +problems in the future. + +Also, remember to run the `clean-cache` operation from time to time to get rid +of old and outdated package archives stored in the package cache. + +The order described above is the order in which you should proceed in most +cases. However, sometimes it's not the correct order. That's why it's +important to read the change log to detect possible special cases and read +comments by Patrick Volkerding. If you break that order, slackroll will emit a +warning, but it's only a warning. The choice of what to do is on you. + +=== Kernel upgrades === + +When kernel packages have pending upgrades, you can use two operations created +specifically to handle the situation. `kernel-upgrade` will install the new +kernel packages using `installpkg` instead of `upgradepkg` and then help you +configure your boot loader for the new kernel. This means that, for a small +time period, you will have two versions of the kernel packages installed. +After a successful reboot to the new kernel, you can use the `kernel-clean` +operation to remove the previous versions of those packages. + +=== Third-party repositories === + +As mentioned previously, `slackroll` can also work with a number of +third-party repositories that would normally contain known but unofficial +packages for the Slackware version you're running. If you're going to work +with third-party repositories, I recommend adding them after the initial setup +phase described in this tutorial. + +You can add a new repository with the `add-repo` operation. Once you've added +all the third-party repositories you want, run the `update` operation to +retrieve information about remote packages and the `list-transient` operation +to check the summary of activity. + +For `slackroll` to be able to work with a third-party repository, the +repository needs to provide a `FILELIST.TXT` file in the repository root, and +packages need to be signed with external `.asc` files like the official ones. +These package signatures will be verified by the program when downloading +packages, which means the signature key needs to be in the superuser's +keyring. It's very important to note the `import-key` operation *will not +download GPG keys from third-party repositories as a security measure*. You +need to download the keys by yourself and import them with `gpg --import +KEY_FILE`, where `KEY_FILE` is the path to the GPG key file. Then, you will be +able to download and install packages from the repository. + +The list of third-party repositories can be printed with the `list-repos` +operation, and you can remove a repository from the list with the +`remove-repo` operation, by providing the repo number as listed with +`list-repos`. + +== Feedback == + +I'm all open for good bug reports and general feedback but I'm, as always, +reluctant to change the main program concepts, like adding dependency support +or probably adding more package states. I also know the program currently +can't be used to upgrade the system in non-interactive mode (like calling it +from a cron entry). That is very unlikely to change, because when there's an +upgrade, there's no easy way to decide which version should be installed if a +package has a version in the main tree, another one in `/extra/` and another +one in `/testing/`, so it's always going to need user input. + +If you have a question, you should first read the FAQ. For other questions, +comments or suggestions, link:http://rg3.name/contact.html[contact me] by +email, or report an issue in the +link:https://github.com/rg3/slackroll/issues[issue tracker]. Keep in mind I'm +using the program under `slackware64-current`. If you detect a problem under +another version, please report it as soon as possible because it may go +unnoticed to me. + +== Frequently Asked Questions == + +=== Packages with nonstandard names === + +*Question*: While attempting to setup `slackroll` I get _ERROR: Nonstandard +package name: _. How can I solve this problem? + +*Answer*: It seems some people are using packages that don't follow the +Slackware package name convention of _name-version-arch-build_. I think it is +wrong to have a package that doesn't follow the convention. `slackroll` needs +to parse the package names to extract the different components. These packages +make it very difficult or impossible, so they are rejected. There is no way to +analyze those names properly in a predictable way. The problem should be +solved by removing that package, renaming the package archive to have a +standard name and then installing it again. + +Some examples of invalid package names I have seen reported are +`pyfloppy-1.6-noarch.2AS`, `gammapage-0.5.i486-1AS` and +`scons-0.96.1-1.noarch`. + +Remember: it doesn't matter if it's an official package or a foreign or custom +one. It should follow the naming convention. + +=== Saving the list of URLs === + +*Question*: Using the `urls` or `urls-upgrades` operation I want to save the +URL list to a text file. However, if I use shell redirections and `slackroll` +prompts me to select a specific package version, I can't see the questions. Is +there an easy way of doing this? + +*Answer*: Yes. Pipe the output of `slackroll` to `tee urls.txt` and then edit +the file to remove the extra lines. + +=== Coordinating with rsync === + +*Question*: I normally get my packages using rsync, so as to keep a local copy +of the remote tree. Can I coordinate this with `slackroll`? + +*Answer*: Yes. I would use a script like the following one, replacing the +chunks in curly braces by the appropriate contents. + +-------------------------------------------------- +SLACKROLL_DIR=/var/slackroll +LOCAL_MIRROR_DIR={ path to local copy of the remote trees } +{ rsync command(s) } +cd $SLACKROLL_DIR +slackroll update +rm -f packages/* +for pkg in $( slackroll remote-paths ); do + ln -sf $LOCAL_MIRROR_DIR/$pkg ./packages +done +-------------------------------------------------- + +This will synchronize your local copy of the remote trees and then populate +the `slackroll` package cache with symbolic links to the package archives +located inside your local copy of the Slackware remote trees. From the point +of view of `slackroll`, it's like if it had already downloaded every package. + +=== Environment variables === + +*Question*: Which environment variables affect `slackroll`? + +*Answer*: `TMPDIR` lets you specify a temporary directory that will be used to +download files before they are moved to their final locations, which is +`/var/slackroll/tmp` by default. `PAGER` lets you specify a pager program, +which is `less` by default. `VISUAL` lets you specify a visual editor, which +is used to edit single files and is `vim` by default. `SRDIFF` lets you +specify the diff tool that will be used to edit and compare pairs of files, +which is `vimdiff` by default. + +=== Syntax highlighting in vimdiff === + +*Question*: Is it possible to disable syntax highlighting in `vim`, but only +when it's running in diff mode? + +*Answer*: Yes. Add this to your `~/.vimrc` file, taken from the `vim` help +documents: + +------------------------ +if &diff + syntax off +endif +------------------------ + +=== Most frequently used operations === + +*Question*: `slackroll` has a lot of operations available. Some of them are +mentioned in the tutorial but, in a few words, which operations do you use +more frequently? + +*Answer*: There is a first group of operations everybody will be running very +frequently: `update`, `changelog`, `list-transient` and `upgrade`. If you use +a few foreign packages you install and upgrade by hand, you could put +`install-foreign` in that first group too. Some users, specially the ones +running `slackware-current` like I do, would have a second group of common +operations they run from time to time: `clean-cache`, `install`, `remove`, +`remove-unavailable`, `install-new` and `not-installed`. + +=== Comparing `slackroll` to other tools === + +*Question*: What are the differences between `slackroll` and other tools like +`slapt-get`, `swaret` or `slackpkg`? + +*Answer*: That's a hard question which is better answered by exposing the +features of `slackroll`. In any case, it should be clarified that you can run +two types of Slackware installations. On the one hand you have stable +releases. If you are going to run a stable release any tool will probably be +useful enough for you, including `slackroll`. This is because stable releases +are easy to manage, given that the only events they are exposed to are the +release of patches. Any of the existing tools can easily tell you which +patches have been released and let you automate the download and installation +process. It is extremely rare, but not impossible, for a package to be added +to or removed from the tree of a stable release. + +On the other hand, you can be running the rolling release of Slackware which +serves as the testing tree, called slackware(64)-current, or using third-party +repositories. In this case, in my humble opinion, `slackroll` is the best +tool. This is because `slackroll` lets you track almost any event happening in +the remote trees, be it packages being added, removed or upgraded, including +the events of a foreign package getting a remote version and the removal of a +package for which a customized version was installed. This is possible thanks +to its package states foundation and the preference for working with two +different states (foreign and frozen) instead of relying on a blacklisting +mechanism. No other tool, as far as I know, can deal with as many events as +`slackroll`. I'm unable to imagine an event that is not covered by +`slackroll`. + +Apart from the type of Slackware installation you're running, there's the +issue of using third-party repositories. Starting with version 43 and inspired +by community forks of `slackpkg`, `slackroll` added support for external +repositories, and performs a decent job at handling them. This makes it a +viable alternative to *slapt-get* in those situations. Some of those +repositories provide dependency information for packages, which `slapt-get` +can use, while `slackroll` doesn't use it. + +Compared to the shell-based *swaret* (there was a new `swaret` being developed +in Perl), `slackroll` lacks tracking binary dependencies, but it compensates +that lack by letting you search for files in remote packages with the +manifest-related operations. Apart from that, `swaret` is incredibly slow and +CPU hungry even when it's only downloading files from the network, and doesn't +come close to tracking as many events as `slackroll`. `slackroll` is, in my +humble opinion, a clear winner over `swaret` unless you absolutely love the +binary dependency detection and resolution it provides. For me that's a minor +feature. The Perl implementation was supposed to be basically the same, but +solving the high CPU usage problem. If that's the case, `slackroll` would +still be a much better option, in my opinion, because `swaret` still doesn't +do `glibc` upgrades properly, does not detect removed packages, etc. + +`slackroll`'s closest friend is *slackpkg*, included in the `/extra/` tree. +You can think of it like a very much improved `slackpkg` that works faster, +detects more corner cases and has more features. If you run `slackpkg`, do not +hesitate to give `slackroll` a try. The main difference between `slackpkg` and +`slackroll` is that the latter, like many other package management tools, +keeps a persistent database of packages on disk. For example, `slackpkg` uses +a reliable method of parsing the change log to detect when a package has been +added, while `slackroll` downloads FILELIST.TXT and notices which packages are +new because it didn't have information on them before. This method also works +with third-party repositories. Another example is `slackpkg`'s clean-system +operation, which prompts you about packages with are not in any official +package set. This operation helps you remove packages that have been removed +from the official Slackware tree, but you need to blacklist your own packages +if you don't want them to appear in the list. `slackroll`, on the other hand, +can be told those packages are foreign and it _remembers_ that information. + +Finally, in general, `slackroll` is at least as fast or faster than any of the +above tools, specially faster than the ones that are big shell scripts +(`slackpkg` and `swaret`). It downloads less meta-data than any other, because +it only needs `FILELIST.TXT` and, for convenience, the new entries from the +change log (indeed, it only downloads the new entries). It detects more +events, which is specially useful when running Slackware's rolling release, +_slackware(64)-current_. And it has some useful features no other tool has, +like the operations to detect orphan files, broken symlinks and missing files. +You won't have to run `grep` on the contents of `/var/log/packages` anymore, +because it has a local search operation. It lets you download and search the +MANIFEST list for specific files if, for example, you're missing a library. It +also lets you choose which package version to install when there are several +ones available. It lets you upgrade individual packages or every upgrade-able +package, install new packages, remove old ones, search for package names or +packages with a given tree component, list alternative versions of packages, +detect and warn you about activity in `glibc` packages (giving them priority +while upgrading too), etc. diff --git a/slackroll.css b/slackroll.css deleted file mode 100644 index 08b1dd2..0000000 --- a/slackroll.css +++ /dev/null @@ -1,83 +0,0 @@ -body { - font-family: sans-serif; - font-size: medium; - background: white; - margin-bottom: 5ex; -} - -.title { - text-align: center; - font-size: xx-large; - font-weight: bold; - width: 90%; - margin: 0 auto; - background-color: #dd5500; - color: white; - border-bottom: 3px solid #f38630; - border-top: 3px solid #f38630; - padding: 0.5ex; -} - -.subtitle { - font-size: x-large; - text-align: center; - font-weight: bold; - color: #dd5500; - margin: 1ex; -} - -.navbar { - text-align: center; - font-size: small; -} - -h1 { - display: block; - width: 80%; - margin-top: 2ex; - margin-left: auto; - margin-right: auto; - padding-left: 0.5ex; - font-size: x-large; - color: #006699; - border-top: 1px solid #a7dbd8; - border-left: 10px solid #a7dbd8; -} - -h2 { - display: block; - margin: 1ex auto; - width: 70%; - font-weight: bold; - font-size: large; - color: black; -} - -h3 { - display: block; - margin-top: 2ex; - margin-left: auto; - margin-right: auto; - margin-bottom: 0; - width: 60%; - font-weight: bold; - font-size: medium; - color: #444444; -} - -p { - display: block; - margin: 1ex auto; - width: 60%; - text-align: justify; -} - -code { - color: #880000; -} - -pre { - display: block; - margin: 0 auto; - width: 60%; -} diff --git a/tutorial.html b/tutorial.html index 33ac8ab..7392da2 100644 --- a/tutorial.html +++ b/tutorial.html @@ -1,166 +1,14 @@ - - -slackroll: Introduction and Tutorial - - - - -
    slackroll
    -
    Introduction and Tutorial
    -
    Also available: FAQ RSS feed
    - -

    Target audience

    - -

    slackroll is a package or update manager for Slackware systems. It does not provide dependency checking and uses pkgtools to install or upgrade packages. It’s designed to work with official mirrors and third-party repositories. If you have a Slackware system mainly composed of official packages, unofficial packages and a few custom packages, slackroll can help you manage it and keep in touch with the remote trees. It tries to know when new packages appear, when packages are removed and when packages are upgraded.

    - -

    Before you start

    - -

    So you have decided to try slackroll. Let me introduce a few concepts so you don’t get lost.

    - -

    Packages

    - -

    In the following text I’m going to be talking about packages. For package, we are going to understand a named piece of software, without having any specific version unless I explicitly mention it. A package can be bash or kdewebdev or gcc-gfortran, for example.

    - -

    States

    - -

    Each package is in one of several possible states. The program tries to keep a persistent database that associates each package with its state. When it runs, it analyzes the list of packages present in your system, the list of remote packages, and tries to keep the persistent database updated by introducing new entries, deleting old ones and changing the state of some of those entries.

    - -

    There are several possible states for a package, divided in two groups. First, we have transient states. As a user, your job is to make sure no packages remain in those states for long periods of time. Second, we have the normal states, in which the different packages should normally be.

    - -

    Transient states (to be avoided)

    - -

    NEW

    - -

    A package is in this state when it’s present in a remote tree and it wasn’t present before. If you detect you have packages in this state you should decide if you want to install them or mark them as not installed. This state lets you see which packages are being added to remote trees.

    - -

    UNAVAILABLE

    - -

    Sorry if this name is somehow confusing. A package is in this state when it’s present in your system, but not in a remote tree. You should decide if you want to remove them from your system or mark them as foreign packages. This state lets you see which packages are being removed from remote trees.

    - -

    OUTDATED

    - -

    A package is outdated if it’s present in your system and in a remote tree, but the local version does not match any relevant remote one. The program will try to upgrade these packages.

    - -

    Normal states

    - -

    INSTALLED

    - -

    A package is installed if it’s present in your system and in the remote tree, and the local version is not outdated. Very common state, as you can suppose.

    - -

    NOT INSTALLED

    - -

    A package is not installed if it’s a known package which is not present in your system but exists in a remote tree. It’s also a very common state.

    - -

    FROZEN

    - -

    No package will enter the frozen state unless you mark it so. It should be used for packages present in your system and in a remote tree, but that you don’t want to upgrade automatically. This state can be used for packages which are not meant to be upgraded automatically or ever, like aaa_elflibs and others, and probably for customized versions of official packages. For example, my custom build of freetype is marked as frozen. You must pay attention to these packages, as upgrades to them will be silently ignored. You may find the list-versions and list-outdated-frozen operations useful to detect version mismatches between your local copy and the ones in remote trees. Having a package in the frozen state does not prevent you from using the install operation to download and install a different version. If the package ever disappears from the remote trees, it will be marked as unavailable and you will probably see it. You could continue to use it by marking it as foreign if you wish.

    - -

    FOREIGN

    - -

    No package will enter the foreign state unless you mark it so. It should be used for packages that exist in your system but do not have a known remote origin. For example, the slackroll package in my system is marked as foreign. A foreign package will be marked as installed or outdated if it ever appears in a remote tree, usually becoming a candidate for upgrading. Hopefully, you’ll notice this fact. You could still use your own version instead of the remote one by marking it as frozen.

    - -

    Remote trees

    - -

    slackroll works with two types of remote trees. It needs a mirror, which is a URL pointing to a replica of the official Slackware package tree for the Slackware version you’re using. There can be only one mirror and it’s selected with the set-mirror operation, as you will see later.

    - -

    In addition, slackroll can work with a number of additional third-party repositories. These are managed with the add-repo, list-repos and remove-repo operations, and they will be explained later.

    - -

    Get slackroll

    - -

    slackroll is a self-contained Python script released to the public domain. You can download the source code of the master branch or any tagged releases as a ZIP archive from Github, or by cloning the repository. Once you have access to the plain source files, run the SlackBuild script from the source directory as root. This will create a package you can install with installpkg for the first time. In the future, you can use upgradepkg or even slackroll itself to install newer package versions. Continue reading for more details.

    - -

    Getting started

    - -

    slackroll requires python, pkgtools, gnupg (or gnupg2), an editor and diff tool (which are vim and vimdiff by default (provided by package vim), and a pager (less by default) to operate properly.

    - -

    It should be noted that you can start using slackroll whenever you want, but my advice is to do it when your system is under control and there are no upgrades pending. This will give you a chance of configuring the program and setting the package states properly without making serious mistakes.

    - -

    You should first choose a Slackware mirror. In case your mirror of choice offers access using both FTP and HTTP, prefer HTTP. Take into account slackroll will store downloaded packages in a subdirectory of /var/slackroll, so you will probably need to have a good amount of space available for them in there. Set the mirror URL with the set-mirror operation. For example:

    - -

    -slackroll set-mirror 'http://example.org/slackware-current/' -

    - -

    Great. You are ready to start. Retrieve the remote GPG key to add it to your key ring. Having the GPG key is required, and it should be safe to do this step even if the key is already in your key ring. You can also get the key from the Slackware CD or DVD. The GPG key and the official package signatures will be downloaded from a primary mirror instead of the mirror you chose, in order to increase security.

    - -

    -slackroll import-key -

    - -

    Retrieve information about the remote packages. You’ll have to perform this step every time a remote tree changes.

    - -

    -slackroll update -

    - -

    Finally, you could start checking if there are new packages, unavailable packages or upgrades. However, the first time you use slackroll, any package not installed in your system will be marked as new, every foreign package will be marked as unavailable, and every customized package will probably be a candidate for upgrading if you try to do so. If you have your system under control (and I hope you do!), you can in most cases blindly mark all new packages as not installed. There’s a command to do it, being a common first operation.

    - -

    -slackroll new-not-installed -

    - -

    In most cases, you can also mark any unavailable packages as foreign. However, the number of foreign packages is usually quite low, and forgetting to uninstall a package which has been removed is a very common mistake, so my advice is to review the list of unavailable packages by hand, detecting which ones may not be foreign packages and need to be uninstalled.

    - -

    -slackroll list-unavailable -

    - -

    Once you’ve got rid of old packages (using removepkg or the remove operation), mark the rest as foreign packages.

    - -

    -slackroll unavailable-foreign -

    - -

    Some people like to “blacklist” packages so they are not upgraded normally. Almost always, you want to do this with the package aaa_elflibs if it’s present in your system, and maybe with some other packages. If you don’t want them to be upgraded normally, they belong to the frozen state. Mark them as frozen. The same applies to customized builds of official packages.

    - -

    -slackroll frozen aaa_elflibs -

    - -

    The frozen operation accepts a list of packages as its arguments. You don’t need to issue a separate command for each one of them.

    - -

    Regarding customized versions of official packages, there are at least three ways of dealing with them. Some people prefer to give them version names that match the official ones, despite being customized builds, and keep them in the installed state. The program will want to upgrade them automatically in that case, and maybe the official version will overwrite the custom one after an upgrade, before you rebuild it, if you don’t mark it as frozen in the mean time. Some other people prefer to do the same but putting the package permanently in the frozen state. In that case, list-outdated-frozen is useful to detect version mismatches between your local copy and the remote ones. Finally, some other people prefer to give them custom version names, normally via personalized build numbers that usually include some packager initials, and mark them as frozen. In that case, list-versions can help you see if your local copy needs to be rebuilt for a new version.

    - -

    Normal operation

    - -

    First off, slackroll help will give you a summary of the most common operations, plus some advice. You can read a brief description of every supported operation by running slackroll help all. Finally, you can get specific help for an operation using slackroll help OPERATION, where OPERATION is the name of the operation you want to get help for.

    - -

    This program is not a perfect tool. I think it can handle almost every situation and be told to do exactly what you want, but reading the change log and subscribing to the slackware-security mailing list is highly recommended.

    - -

    In any case, the most frequent command you will probably run is slackroll update, which should be run whenever the remote tree is changed. Then, you should read the change log with the changelog operation if there are new entries and, finally, the list-transient operation will provide a summary of activity. There should be no packages in transient states after you’re finished dealing with the changes.

    - -

    Watch out for upgrades in the glibc-solibs, sed and pkgtools packages. They should (almost) always be the first ones to be installed or upgraded in that order, even before new packages. You can use the upgrade-key-packages operation to upgrade them first. The program will try to inform you about changes in those packages with a noticeable warning.

    - -

    New packages should either be installed selectively with the install operation or all at the same time with install-new. New packages which will not be installed should be put in the not-installed state with not-installed.

    - -

    Outdated packages should be upgraded, normally using the upgrade operation.

    - -

    Unavailable packages could either be foreign packages that you forgot to mark as such, and should be marked with foreign, or packages which have been removed from the remote tree. In that case, remove or remove-unavailable are the operations you will be looking for.

    - -

    When installing or upgrading foreign packages, you can use installpkg or upgradepkg and then mark them as foreign if needed. However, you can also install them using the install-foreign operation to save time and avoid problems in the future.

    - -

    Also, remember to run the clean-cache operation from time to time to get rid of old and outdated package archives stored in the package cache.

    - -

    The order described above is the order in which you should proceed in most cases. However, sometimes it’s not the correct order. That’s why it’s important to read the change log to detect possible special cases and read comments by Patrick Volkerding. If you break that order, slackroll will emit a warning, but it’s only a warning. The choice of what to do is on you.

    - -

    Kernel upgrades

    - -

    When kernel packages have pending upgrades, you can use two operations created specifically to handle the situation. kernel-upgrade will install the new kernel packages using installpkg instead of upgradepkg and then help you configure your boot loader for the new kernel. This means that, for a small time period, you will have two versions of the kernel packages installed. After a successful reboot to the new kernel, you can use the kernel-clean operation to remove the previous versions of those packages.

    - -

    Third-party repositories

    - -

    As mentioned previously, slackroll can also work with a number of third-party repositories that would normally contain known but unofficial packages for the Slackware version you’re running. If you’re going to work with third-party repositories, I recommend adding them after the initial setup phase described in this tutorial.

    - -

    You can add a new repository with the add-repo operation. Once you’ve added all the third-party repositories you want, run the update operation to retrieve information about remote packages and the list-transient operation to check the summary of activity.

    - -

    For slackroll to be able to work with a third-party repository, the repository needs to provide a FILELIST.TXT file in the repository root, and packages need to be signed with external .asc files like the official ones. These package signatures will be verified by the program when downloading packages, which means the signature key needs to be in the superuser’s keyring. It’s very important to note the import-key operation will not download GPG keys from third-party repositories as a security measure. You need to download the keys by yourself and import them with gpg --import KEY_FILE, where KEY_FILE is the path to the GPG key file. Then, you will be able to download and install packages from the repository.

    - -

    The list of third-party repositories can be printed with the list-repos operation, and you can remove a repository from the list with the remove-repo operation, by providing the repo number as listed with list-repos.

    - -

    Feedback, questions, bug reports

    - -

    I’m all open for good bug reports and general feedback but I’m, as always, reluctant to change the main program concepts, like adding dependency support or probably adding more package states. I also know the program currently can’t be used to upgrade the system in non-interactive mode (like calling it from a cron entry). That is very unlikely to change, because when there’s an upgrade, there’s no easy way to decide which version should be installed if a package has a version in the main tree, another one in /extra/ and another one in /testing/, so it’s always going to need user input.

    - -

    If you have a question, you should first read the FAQ. For other questions, comments or suggestions, contact me by email, or report an issue in the issue tracker. Keep in mind I’m using the program under slackware64-current. If you detect a problem under another version, please report it as soon as possible because it may go unnoticed to me.

    - + + + + + + + Page Redirection + + + If you are not redirected automatically, follow this link + diff --git a/tutorial.php b/tutorial.php deleted file mode 100644 index 570dd9a..0000000 --- a/tutorial.php +++ /dev/null @@ -1,34 +0,0 @@ - - -slackroll: Introduction and Tutorial - - - - -
    slackroll
    -
    Introduction and Tutorial
    -
    Also available: FAQ RSS feed
    - -TextileThis($contents); - -// For untrusted user input, use TextileRestricted instead: -// echo $textile->TextileRestricted($in); - - -?> - - - diff --git a/tutorial.textile b/tutorial.textile deleted file mode 100644 index 42e2619..0000000 --- a/tutorial.textile +++ /dev/null @@ -1,153 +0,0 @@ -h1. Target audience - -@slackroll@ is a package or update manager for Slackware systems. It does not provide dependency checking and uses @pkgtools@ to install or upgrade packages. It's designed to work with official mirrors and third-party repositories. If you have a Slackware system mainly composed of official packages, unofficial packages and a few custom packages, @slackroll@ can help you manage it and keep in touch with the remote trees. It tries to know when new packages appear, when packages are removed and when packages are upgraded. - -h1. Before you start - -So you have decided to try @slackroll@. Let me introduce a few concepts so you don't get lost. - -h2. Packages - -In the following text I'm going to be talking about packages. For package, we are going to understand a _named piece of software_, without having any specific version unless I explicitly mention it. A package can be @bash@ or @kdewebdev@ or @gcc-gfortran@, for example. - -h2. States - -Each package is in one of several possible states. The program tries to keep a persistent database that associates each package with its state. When it runs, it analyzes the list of packages present in your system, the list of remote packages, and tries to keep the persistent database updated by introducing new entries, deleting old ones and changing the state of some of those entries. - -There are several possible states for a package, divided in two groups. First, we have *transient states*. As a user, your job is to make sure no packages remain in those states for long periods of time. Second, we have the normal states, in which the different packages should normally be. - -h2. Transient states (to be avoided) - -h3. NEW - -A package is in this state when it's present in a remote tree and it wasn't present before. If you detect you have packages in this state you should decide if you want to install them or mark them as not installed. This state lets you see which packages are being added to remote trees. - -h3. UNAVAILABLE - -Sorry if this name is somehow confusing. A package is in this state when it's present in your system, but not in a remote tree. You should decide if you want to remove them from your system or mark them as foreign packages. This state lets you see which packages are being removed from remote trees. - -h3. OUTDATED - -A package is outdated if it's present in your system and in a remote tree, but the local version does not match any relevant remote one. The program will try to upgrade these packages. - -h2. Normal states - -h3. INSTALLED - -A package is installed if it's present in your system and in the remote tree, and the local version is not outdated. Very common state, as you can suppose. - -h3. NOT INSTALLED - -A package is not installed if it's a known package which is not present in your system but exists in a remote tree. It's also a very common state. - -h3. FROZEN - -No package will enter the frozen state unless you mark it so. It should be used for packages present in your system and in a remote tree, but that you don't want to upgrade automatically. This state can be used for packages which are not meant to be upgraded automatically or ever, like @aaa_elflibs@ and others, and probably for customized versions of official packages. For example, my custom build of @freetype@ is marked as frozen. You must pay attention to these packages, as upgrades to them will be silently ignored. You may find the @list-versions@ and @list-outdated-frozen@ operations useful to detect version mismatches between your local copy and the ones in remote trees. Having a package in the frozen state does not prevent you from using the install operation to download and install a different version. If the package ever disappears from the remote trees, it will be marked as unavailable and you will probably see it. You could continue to use it by marking it as foreign if you wish. - -h3. FOREIGN - -No package will enter the foreign state unless you mark it so. It should be used for packages that exist in your system but do not have a known remote origin. For example, the @slackroll@ package in my system is marked as foreign. A foreign package will be marked as installed or outdated if it ever appears in a remote tree, usually becoming a candidate for upgrading. Hopefully, you'll notice this fact. You could still use your own version instead of the remote one by marking it as frozen. - -h2. Remote trees - -@slackroll@ works with two types of remote trees. It needs a *mirror*, which is a URL pointing to a replica of the official Slackware package tree for the Slackware version you're using. There can be only one mirror and it's selected with the @set-mirror@ operation, as you will see later. - -In addition, @slackroll@ can work with a number of additional *third-party repositories*. These are managed with the @add-repo@, @list-repos@ and @remove-repo@ operations, and they will be explained later. - -h1. Get slackroll - -"slackroll":http://github.com/rg3/slackroll/ is a self-contained Python script released to the public domain. You can download the source code of the master branch or any tagged releases as a ZIP archive from Github, or by cloning the repository. Once you have access to the plain source files, run the SlackBuild script from the source directory as root. This will create a package you can install with @installpkg@ for the first time. In the future, you can use @upgradepkg@ or even @slackroll@ itself to install newer package versions. Continue reading for more details. - -h1. Getting started - -@slackroll@ requires @python@, @pkgtools@, @gnupg@ (or @gnupg2@), an editor and diff tool (which are @vim@ and @vimdiff@ by default (provided by package @vim@), and a pager (@less@ by default) to operate properly. - -It should be noted that you can start using @slackroll@ whenever you want, but my advice is to do it when your system is under control and there are no upgrades pending. This will give you a chance of configuring the program and setting the package states properly without making serious mistakes. - -You should first choose a Slackware mirror. In case your mirror of choice offers access using both FTP and HTTP, prefer HTTP. Take into account @slackroll@ will store downloaded packages in a subdirectory of @/var/slackroll@, so you will probably need to have a good amount of space available for them in there. Set the mirror URL with the @set-mirror@ operation. For example: - - -slackroll set-mirror 'http://example.org/slackware-current/' - - -Great. You are ready to start. Retrieve the remote GPG key to add it to your key ring. Having the GPG key is required, and it should be safe to do this step even if the key is already in your key ring. You can also get the key from the Slackware CD or DVD. The GPG key and the official package signatures will be downloaded from a primary mirror instead of the mirror you chose, in order to increase security. - - -slackroll import-key - - -Retrieve information about the remote packages. You'll have to perform this step every time a remote tree changes. - - -slackroll update - - -Finally, you could start checking if there are new packages, unavailable packages or upgrades. However, the first time you use @slackroll@, any package not installed in your system will be marked as new, every foreign package will be marked as unavailable, and every customized package will probably be a candidate for upgrading if you try to do so. If you have your system under control (and I hope you do!), you can in most cases blindly mark all new packages as not installed. There's a command to do it, being a common first operation. - - -slackroll new-not-installed - - -In most cases, you can also mark any unavailable packages as foreign. However, the number of foreign packages is usually quite low, and forgetting to uninstall a package which has been removed is a very common mistake, so my advice is to review the list of unavailable packages by hand, detecting which ones may not be foreign packages and need to be uninstalled. - - -slackroll list-unavailable - - -Once you've got rid of old packages (using *removepkg* or the @remove@ operation), mark the rest as foreign packages. - - -slackroll unavailable-foreign - - -Some people like to "blacklist" packages so they are not upgraded normally. Almost always, you want to do this with the package @aaa_elflibs@ if it's present in your system, and maybe with some other packages. If you don't want them to be upgraded normally, they belong to the frozen state. Mark them as frozen. The same applies to customized builds of official packages. - - -slackroll frozen aaa_elflibs - - -The frozen operation accepts a list of packages as its arguments. You don't need to issue a separate command for each one of them. - -Regarding customized versions of official packages, there are at least three ways of dealing with them. Some people prefer to give them version names that match the official ones, despite being customized builds, and keep them in the installed state. The program will want to upgrade them automatically in that case, and maybe the official version will overwrite the custom one after an upgrade, before you rebuild it, if you don't mark it as frozen in the mean time. Some other people prefer to do the same but putting the package permanently in the frozen state. In that case, @list-outdated-frozen@ is useful to detect version mismatches between your local copy and the remote ones. Finally, some other people prefer to give them custom version names, normally via personalized build numbers that usually include some packager initials, and mark them as frozen. In that case, @list-versions@ can help you see if your local copy needs to be rebuilt for a new version. - -h1. Normal operation - -First off, @slackroll help@ will give you a summary of the most common operations, plus some advice. You can read a brief description of every supported operation by running @slackroll help all@. Finally, you can get specific help for an operation using @slackroll help OPERATION@, where @OPERATION@ is the name of the operation you want to get help for. - -This program is not a perfect tool. I think it can handle almost every situation and be told to do exactly what you want, but reading the change log and subscribing to the @slackware-security@ mailing list is highly recommended. - -In any case, the most frequent command you will probably run is @slackroll update@, which should be run whenever the remote tree is changed. Then, you should read the change log with the @changelog@ operation if there are new entries and, finally, the @list-transient@ operation will provide a summary of activity. There should be no packages in transient states after you're finished dealing with the changes. - -Watch out for upgrades in the @glibc-solibs@, @sed@ and @pkgtools@ packages. They should (almost) always be the first ones to be installed or upgraded in that order, even before new packages. You can use the @upgrade-key-packages@ operation to upgrade them first. The program will try to inform you about changes in those packages with a noticeable warning. - -New packages should either be installed selectively with the @install@ operation or all at the same time with @install-new@. New packages which will not be installed should be put in the not-installed state with @not-installed@. - -Outdated packages should be upgraded, normally using the @upgrade@ operation. - -Unavailable packages could either be foreign packages that you forgot to mark as such, and should be marked with @foreign@, or packages which have been removed from the remote tree. In that case, @remove@ or @remove-unavailable@ are the operations you will be looking for. - -When installing or upgrading foreign packages, you can use *installpkg* or *upgradepkg* and then mark them as foreign if needed. However, you can also install them using the @install-foreign@ operation to save time and avoid problems in the future. - -Also, remember to run the @clean-cache@ operation from time to time to get rid of old and outdated package archives stored in the package cache. - -The order described above is the order in which you should proceed in most cases. However, sometimes it's not the correct order. That's why it's important to read the change log to detect possible special cases and read comments by Patrick Volkerding. If you break that order, slackroll will emit a warning, but it's only a warning. The choice of what to do is on you. - -h2. Kernel upgrades - -When kernel packages have pending upgrades, you can use two operations created specifically to handle the situation. @kernel-upgrade@ will install the new kernel packages using @installpkg@ instead of @upgradepkg@ and then help you configure your boot loader for the new kernel. This means that, for a small time period, you will have two versions of the kernel packages installed. After a successful reboot to the new kernel, you can use the @kernel-clean@ operation to remove the previous versions of those packages. - -h2. Third-party repositories - -As mentioned previously, @slackroll@ can also work with a number of third-party repositories that would normally contain known but unofficial packages for the Slackware version you're running. If you're going to work with third-party repositories, I recommend adding them after the initial setup phase described in this tutorial. - -You can add a new repository with the @add-repo@ operation. Once you've added all the third-party repositories you want, run the @update@ operation to retrieve information about remote packages and the @list-transient@ operation to check the summary of activity. - -For @slackroll@ to be able to work with a third-party repository, the repository needs to provide a @FILELIST.TXT@ file in the repository root, and packages need to be signed with external @.asc@ files like the official ones. These package signatures will be verified by the program when downloading packages, which means the signature key needs to be in the superuser's keyring. It's very important to note the @import-key@ operation *will not download GPG keys from third-party repositories as a security measure*. You need to download the keys by yourself and import them with @gpg --import KEY_FILE@, where @KEY_FILE@ is the path to the GPG key file. Then, you will be able to download and install packages from the repository. - -The list of third-party repositories can be printed with the @list-repos@ operation, and you can remove a repository from the list with the @remove-repo@ operation, by providing the repo number as listed with @list-repos@. - -h1. Feedback, questions, bug reports - -I'm all open for good bug reports and general feedback but I'm, as always, reluctant to change the main program concepts, like adding dependency support or probably adding more package states. I also know the program currently can't be used to upgrade the system in non-interactive mode (like calling it from a cron entry). That is very unlikely to change, because when there's an upgrade, there's no easy way to decide which version should be installed if a package has a version in the main tree, another one in @/extra/@ and another one in @/testing/@, so it's always going to need user input. - -If you have a question, you should first read the "FAQ":faq.html. For other questions, comments or suggestions, "contact me":http://rg3.name/contact.html by email, or report an issue in the issue tracker. Keep in mind I'm using the program under @slackware64-current@. If you detect a problem under another version, please report it as soon as possible because it may go unnoticed to me.