summaryrefslogtreecommitdiff
path: root/Master/tlpkg/doc/repository-setup.txt
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2008-09-30 00:21:21 +0000
committerKarl Berry <karl@freefriends.org>2008-09-30 00:21:21 +0000
commit69405f1552b2face9e036ffa57e1a1f3eb7382cd (patch)
tree4a2bbc858755a52461a89c16314c2ef566d43d6c /Master/tlpkg/doc/repository-setup.txt
parent4ac0fd1542da6a36a91b845e4d86bfd279724a0e (diff)
English tweaks to the new alt repo setup doc, and delete our unupdated dev man files
git-svn-id: svn://tug.org/texlive/trunk@10794 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/tlpkg/doc/repository-setup.txt')
-rw-r--r--Master/tlpkg/doc/repository-setup.txt99
1 files changed, 58 insertions, 41 deletions
diff --git a/Master/tlpkg/doc/repository-setup.txt b/Master/tlpkg/doc/repository-setup.txt
index 293d0f107f6..fa86745ca1b 100644
--- a/Master/tlpkg/doc/repository-setup.txt
+++ b/Master/tlpkg/doc/repository-setup.txt
@@ -1,7 +1,9 @@
+$Id$
+
How to set up your own TeX Live Packages repository
===================================================
-$Id$
+(This document is public domain.)
TeX Live 2008 contains the TeX Live Manager, which allows updates over
the network. By specifying different installation sources the user can
@@ -9,11 +11,11 @@ in theory install packages using tlmgr from a different source as the
default TeX Live repository.
This document describes how to set up a repository in a way that tlmgr
-can use it. Possible applications are distribution of company-internal
+can use it. Possible applications include distribution of company-internal
packages or non-free stuff not included in TeX Live.
-Note that this document is very much work in progress, as is most of the
-TeX Live infrastructure. If you have any questions please contact us
+Note that this document is very much work in progress (as is most of the
+TeX Live infrastructure). If you have any questions please contact us
at tex-live@tug.org.
Contents
@@ -26,7 +28,7 @@ Contents
5. Adjusting the revision numbers
6. Making the web distribution
7. Testing your distribution
-8. Final notes (and not supported stuff)
+8. Final notes (and unsupported stuff)
0. Preliminaries
@@ -36,17 +38,17 @@ be reminded that you should take good care not to
- overwrite files which are in a different package
The current system does NOT check for files that got overwritten
- take care not to hose the rest of the TeX Live system,
- imagine you install a package that removes/deletes the TeX Live Manager
- tlmgr the user will hardly be able to revert to any working state!
+ imagine you install a package that removes/deletes tlmgr --
+ the user will hardly be able to revert to any working state!
- test, test, and again TEST before shipping your stuff
-- might be good to avert us at tex-live@tug.org so that we can take a look
+- might be good to alert us at tex-live@tug.org so that we can take a look
and comment, or check for other problems. Also, if we change something
in the infrastructure you have a better chance in getting notifications
and better treatment ;-)
In principle what you have to do is to set up some directory in a layout
paralleling the one in our repository under Master. See
-http://www.tug.org/texlive/svn/ for details.
+http://www.tug.org/texlive/svn/ for details on accessing our repo.
That means, with ROOT as the root of your local "repository":
ROOT/tlpkg/ infrastructure stuff, modules, scripts
@@ -72,8 +74,9 @@ the contents of at least
These files can be checked out via svn, or downloaded from the net. We
recommend the first variant so that you can update them regularly.
-2. Preparing the "repository"
------------------------------
+
+2. Preparing your repository
+----------------------------
Create a root folder which will mirror our directory layout. We will call
that root folder ROOT from now on.
@@ -91,50 +94,55 @@ in the very same places as in TeX Live.
If you really want to replace packages with files in texmf, please think
twice, and maybe contact us before.
+
3. tlpsrc files
---------------
Now you have to create several TeX Live Package Source files, .tlpsrc files
and place them into
ROOT/tlpkg/tlpsrc
+
You have to have ONE .tlpsrc file for each package you want to ship, and
-furthermore ONE for your installation, called 00texlive.config.tlpsrc.
-This should contain (at least) the following lines:
+furthermore ONE for your overall installation, called
+00texlive.config.tlpsrc. This should contain (at least) the following
+lines:
name 00texlive.config
category TLCore
depend container_split_src_files
depend container_split_doc_files
depend container_format/lzma
depend release/YOUR_ID_AND_MAYBE_YEAR
-The "container_split_src_files" and "container_split_doc_files" are options,
-they specify whether at a later stage the container script will generate
-different .tar.lzma for source and doc files, or put all of them into
-one .tar.lzma. It is up to you.
+
+The "container_split_src_files" and "container_split_doc_files" are
+options, they specify whether at a later stage the container script will
+generate separate .tar.lzma archives for source and doc files, or put
+all of them into one .tar.lzma. It is up to you.
The
depend container_format/lzma
is *obligatory* because currently we do NOT support any other format.
Finally the
depend release/YOUR_ID_AND_MAYBE_YEAR
-is not used, but you could add here some identification string. It is not
-currently used, but tlmgr might at some future point use it.
+is not used, but you could add here some identification string;
+it can't hurt, and we might be able to display it to the user in the
+future.
For the rest of your package you should create .tlpsrc files describing
their content. Either copy one of our .tlpsrc files, or (much better)
-PLEASE read the documentation of TLPSRC.pm (in POD format, also shipped
-in Master/tlpkg/man/TeXLive-TLPSRC.1, but that might be outdated).
+PLEASE read the documentation of TLPSRC.pm (in POD format).
Some guidelines: For simple packages, say a LaTeX package foobar, put all
the files in
ROOT/texmf-dist/tex/latex/foobar/
ROOT/texmf-dist/source/latex/foobar/
ROOT/texmf-dist/doc/latex/foobar/
-then create a very simple .tlpsrc file foobar.tlpsrc containing:
+then create a two-line .tlpsrc file foobar.tlpsrc containing:
name foobar
category Package
(that is all). The rest will be automatically done by our scripts. If you
want to understand that, read the section on auto-generated patterns in
the TLPSRC.pm documentation.
+
4. Creating the TeX Live Database
---------------------------------
If you have set up all your local files, and the tlpsrc files, you can
@@ -143,29 +151,33 @@ create the TeX Live Database in ROOT/tlpkg/texlive.tlpdb by calling
The -from-files does use a find command to find all the files in ROOT
instead of using "svn status" what is done normally. The -all makes
tlpsrc2tlpdb work on all tlpsrc files present in ROOT/tlpkg/tlpsrc/.
+Presumably this won't be very many files. But if you like, you can
+specify individual package names instead of -all.
You can add the option
-with-win-pattern-warning
-which will warn on missing files for Win32, some of those warnings are
+which will warn on missing files for Windows; some of those warnings are
by default suppressed.
As usual, please read the documentation of tlpsrc2tlpdb (again in POD)
for further information.
-That process will probably ship out some warnings, read them carefully.
+That process will probably show you some warnings; read them carefully.
-After that you should have a files
+After it runs successfully, you should have a file
ROOT/tlpkg/texlive.tlpdb
-Your next job is to check that texlive.tlpdb file that the files you
-wanted to have in one package are actually there. Go through all packages
-(starting always with a line "name foobar") and check for the occurring
-files.
+
+Your next job is to check that your new texlive.tlpdb has the files you
+expected in the corresponding packages that you expected. Go through
+the entire file (each package starts with a line "name foobar") and
+the file list..
If you are not content, work on your patterns to fix that.
There are some scripts in tlpkg/bin/ starting with "check-" which you might
use for doing some checks on your repository.
+
5. Adjusting the revision numbers
---------------------------------
While reading through the texlive.tlpdb you might have seen that all the
@@ -177,18 +189,21 @@ number from one step to the next.
If you want to change that, there are several options:
- do it by hand in the texlive.tlpdb
- that is fine, but you should remember what you have already shipped
+ ... if you can remember what numbers you already shipped
+
- do it automatically with some script which takes into account the already
shipped version of the packages, or the version of the package in
the main TeX Live repository (if you replace a TeX Live package)
An example for doing that take a look at our repository
tlpkg/etc/tlrepo-from-minimals.pl
+
6. Making the web distribution
------------------------------
Now that the texlive.tlpdb has been set up, revision numbers adjusted, you
can create or update your web distribution with
perl ROOT/tlpkg/bin/tl-update-containers -location DEST -no-setup
+
The -location gives the place where your former distribution was or where
it should be created. In the former case only those containers with larger
revision numbers are recreated. In the latter case all containers are
@@ -200,9 +215,10 @@ you should have them in your PATH. If you do not give this option you also
have to check out some more files, like config.guess, and tlpkg/installer
where the binaries for lzma for the architectures we ship are present.
+
7. Testing your distribution
----------------------------
-Having complete all your steps you can test your distribution by calling
+Having completed all these steps, you can test your distribution by calling
the TeX Live Manager with the location argument. Continuing the above
exmaple we use DEST:
tlmgr -location DEST update --list
@@ -210,22 +226,23 @@ or
tlmgr -location DEST update --all
or
tlmgr -location DEST list
-etc etc. Please see the documentation of tlmgr (POD again) for details.
+etc. Please see the documentation of tlmgr (POD again) for details.
-8. Final notes (and not supported stuff)
-----------------------------------------
+
+8. Final notes (and unsupported stuff)
+--------------------------------------
We cannot repeat it often enough, please don't play around with files not
belonging to your packages. That is dangerous!
-Finally, not that besides the usual post installation stuff (running mktexlsr,
-fmtutil and updmap) you have no way to change the post installation
-and removal procedure at this time. Currently all the Post actions are
-hard coded into tlpkg/TeXLive/TLPostActions.pm as it is on the installed
+Finally, besides the usual post installation stuff (running mktexlsr,
+fmtutil and updmap) you have no way to change the post installation and
+removal procedure at this time. Currently all the Post actions are hard
+coded into tlpkg/TeXLive/TLPostActions.pm as it is on the installed
system (not the one in your repo, so changing something there will NOT
help). You might ask us for including something there (but we need GOOD
-reason for that), or you have to wait until we extended the infrastructure
-such that post actions can be specified freely in the .tlpsrc file.
-
+reason for that), or you have to wait until we extended the
+infrastructure such that post actions can be specified freely in the
+.tlpsrc file.
If you have further comments, questions, additions to this file please
let us know at tex-live@tug.org.