summaryrefslogtreecommitdiff
path: root/Master/tlpkg/doc/repository-setup.txt
blob: affaec632f281a98c8c9929d5c9afabd775013c3 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
How to set up your own TeX Live Packages repository
===================================================

$Id$

TeX Live 2008 contains 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 are 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
at tex-live@tug.org.

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


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 the TeX Live Manager
  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
  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.

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{,-doc}	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 the first variant so that you can update them regularly.

2. Preparing the "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,-doc}
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 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 
	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.

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

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:
	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 
create the TeX Live Database in ROOT/tlpkg/texlive.tlpdb by calling
	perl ROOT/tlpkg/bin/tlpsrc2tlpdb -from-files -all
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/.

You can add the option
	-with-win-pattern-warning
which will warn on missing files for Win32, 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.

After that you should have a files
	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.

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

6. Making the web distribution
------------------------------