diff options
author | Norbert Preining <preining@logic.at> | 2009-09-15 18:56:50 +0000 |
---|---|---|
committer | Norbert Preining <preining@logic.at> | 2009-09-15 18:56:50 +0000 |
commit | 995770ec5a02a4379ee49acbad1ce091601f7203 (patch) | |
tree | 1d78cb5bf9ab257c8c5d66ceb3127337fbd4b0b3 /Master/tlpkg/doc/historic | |
parent | 29b6bc51ba93d568c16f16e04fbc509653d85241 (diff) |
rework tlpkg/doc and tlpkg/dev layout
git-svn-id: svn://tug.org/texlive/trunk@15301 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/tlpkg/doc/historic')
-rw-r--r-- | Master/tlpkg/doc/historic/Perl-API.txt | 290 | ||||
-rw-r--r-- | Master/tlpkg/doc/historic/installer-layout.txt | 92 | ||||
-rw-r--r-- | Master/tlpkg/doc/historic/specification.txt | 159 |
3 files changed, 541 insertions, 0 deletions
diff --git a/Master/tlpkg/doc/historic/Perl-API.txt b/Master/tlpkg/doc/historic/Perl-API.txt new file mode 100644 index 00000000000..2b3200c2e74 --- /dev/null +++ b/Master/tlpkg/doc/historic/Perl-API.txt @@ -0,0 +1,290 @@ +API for Perl Modules for new infra +================================== + +NOTE: THE DEFINITIVE DOCUMENTATION IS IN THE PM FILES AS POD DOCUMENTATION!! + +Module TeXLive::TLPSRC +---------------------- + +PLEASE SEE THE MANPAGE OF TeXLive::TLPSRC which is MORE UP 2 DATE!!!! + +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 +---------------------- + +PLEASE SEE THE MANPAGE OF TeXLive::TLPOBJ which is MORE UP 2 DATE!!!! + +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 + + All the arch independent zip files ALSO contain the + respective TLPOBJ file in + .tlpobj/$name.tlpobj + SO $zipname.zip does contain this tlpobj file, while + $zipname.$arch.zip does NOT. + + (Compatibility with the scheme used before) + + $tlp->update_from_catalogue($texcatalogue); + merges some information from the TeX Catalogue into + the TLPOBJ + +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::TLTREE +---------------------- +(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 + $tltree->init_from_files + inits from a find $svnroot command, all the revisions + are set to 1 + +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) + + Note that a pattern of the form + bin/${ARCH}/foobar + also matches for arch=win32 + bin/${ARCH}/foobar.{exe,bat} + + +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 + +Constructor + + TeXLive::TLPDB->new; + TeXLive::TLPDB->new ( location => "path/to/tldb/file" ); + TeXLive::TLPDB->new ( location => "http://path/to/tldb/file" ); + TeXLive::TLPDB->new ( location => "ftp://path/to/tldb/file" ); + +Read/Write functions (with argument set, without arg read) + + $tldb->location + +Input/Output + + $tldb->from_file("path/to/tldb/file"); + $tldb->from_file("http://path/to/tldb/file"); + $tldb->from_file("ftp://path/to/tldb/file"); + 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) + + $tldb->list_packages + returns all packages installed + +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: + platform; + platform_desc($platform); + win32; + unix; + getenv($string); + which($string); + program_exists($program); + get_system_tmpdir; + dirname($path); + basename($path); + dirname_and_basename($path); + mkdirhier($path); + copy($file, $target_dir); + media; + initialze_installer; + binaries_available_from_disk; + binaries_available_from_net; + make_var_skeleton($path); + make_local_skeleton($path); + sort_uniq(@list); + push_uniq(\@list, @items); + member($item, @list); + debug($string); diff --git a/Master/tlpkg/doc/historic/installer-layout.txt b/Master/tlpkg/doc/historic/installer-layout.txt new file mode 100644 index 00000000000..1fc6ad424c0 --- /dev/null +++ b/Master/tlpkg/doc/historic/installer-layout.txt @@ -0,0 +1,92 @@ +Installer/Updater/Layout +======================== + +layout +------ + +root directory ROOT (texlive2008 or texlive-2008 or ...) + + ROOT/texmf-dist + ROOT/texmf + ROOT/texmf-config + ROOT/texmf-var + ROOT/bin + + ROOT/tlpkg/texlive.tlpdb + ROOT/tlpkg/tlpobj + ROOT/tlpkg/ ... + +As suggested by Reinhard, and discussed with Karl, I propose to put the +texlive.tlpdb NOT into ROOT, but "hide" it somehow, i.e., put it into + ROOT/tlpkg + + +distribution methods +-------------------- + + inst CD/DVD + + contains all the packages in zip (or lzma or ...) form, plus the + installer and the texlive.tlpdb + + live DVD + + contains a live tree, no zip media, plus the texlive.tlpdb + + network + + zip files + "package version" file + texlive.tlpdb (??? necessary, could be ignored) + + +format of the zip files +---------------------- +(can be another compression method) + +The zip files contain the files with pathes relative to ROOT, i.e., + ./texmf-dist/... + ./texmf/... + ./bin/... + +Furthermore, the zip file contains a TLPOBJ file in + ./tlpkg/tlpobj/NAME.tlpobj + +This allows the distribution of "packages" even from outside of TeX Live +(imagine that someone creates a minion-pro.zip for installation into +the TeX Live installation). + +OTOH this is a duplication in some cases since the inst and live media +the same information is present in the texlive.tlpdb. But I think that the +win of "self containment" over "no duplication" is more important. + +Furthermore, Karl suggested that some people may want to recreate the +texlive.tlpdb in case it was destroyed. For this we have to ship the +tlpobj files. + + +Installation procedure +---------------------- + +- from inst CD +-------------- + + files in the zip + tlpobj data from shipped texlive.tlpdb or the zip file + +- from network (used also for the updater) +------------------------------------------ + + files in the zip + tlpobj data from the zip file or from the network tlpdb (if present) + + +- from full/live DVD: +--------------------- + + files from the DVD + tlpobj data from the shipped texlive.tlpdb + + +(from here on action for all) + diff --git a/Master/tlpkg/doc/historic/specification.txt b/Master/tlpkg/doc/historic/specification.txt new file mode 100644 index 00000000000..6233c95e084 --- /dev/null +++ b/Master/tlpkg/doc/historic/specification.txt @@ -0,0 +1,159 @@ +Specifications +============== + +(see also the pod documentation of the respective perl modules for + the specificatin) + +1) tlpsrc +--------- + +PLEASE SEE THE MANPAGE OF TeXLive::TLPSRC which is MORE UP 2 DATE!!!! + + +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 + runpattern + srcpattern + docpattern + binpattern + execute + depend +(NO continuation lines!) + +Interpretation: +name + name of the package + +category + Collection Scheme TLCore Package Documentation + as well known from tpms + Collection and Scheme is new and is for ... + +catalogue + name of the respective Catalogue entry, if missing, same as name + +(run|src|doc|bin)pattern + (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 runpattern: + t texmf-dist topdir $tlp for type = Package + (with topdir = bibtex, context, ... see tlsrc2tlp.pl) + for docpattern: + t texmf-dist doc $tlp for type = Package + t texmf-doc doc $tlp for type = Documentation + for srcpattern: + t texmf-dist source $tlp for type = Package + t texmf-doc source $tlp for type = Documentation + for binpattern: + 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 + all the lines of longdesc are concatenated + +2) tlpobj file +-------------- + +PLEASE SEE THE MANPAGE OF TeXLive::TLPOBJ which is MORE UP 2 DATE!!!! + +same format as tlpsrc, but the keys are + name + category + revision + shortdesc + longdesc + catalogue + runfiles + docfiles + srcfiles + binfiles + execute + depend + catalogue-* (whatever) + ??? 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 + 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 + + catalogue-* + can contain arbitrary fields from the TeX Catalogue + + +3) tlpdb file +------------ +concatenation of all the tlp files, separated by empty line(s) + + |