path: root/Master/tlpkg/doc/repository-setup.txt

$Id$
(This document is public domain.)

How to set up your own TeX Live Packages repository
===================================================
TeX Live 2008 and later contain the TeX Live Manager, which allows 
updates over the network. By specifying different installation sources
the user can 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 include distribution of company-internal
packages or non-free stuff not included in TeX Live.

Multiple repository support is very much work in progress.
Write tex-live@tug.org if questions or suggestions.

Contents
--------
0. Preliminaries
1. Prerequisites
2. Preparing the "repository"
3. tlpsrc files
4. Creating the TeX Live Database
5. Adjusting the revision numbers
6. Making the web distribution
7. Testing your distribution
8. Final notes (and unsupported stuff)


0. Preliminaries
----------------
First of all, before you start with providing your own packages, please
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 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 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 on accessing our repo.

That means, with ROOT as the root of your local "repository":
	ROOT/tlpkg/		infrastructure stuff, modules, scripts
	ROOT/texmf-dist/	stuff where you should put your 
				TeX code, fonts etc
	ROOT/texmf		if you have the need for that please read
				first about their usage in the 
				TeX Live Guide.

After that you call the very same scripts as we do when building the
distribution database in
	ROOT/tlpkg/texlive.tlpdb

Finally you create/update your web distribution from that ROOT.


1. Prerequisites
----------------
You need from the TeX Live Repository (see http://www.tug.org/texlive/svn/)
the contents of at least
	Master/tlpkg/TeXLive		the perl modules
	Master/tlpkg/bin		the scripts for managing
These files can be checked out via svn, or downloaded from the net.
We recommend svn, so that you can easily update them regularly.


2. Preparing your repository
----------------------------
Create a root folder which will mirror our directory layout. We will call
that root folder ROOT from now on.

Put the above files into 
	ROOT/tlpkg/TeXLive
	ROOT/tlpkg/bin
After that put all of YOUR files in a TDS compliant way in one of the texmf
trees, texmf-dist, texmf, texmf-doc.
	ROOT/texmf{,-dist}
We recommend putting all the files in 
	ROOT/texmf-dist
or, if you are replacing a package which is already present in TeX Live,
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 overall installation, called
00texlive.config.tlpsrc. This package defines some basic configurations
for the tlpdb, like how it announces itself, whether separate src and
doc containers are build, and the release years it supports.

By default these values are taken from %TeXLive::TLConfig::TLPDBConfigs
where you can make changes in your local TLConfig.pm file, or you add
these settings directly in the tlpsrc file and call tl-update-tlpdb
later on with the option -tlpdb-options-from-tlpsrc.

In the end the generate "package" 00texlive.config should contain
(at least) the following lines:
	category TLCore
	depend container_format/xz
	depend release/NNNN-YOUR_ID

and might optionally contain:
	depend container_split_src_files
	depend container_split_doc_files
	depend maxrelease/MMMM-YOUR_ID

The 
	depend container_format/xz
is *obligatory* because currently we do NOT support any other format.

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.xz archives for source and doc files, or put
all of them into one .tar.xz. It is up to you.

Finally, the 
	depend release/NNNN-YOUR_ID
and (optionally)
	depend maxrelease/MMMM-YOUR_ID
determine(s) which release(s) of TL your repository works with.
If maxrelease is present, the year specified in the local (user's) 
installation's $TLConfig::ReleaseYear must be in the range 
[release,maxrelease].  
If maxrelease is not present, the release/NNNN value must exactly 
match the the TL release number NNNN.
For example, you might have:
	depend release/2009-myorg
and if your packages work with both TL'09 and TL'10, you could add:
	depend maxrelease/2010-myorg


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).

If you want to use the auto-generated patterns we are using in TeX Live 
you have to copy our 00texlive.autopatterns.tlpsrc into your tlpkg/tlpsrc
directory.

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 two-line .tlpsrc file foobar.tlpsrc containing:
	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 (and don't forget to copy 
00texlive.autopatterns.tlpsrc).


4. Creating the TeX Live Database
---------------------------------
If you have set up all your local files, and the tlpsrc files, you can 
create the TeX Live Database in ROOT/tlpkg/texlive.tlpdb by calling
	perl ROOT/tlpkg/bin/tl-update-tlpdb -from-files
If you have set your TLPDB configuration options directly in the .tlpsrc
file you have to add
		-tlpdb-options-from-tlpsrc
The -from-files does use a find command to find all the files in ROOT 
instead of using "svn status" what is done normally. By default
tl-update-tlpdb uses 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 together with -tlpsrc-from-cmdline.

You can add the option
	-with-win-pattern-warning
which will warn on missing files for Windows; some of those warnings are
by default suppressed.

Another option that might be of interest is
	-no-revision-check
Normally if there is an old tlpdb the packages in the new one are compared
with the packages in the old one and checked that the revisions are
increasing.

As usual, please read the documentation of tl-update-tlpdb (again in POD)
for further information.

That process will probably show you some warnings; read them carefully.

After it runs successfully, you should have a file
	ROOT/tlpkg/texlive.tlpdb
	
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 
packages will have 
	revision 0
in there. The revision is used for checking which one is newer. So if you 
have different "releases" of a package you should increase the revision
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
  ... 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
created.

The option -no-setup does not call the built-in routines for determining the
location of the lzma and tar binary, and calls simply "lzma" and "tar". So
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 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
or 
	tlmgr -location DEST update --all
or 
	tlmgr -location DEST list
etc.  Please see the documentation of tlmgr (POD again) for details.


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, 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.

If you have further comments, questions, additions to this file please
let us know at tex-live@tug.org.


Last changed 2009-09-10 by np, based on comments of Dohyun Kim (kotex)