*! version 1.1 24 February 2022
help for zippkgversion 1.1 (24 February 2022)

Title

zippkg -- A Stata module to create ZIP archives of
community-contributed content for offline distribution

Table of contents

Syntax
Description
Options
Remarks
Examples
Author
Also see

Syntax

zippkg
pgkspec
[,
zippkg_options]

where the syntax of pkgspec is

[(]
pkglist ,
pkgspec_options
[)] [||]

and pkglist is a list of packages names

zippkg options

from(directory_or_url) requests to use directory_or_url as
installation source; the special keyword "ssc" is allowed (and used as
default if the option is omitted), any other content will be passed through to
net install

all also download ancillary files; will be passed through to
net install or
ssc, respectively

notrackfile do not include (stata.trk) in the archive
file

flat requests that the archive file(s) created should not
contain a directory structure

single instead of creating a joint archive file for all packages
requested, create a single archive file for each pkglist

saving(filename) save output archive as
filename; if filename is specified without a file extension,
.zip is assumed

replace replace the output archive file(s), if already
present

checksums activate Stata's checksum mechanism before downloading
files

verbose give verbose output

pgkspec options
from(directory_or_url) requests to use directory_or_url as
installation source; the special keyword "ssc" is allowed (and used as
default if the option is omitted), any other content will be passed through to
net install

all also download ancillary files; will be passed through to
net install or
ssc, respectively

notrackfile do not include (stata.trk) in the archive
file

flat requests that the archive file(s) created should not
contain a directory structure

saving(filename) save output archive as
filename; if filename is specified without a file extension,
.zip is assumed

replace replace the output archive file(s), if already
present

Description

zippkg is a tool to download community-contributed content from the
internet, and create a ZIP archive from it. Its purpose is to ease the
distribution of such content to machines not connected to the internet, be it
in data centers, secure enclaves, or any other scenario.
Also, it may help
in equipping new Stata installations with a set of preinstalled packages.

Downloading several packages from different sources is supported via a syntax
mechanism similar to the one of graph twoway; both
variants (||-separator notation and ()-binding notation) are
supported.
When using zippkg this way, some options are available as
"global" options to zippkg only, while others are available as in the
scope of each pkgspec as well. See section options
for a detailed description of the options, and an overview table showcasing
option availibility.

Options

Availability of options:

option name zippkg option pkgspec
option

from() yes yes

all yes yes

saving() yes yes

notrackfile yes yes

flat yes yes

replace yes yes

single yes no

checksums yes no

verbose yes no

If an option is specified both as zippkg option and pkgspec
option, the pkgspec option always takes precedence.

downloading

Options for downloading content:

from(directory_or_url) requests to use directory_or_url as
installation source for the packages in pkglist. It will be passed through
to net install, unless the special keyword
"ssc" is specified.
The special keyword "ssc", which is
the default if the option is omitted, makes zippkg use the command
ssc install for package installation instead of
net install in order to use the
Statistical Software Components
(SSC) archive as installation source.

all requests to also download ancillary files (and include in the
resulting archive file). It will be passed through to
net install or
ssc (if SSC is the installation source).

Note that ancillary files that have been downloaded that way always are placed
at the top-level directory of the created archive file, regardless of the option
flat. This may induce errors in creating the archive file in case two
packages ship ancillary files with the same name.

checksums requests to activate Stata's checksum (see
help checksum) mechanism before downloading files. When
specified, zippkg will "set checksum on" before downloading files,
and reset the setting afterwards.

ZIP options

Options creating the ZIP archive:

saving(filename) requests the archive file created to be named
filename. If filename is specified without a file extension,
.zip is assumed.
If the option is omitted (and the zippkg
option single is not specified), "./zippkg.zip" will be used as
the default. This will create a file named zippkg.zip in the current
working directory of Stata.
If the option is omitted and option
single is specified, the default is to create archives named
zippkg#.zip in the Stata's working directory, where # denotes a
running integer.
Options single and
saving(filename) are mutually exclusive as zippkg options, with
single taking precedence if both are specified.

notrackfile specifies that Stata's internal tracking file of
installed packages (stata.trk) not be included in the archive file(s).

flat requests that the archive file(s) created should not contain a
directory structure. By default, the archive file(s) will contain the typical
directory structure Stata uses in the PLUS directory (see sysdir). When
the option flat is specified, all files will be saved in the top-level
directory of the archive(s).

replace requests to overwrite existing archive, instead of aborting
with an error message.

single requests that single archive files will be created for each
pkglist downloaded, instead of a joint archive file for all packages. Each
of the single archive files will be named zippkg#.zip, and saved
to Stata's current working directory. In the archive name, # denotes a
running integer for the pkglist
This option literally is a shortcut
to manually specifying saving(zippkg#.zip) in each pkgspec
manually.
Options single and saving(filename), when specified
as global zippkg options, are mutually exclusive, with single taking
precedence if both are specified.
In the scope of pkgspec options,
saving implies single.

advanced

verbose gives verbose output during the process. This may be
desired to identify downloading problems.

Remarks

zippkg will reset the installation directories for net to its
factory defaults (i.e. it executes "net set ado PLUS" and
"net set other" after downloading files). This may modify user settings,
if the default paths have been changed. Please contact the author if you have a
good idea on how to prevent this.

The source code of the program is licensed under the
GNU General Public License version 3 or later.
The corresponding license text can be found on the internet at
http://www.gnu.org/licenses/ or in gnugpl.

Examples

Download packages fre and catplot from SSC:

. zippkg fre catplot

Download packages fre and catplot from SSC , and sjlatex
from https://www.stata-journal.com/production:

. zippkg (fre catplot) (sjlatex ,
from("https://www.stata-journal.com/production"))

Do the same, but using the ||-separator notation rather than
the ()-binding notation:

. zippkg fre catplot || sjlatex ,
from("https://www.stata-journal.com/production")

Download the same packages, but place each in its single archive
file:

. zippkg (fre catplot) (sjlatex ,
from("https://www.stata-journal.com/production")) , single

Do the same, but using the ||-separator notation rather than
the ()-binding notation:

. zippkg fre catplot || sjlatex ,
from("https://www.stata-journal.com/production") || , single

Download the same packages, but use a custom file name for the resulting
(joint) archive:

. zippkg (fre catplot) (sjlatex ,
from("https://www.stata-journal.com/production")) ,
saving(my_packages.zip)

Download four packages from SSC, but save separate archive files with
their authors' names:

. zippkg (fre estout , saving(jann_pkgs.zip)) (catplot missings,
saving(cox_pkgs.zip))

Author

Daniel Bela (daniel.bela@lifbi.de),
Leibniz Institute for Educational Trajectories (LIfBi), Germany.

Support via https://github.com/dirtyhawk/stata-zippkg.

Also see

net, ssc, checksum