pkgsrc/doc/guide/files/ftp-layout.xml

<!-- $NetBSD: ftp-layout.xml,v 1.15 2019/02/28 10:54:31 leot Exp $ -->

<appendix id="ftp-layout">
<title>Directory layout of the pkgsrc FTP server</title>

	<para>As in other big projects, the directory layout of pkgsrc
	is quite complex for newbies. This chapter explains where you
	find things on the FTP server. The base directory on
	<filename>ftp.NetBSD.org</filename> is <ulink
	url="ftp://ftp.NetBSD.org/pub/pkgsrc/"><filename>/pub/pkgsrc/</filename></ulink>.
	On other servers it may be different, but inside this directory,
	everything should look the same, no matter on which server you
	are. This directory contains some subdirectories, which are
	explained below.</para>

<sect1 id="ftp-distfiles">
<title><filename>distfiles</filename>: The distributed source files</title>

	<para>The directory <filename>distfiles</filename> contains lots
	of archive files from all pkgsrc packages, which are mirrored
	here. The subdirectories are called after their package names
	and are used when the distributed files have names that don't
	explicitly contain a version number or are otherwise too generic
	(for example <filename>release.tar.gz</filename>).</para>

</sect1>
<sect1 id="ftp-misc">
<title><filename>misc</filename>: Miscellaneous things</title>

	<para>This directory contains things that individual pkgsrc
	developers find worth publishing.</para>

</sect1>
<sect1 id="ftp-packages">
<title><filename>packages</filename>: Binary packages</title>

	<para>This directory contains binary packages for the various
	platforms that are supported by pkgsrc.
	Each subdirectory is of the form <replaceable>OPSYS</replaceable
	>/<replaceable>ARCH</replaceable
	>/<replaceable>OSVERSION_TAG</replaceable
	>. The meaning of these variables is:</para>

	<itemizedlist>

	<listitem><para><varname>OPSYS</varname> is the name of the
	operating system for which the packages have been built. The
	name is taken from the output of the <command>uname</command>
	command, so it may differ from the one you are used to
	hear.</para></listitem>
	
	<listitem><para><varname>ARCH</varname> is the hardware
	architecture of the platform for which the packages have been
	built. It also includes the <varname>ABI</varname> (Application
	Binary Interface) for platforms that have several of
	them.</para></listitem>

	<listitem><para><varname>OSVERSION</varname> is the version of
	the operating system. For version numbers that change often (for
	example NetBSD-current), the often-changing part should be
	replaced with an <literal>x</literal>, for example
	<literal>4.99.x</literal>.</para></listitem>

	<listitem><para><varname>TAG</varname> is either
	<literal>20<replaceable>xx</replaceable>Q<replaceable>y</replaceable></literal>
	for a stable branch, or <literal>head</literal> for packages
	built from the HEAD branch. The latter should only be used when
	the packages are updated on a regular basis. Otherwise the date
	from checking out pkgsrc should be appended, for example
	<literal>head_20071015</literal>.</para></listitem>

	</itemizedlist>

	<para>The rationale for exactly this scheme is that the pkgsrc users looking for binary packages
	can quickly click through the directories on the
	server and find the best binary packages for their machines. Since they
	usually know the operating system and the hardware architecture, OPSYS
	and ARCH are placed first. After these choices, they can select the
	best combination of OSVERSION and TAG together, since it is usually the
	case that packages stay compatible between different version of the
	operating system.</para>

	<para>In each of these directories, there is a
	whole binary packages collection for a specific platform. It has a directory called
	<filename>All</filename> which contains all binary packages.
	Besides that, there are various category directories that
	contain symbolic links to the real binary packages.</para>

</sect1>
<sect1 id="ftp-reports">
<title><filename>reports</filename>: Bulk build reports</title>

	<para>Here are the reports from bulk builds, for those who want
	to fix packages that didn't build on some of the platforms. The
	structure of subdirectories should look like the one in <xref
	linkend="ftp-packages"/>.</para>

</sect1>
<sect1 id="ftp-source">
<title><filename>current</filename>,
<filename>stable</filename>,
<filename>pkgsrc-20<replaceable>xx</replaceable>Q<replaceable>y</replaceable></filename>:
source packages</title>

	<para>These directories contain the <quote>real</quote> pkgsrc,
	that is the files that define how to create binary packages from
	source archives.</para>

	<para>Each of the <filename>current</filename>,
	<filename>stable</filename> and
	<filename>pkgsrc-20<replaceable>xx</replaceable>Q<replaceable>y</replaceable></filename>
	directories share the same structure.  They each contain a
	<filename>pkgsrc</filename> directory and
	<filename>pkgsrc.tar.{bz,gz,xz}</filename> file.</para>

	<para>The directory <filename>pkgsrc</filename> contains a
	snapshot of the CVS repository, which is updated regularly. The
	file <filename>pkgsrc.tar.{bz,gz,xz}</filename> contains the same
	as the directory, ready to be downloaded as a whole.</para>

	<para>The <filename>current</filename> directory contains files
	related to the HEAD branch of the CVS repository.
	In this directory there is an additional file called
	<filename>pkgsrc-readmes.tar.{bz,gz,xz}</filename> that contains
	all pkgsrc <filename>README</filename>s with information about
	categories and packages.
	</para>

	<para>The <filename>stable</filename> directory is a symlink to
	the latest 
	<filename>pkgsrc-20<replaceable>xx</replaceable>Q<replaceable>y</replaceable></filename>.
	</para>

	<para>The
	<filename>pkgsrc-20<replaceable>xx</replaceable>Q<replaceable>y</replaceable></filename>.
	directories contain files related to the 
	<filename>-20<replaceable>xx</replaceable>Q<replaceable>y</replaceable></filename>
	stable branch of the CVS repository. In these directories there is
	an additional file called
	<filename>pkgsrc-20<replaceable>xx</replaceable>Q<replaceable>y</replaceable>.tar.{bz,gz,xz}</filename>,
	which contains the state of pkgsrc when it was branched.</para>

</sect1>
</appendix>