summaryrefslogtreecommitdiff
path: root/Master/tlpkg/doc
diff options
context:
space:
mode:
authorNorbert Preining <preining@logic.at>2007-06-16 16:22:16 +0000
committerNorbert Preining <preining@logic.at>2007-06-16 16:22:16 +0000
commitd4eefe7213116b2b11dbfa09d39b54d6470203ca (patch)
treed0fa75c399323763c095e1ac6d77ae6766ab88e5 /Master/tlpkg/doc
parentad7c8ab6419951c6e744c47c4be81bef897a18b3 (diff)
move new-infra to Master/tlpkg
rename stuff create list files tlsrc for all packages (also schemes) git-svn-id: svn://tug.org/texlive/trunk@4439 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/tlpkg/doc')
-rw-r--r--Master/tlpkg/doc/Perl-API.txt242
-rw-r--r--Master/tlpkg/doc/TODO137
-rw-r--r--Master/tlpkg/doc/specification.txt141
3 files changed, 520 insertions, 0 deletions
diff --git a/Master/tlpkg/doc/Perl-API.txt b/Master/tlpkg/doc/Perl-API.txt
new file mode 100644
index 00000000000..ee1e3e69443
--- /dev/null
+++ b/Master/tlpkg/doc/Perl-API.txt
@@ -0,0 +1,242 @@
+API for Perl Modules for new infra
+==================================
+
+Module TeXLive::TLPSRC
+----------------------
+
+Constructor:
+ TeXLive::TLPSRC->new;
+ TeXLive::TLPSRC->new( name => "foobar", shortdesc => "The foobar package", ...);
+
+Input/Output
+ $tlsrc->from_file("package.tlsrc");
+ $tlsrc->writeout
+ without arg to stdout
+ with arg to filehandle
+
+Read/Write functions (with argument set, without arg read)
+
+ $tlsrc->name
+ $tlsrc->category
+ $tlsrc->shortdesc
+ $tlsrc->longdesc
+ $tlsrc->catalogue
+ $tlsrc->srcpatterns
+ $tlsrc->docpatterns
+ $tlsrc->runpatterns
+ $tlsrc->binpatterns
+ $tlsrc->depends
+ $tlsrc->executes
+
+Generation function
+ $tlp = $tlsrc->make_tlpobj($tltree);
+ generates a TeXLive::TLPOBJ object from itself and
+ a TeXLive::TLTREE object (see below)
+
+
+Module TeXLive::TLPOBJ
+----------------------
+
+Package variables:
+ &TeXLive::TLPOBJ->zipdir
+ set/returns the default location for created zip files
+
+Constructur:
+ TeXLive::TLPOBJ->new;
+ TeXLive::TLPOBJ->new( name => "foobar", ...);
+
+Input/Output
+ $tlp->from_file("package.tlp");
+ reads from file, only one tlp allowed in file
+ $tlp->from_fh($filehandle [, $multi] );
+ reads from $filehandle
+ if $multi is undefined (ie not given) then multiple tlp
+ in the same file are treated as errors
+ if $multi is defined then returns after reading one
+ tlp
+ returns 1 if it found a tlp, otherwise 0
+ $tlp->writeout
+ without arg to stdout
+ with arg to filehandle
+ $tlp->writeout_simple
+ for comparison with tpm/tlps, will go away
+
+ $tlp->make_zip($tltree[,$destdir[,$zipname]]);
+ creates a zip file of the arch INDEPENDENT files in tlp
+ in $destdir (if not defined then TLP->zipdir is used).
+ The file name of the created zipfile is $zipname (if not
+ present $tlp->name.zip)
+
+ If the package contains "binfiles"; then zip files for
+ all archs containing ONLY the binfiles are created, and
+ the zipfile name is
+ $zipname.$arch.zip
+
+ (Compatibility with the scheme used before)
+
+
+Utilities:
+ $tlp->recompute_sizes($tltree)
+ recomputes all the *size fields, see below
+ $tlp->recompute_revision($tltree)
+ recomputes the revision of the package
+ $tlp->is_arch_dependent
+ true if it contains bin files, otherwise false
+ $tlp->total_size
+ if no arguments given this is
+ srcsize + docsize + runsize
+ if args are given then this is
+ srcsize + docsize + runsize +
+ + sum_{i in args} binsize{$i}
+
+Read/Write functions (with argument set, without arg read)
+
+ $tlp->name
+ $tlp->category
+ $tlp->revision
+ $tlp->shortdesc
+ $tlp->longdesc
+ $tlp->catalogue
+ reads/returns scalar
+ $tlp->srcfiles
+ $tlp->srcsize
+ $tlp->docfiles
+ $tlp->docsize
+ $tlp->runfiles
+ $tlp->runsize
+ *files reads/returns array of files
+ *size reads/returns scalar
+ $tlp->binfiles
+ $tlp->binsize
+ note that this gives/returns a HASH of architectures!!
+ $tlp->depends
+ $tlp->executes
+ reads/returns array
+
+ $tlp->add_srcfiles(@files)
+ $tlp->remove_srcfiles(@files)
+ adds @files to the list of srcfiles
+ $tlp->add_docfiles(@files)
+ $tlp->remove_docfiles(@files)
+ adds @files to the list of docfiles
+ $tlp->add_runfiles(@files)
+ $tlp->remove_runfiles(@files)
+ adds/removes @files to the list of runfiles
+
+ $tlp->add_binfiles($arch,@files)
+ $tlp->remove_binfiles($arch,@files)
+ adds/removes @files to the list of binfiles for arch=$arch
+
+ $tlp->add_files($type,@files)
+ $tlp->remove_files($type,@files)
+ adds/removes @files to the list of $type = (run|doc|src)files
+ NOT FOR binfiles!
+
+
+Module TeXLive::TKTREE
+----------------------
+(this one is still quite hacky)
+
+Constructor
+
+ TeXLive::TLTREE->new;
+ TeXLive::TLTREE->new( svnroot => "path/to/svn/managed/dir" );
+
+Init functions
+
+ $tltree->init_from_svn
+ changes to svnroot, calls svn status -v and builds
+ up all the necessary information
+ $tltree->init_from_statusfile($file)
+ does the same as init_from_svn, but from a pre-made
+ output of svn status -v
+
+Input/Ouput
+
+ $tltree->print
+ to stdout, more or less for hacking only not usefull
+
+Pattern matching functions
+
+ $ref = $tltree->get_matching_files($type,$pattern)
+ for $type = bin
+ returns a ref to a hash of keys = architectures
+ otherwise
+ returns a ref to an array
+ (see specification)
+
+Other functions
+
+ $tltree->file_svn_lastrevision($file)
+ returns the revision of the last change of file
+ as given by svn status -v
+ undef if file is not contained in $tltree
+
+ $tltree->size_of($file)
+ returns the size of $file, or undef if not in tree
+
+ &$tlsrc->architectures
+ sets/reads the list of architectures,
+ predefined to ....
+
+
+Module TeXLive::TLPDB
+------------------------
+Package variables:
+ &TeXLive::TLPDB->listdir
+ sets/returns the default location for created list files
+
+Constructore
+
+ TeXLive::TLPDB->new;
+ TeXLive::TLPDB->new ( location => "path/to/tldb/file" );
+
+Read/Write functions (with argument set, without arg read)
+
+ $tldb->location
+
+Input/Output
+
+ $tldb->from_file($filename);
+ reads a tldb file (tlp descriptions separated by newlines)
+
+ $tldb->writeout
+ without arg to stdout
+ with arg to filehandle
+
+ $tldb->save
+ saves to $self->location;
+
+ $tldb->generate_packagelist
+ outputs list of "package revision" for web delivery
+ without arg to stdout
+ with arg to filehandle
+
+ $tldb->generate_listfiles([$destdir])
+ create list file(s) in $destdir (if not given then it defaults
+ to TLDB->listdir) (could be more than one for
+ packages with binary files)
+
+TLP interface
+
+ $tldb->add_tlpobj($tlp)
+ adds a TeXLive::TLPOBJ to the db (or replaces an already present)
+
+ $tlp = $tldb->get_package("packagename");
+ returns undef if not installed
+
+ $rev = $tldb->package_revision("packagename");
+ returns undef if not installed, otherwise the
+ revision of "packagename"
+
+
+Package TeXLive::TLUtils
+------------------------
+
+exported functions:
+ sort_uniq(@list)
+ push_uniq(\@list,@list)
+ dirname($file)
+ basename($file)
+
+
diff --git a/Master/tlpkg/doc/TODO b/Master/tlpkg/doc/TODO
new file mode 100644
index 00000000000..e735fa15a31
--- /dev/null
+++ b/Master/tlpkg/doc/TODO
@@ -0,0 +1,137 @@
+TODO for new-infra
+==================
+PRE SWITCH
+----------
+- list files (TLPDB->generate_lists)
+ how is the size generated???
+ for normal packages: just the sum of docsize/srcsize/runsize
+ for packages with binaries: sum of the above + the maximum of the
+ sizes of the binaries{$arch}???
+ for collections: the sum of the sizes of the included packages
+ plus the size of itself (in case single files are added)??
+ for schemes: ????????????????????????? no idea: I summed up the
+ size of all the collections, but it seems to be wrong!
+- list files II
+ we should somehow check for equivalence of the two sets of files
+ a simple grep -v emptylines | sort |uniq ... diff should do it
+- rewrite the place script
+
+POST SWITCH
+-----------
+- update.pl: implement more of the 'updater'
+- Shell librarys
+ . test the tlp_ and the tldb_tlp_ functions
+ . missing functionality?
+ . rewrite the long read/case with awk/grep/whatever there is
+- rewrite install-* scripts to use the shell library
+ (or rewrite it in perl?)
+
+install scripts
+===============
+collection of usage of list files etc in the install scripts
+- get list of schemes by ls *.scheme
+- get title/size from the schemes
+- list all lang collections by ls collection-lang*
+- list all other collections by ls collection-* | grep -v collection-lang
+
+
+
+
+$ grep LISTS *
+common.sh: for i in `grep "^-collection-" $LISTS/$S.scheme | sed -e 's/^-//' -e 's/-/_/g'`
+
+ tlp_get_depends $S.tlp | grep collection- | ...
+
+common.sh: selected_packages=`grep "^[+\-]" $LISTS/$S.scheme | grep -v collection- | sed -e 's/^.//' -e 's/-/_/'`
+
+ tlp_get_depends $S.tlp | grep -v collection- | ...
+
+common.sh: selected_collections=`grep "^-collection-" $LISTS/$S.scheme | sed -e 's/^-collection-//'`
+
+ tlp_get_depends $S.tlp | grep "^collection-" ...
+
+common.sh: morecols=`grep -- "^-" $LISTS/$col | sed 's/.//'`
+
+ tlp_get_depends $col.tlp | grep ...
+
+common.sh: packages=`grep "^+" $LISTS/$col | sed 's/.//'`
+
+ tlp_get_depends $col.tlp | grep Package/
+
+common.sh: eval sort < $LISTS/$col | grep '^\!' | tr ' ' '=' >> $work_dir/$col.jobs
+
+ tlp_get_executes | tr ...
+
+common.sh: eval sort < $LISTS/$pack | grep '^\!' | tr ' ' '=' >> $work_dir/$col.jobs
+
+ tlp_get_executes | tr ...
+
+common.sh: more=`grep "^+" $LISTS/$pack | sed 's/.//'`
+
+ tlp_get_depends ...
+
+install-compr.sh: LISTS=$CDDIR/texmf/lists
+install-compr.sh: all_schemes=`(cd $LISTS && ls *.scheme | sed 's/\.scheme//' | sed 's/-/_/' | sort )`
+
+
+install-compr.sh: T=`grep '^\*Title' $LISTS/$S.scheme | sed -e 's/\*Title: //'`
+
+ tldb_tlp_get_title $tldb $S
+
+install-compr.sh: C=`grep '^\*Size' $LISTS/$S.scheme | sed -e 's/\*Size: //'`
+
+ tldb_tlp_get_size $tldb $S needs hacking, since sizes are currently
+ not computed for the whole package, but for
+ the single types of files
+
+install-compr.sh: all_lang_collections=`(cd $LISTS && ls collection-lang* | sed 's/-/_/g' | sort )`
+install-compr.sh: T=`grep '^\*Title' $LISTS/$S | sed -e 's/\*Title: //'`
+install-compr.sh: C=`grep '^\*Size' $LISTS/$S | sed -e 's/\*Size: //'`
+install-compr.sh: all_collections=`(cd $LISTS; ls collection-* | grep -v collection-lang | sed 's/-/_/g' | sort )`
+install-compr.sh: T=`grep '^\*Title' $LISTS/$S | sed -e 's/\*Title: //'`
+install-compr.sh: C=`grep '^\*Size' $LISTS/$S | sed -e 's/\*Size: //'`
+install-live.sh: LISTS=${OVERRIDE_LISTS-$CDDIR/texmf/lists}
+install-live.sh: BIN=${OVERRIDE_LISTS-$CDDIR/bin}
+install-live.sh: test -d $LISTS || fatal "$0: $LISTS: no such directory. Are you sure this is the TeX Live CD?"
+install-live.sh: systems=`(cd $LISTS; ls bin-tex.* | sed -e 's/bin-tex.//')`
+install-live.sh: all_schemes=`(cd $LISTS; ls *.scheme | sed -e 's/-/_/g' -e 's/\.scheme//' | sort )`
+install-live.sh: T=`grep '^\*Title' $LISTS/$S.scheme | sed -e 's/\*Title: //'`
+install-live.sh: C=`grep '^\*Size' $LISTS/$S.scheme | sed -e 's/\*Size: //'`
+install-live.sh: all_lang_collections=`(cd $LISTS; ls collection-lang* | sed 's/-/_/g' | sort )`
+install-live.sh: T=`grep '^\*Title' $LISTS/$S | sed -e 's/\*Title: //'`
+install-live.sh: C=`grep '^\*Size' $LISTS/$S | sed -e 's/\*Size: //'`
+install-live.sh: all_collections=`(cd $LISTS; ls collection* | grep -v collection-lang | sed 's/-/_/g' | sort )`
+install-live.sh: T=`grep '^\*Title' $LISTS/$S | sed -e 's/\*Title: //'`
+install-live.sh: C=`grep '^\*Size' $LISTS/$S | sed -e 's/\*Size: //'`
+install-live.sh: grep "^[A-Za-z0-9]" $LISTS/$I.$arg >> $work_dir/$arg.list
+install-live.sh: grep "^[A-Za-z0-9]" $LISTS/$I.$arg >> $work_dir/$arg.list
+install-live.sh: if test -f $LISTS/$col; then
+install-live.sh: packages=`grep "^+" $LISTS/$col | sed 's/.//'`
+install-live.sh: morecols=`grep "^-" $LISTS/$col | sed 's/.//'`
+install-live.sh: grep "^[a-z]" $LISTS/$col >> $work_dir/tmp
+install-live.sh: grep '^\!' $LISTS/$col >> $work_dir/tmp.jobs
+install-live.sh: if test -f $LISTS/$col.$this; then
+install-live.sh: grep "^[\!a-z]" $LISTS/$col.$this >> $work_dir/tmp
+install-live.sh: test -s $LISTS/$pack || return
+install-live.sh: grep "^[A-Za-z0-9]" $LISTS/$pack >> $work_dir/ptmp
+install-live.sh: grep '^\!' $LISTS/$pack >> $work_dir/ptmp.jobs
+install-live.sh: if test -f $LISTS/$pack.$this; then
+install-live.sh: grep "^[A-Za-z0-9]" $LISTS/$pack.$this >> $work_dir/ptmp
+install-live.sh: for i in `grep "^+" $LISTS/$pack | sed 's/.//'`
+install-pkg-compr.sh: morecols=`grep "^-" $LISTS/$name | sed 's/.//'`
+install-pkg-compr.sh: packages=`grep "^+" $LISTS/$name | sed 's/.//'`
+install-pkg-compr.sh: grep "^[a-z]" $LISTS/$name >> tmp
+install-pkg-compr.sh: if test -f $LISTS/$binlist; then
+install-pkg-compr.sh: grep "^[a-z]" $LISTS/$binlist >> tmp
+install-pkg-compr.sh:LISTS=${listdir-${OVERRIDE_LISTS-$CDDIR/texmf/lists}}
+install-pkg-compr.sh: colfile=$LISTS/collection-$col
+install-pkg-compr.sh: pkgfile=$LISTS/$pkg
+install-pkg-live.sh: list_files $LISTS/$i
+install-pkg-live.sh: if test -f $LISTS/$binlist; then
+install-pkg-live.sh: grep "^[a-z]" $LISTS/$binlist >> tmp
+install-pkg-live.sh:LISTS=${listdir-${OVERRIDE_LISTS-$CDDIR/texmf/lists}}
+install-pkg-live.sh:test -d $LISTS || fatal "$0: $LISTS: no such directory. Are you sure this is the TeX Live CD?"
+install-pkg-live.sh: colfile=$LISTS/collection-$col
+install-pkg-live.sh: list_files $LISTS/collection-$col
+install-pkg-live.sh: pkgfile=$LISTS/$pkg
+install-pkg-live.sh: list_files $LISTS/$pkg
diff --git a/Master/tlpkg/doc/specification.txt b/Master/tlpkg/doc/specification.txt
new file mode 100644
index 00000000000..4c24ce56b8e
--- /dev/null
+++ b/Master/tlpkg/doc/specification.txt
@@ -0,0 +1,141 @@
+Specifications
+==============
+
+1) tlsrc
+--------
+one file *WITHOUT* empty lines (but beginning and end)
+every line looks like
+ key value
+possible keys are
+ name (must be first)
+ category
+ shortdesc
+ longdesc
+ catalogue
+ runpatterns
+ srcpatterns
+ docpatterns
+ binpatterns
+ execute
+ depend
+
+Interpretation:
+name
+ name of the package
+
+category
+ TLCore Package Documentation
+ as well known from tpms
+ if none specified it is Package
+
+catalogue
+ name of the respective Catalogue entry, if missing, same as name
+
+(run|src|doc|bin)patterns
+ (cheap/expensive means working time)
+
+ current status:
+ [PREFIX]TYPE PAT
+ TYPE = t f d r
+ PREFIX = + | +! | !
+ t word1 ... wordN wordL
+ include all files below all dirs of the form
+ word1/.../wordN/.../wordL/...
+ (cheap)
+ f string
+ include file "string" where the LAST(!!!) entry (basename)
+ of string can contain glob characters * and ? (but no other!)
+ (cheap)
+ d string
+ include all files in and below the directory "string"
+ (cheap)
+ r regexp
+ include all files matching /^regexp$/
+ (expensive)
+
+ Note that if one of the patterns section is empty OR (!!!) all
+ provided patterns have the prefix "+" (eg "+f ...."), then
+ the following patterns are added:
+ for runpatterns:
+ t texmf-dist topdir $tlp for type = Package
+ (with topdir = bibtex, context, ... see tlsrc2tlp.pl)
+ for docpatterns:
+ t texmf-dist doc $tlp for type = Package
+ t texmf-doc doc $tlp for type = Documentation
+ for srcpatterns:
+ t texmf-dist source $tlp for type = Package
+ t texmf-doc source $tlp for type = Documentation
+ for binpatterns:
+ NONE!!
+
+ If the prefix contains a ! the pattern is negated, ie after all the
+ files for positive patterns have been added, those matching the
+ negative patterns are removed.
+
+execute free form
+ is taken one to one into the tlp file
+
+depend
+ is taken one to one into the tlp file
+ made up of
+ Type/Package
+ where
+ Type ::= TLCore | Documentation | Package
+
+shortdesc
+ short one line desc
+ is taken one to one into the tlp file
+ if missing can be taken from Catalogue
+
+longdesc
+ longer multiline dscription
+ is taken one to one into the tlp file
+ if missing can be taken from Catalogue
+
+2) tlp file
+-----------
+same format as tlsrc, but the keys are
+ name
+ category
+ revision
+ shortdesc
+ longdesc
+ catalogue
+ runfiles
+ docfiles
+ srcfiles
+ binfiles
+ execute
+ depend
+ ??? what am I missing ???
+
+Interpretation
+ bin|src|doc|runfiles MUST be saved in multi line entries with
+ continuation lines intended by one (1) space. all of them
+ can have (must have?) the size tag size=......, in addition
+ binfiles can have the arch tag arch=...
+ /----------
+ |docfiles size=....
+ | file1
+ | file2
+ | ...
+ For binfiles the architecture can be given on the binfile line:
+ /------------
+ |binfiles arch=i386-solaris size=....
+ | file1
+ | file2
+ | file3
+ | ...
+ Note that only *ONE* *files entry per tlp is allowed
+
+ rest obvious
+
+ revision
+ maxmimum of all the last_changed_revisions of all
+ contained files
+
+3) tldb file
+------------
+concatenation of all the tlp files, separated by empty line(s)
+
+