DETAILS Reference

Example of a typical DETAILS file: 

           SPELL=foo
         VERSION=001
          SOURCE=${SPELL}-${VERSION}.tar.bz2
         SOURCE2=${SOURCE}.asc
SOURCE_DIRECTORY=$BUILD_DIRECTORY/${SPELL}-${VERSION}
   SOURCE_URL[0]=http://example.com/dir/misc/$SOURCE
   SOURCE_URL[1]=http://backup.example.com/dir/misc/$SOURCE
     SOURCE2_URL=http://example.com/dir/misc/$SOURCE2
      SOURCE_GPG="name.gpg:${SOURCE2}:VERIFIED_UPSTREAM_KEY"
     SOURCE_HASH=sha512:...:WORKS_FOR_ME # Collapsed for brevity
  SOURCE2_IGNORE=signature
        WEB_SITE=http://www.example.com
         ENTERED=20100610
      LICENSE[0]=GPL
         UPDATED=20100616 # Deprecated. Replace with PATCHLEVEL and
                          # SECURITY_PATCH
      PATCHLEVEL=1 # Optional if 0
  SECURITY_PATCH=0 # Optional if 0
        KEYWORDS="example keywords"
           SHORT="This is a one-line brief description"
cat << EOF
Description that is wrapped to 80 columns or less.
EOF

Note well that most DETAILS files differ in order of variables from one another. There is not yet a standardized order as of 2010-07-08. Generally, the dependencies upon one another determine the order, or how they need to be grouped together within if statements. From this SOURCE and VERSION are usually the first two variables, and SHORT and cat << EOF are usually the last two.

The descriptions of all standard variables in a DETAILS file are below, in alphabetical order with all [:uppercase:] being alphabetically superior to all [:lowercase:]. Each set of variables are separated by common and grimoire-special categories. This is not a list of all possible variables that have been, are, or will be used in sorcery, as hacks are made to get around problems, like the source having a different capitalization than the spell name.

Common

ARCHIVE

  • This forces the enabling or disabling to archive a spell. The option is either "on" or "off". This should be set to "off" when the spell is a binary install. Otherwise, this should remain untouched, as this is a variable set by user's preferences.

DOCS

  • This marks the space-delimited files as documentation. This is used for installing extra documentation if the user specifies it in preferences.



ENTERED

  • This is the entry date of the spell in the format YYYYMMDD.

KEYWORDS

  • Keywords aren't in use at this time. They shouldn't be added.

LICENSE
LICENSE[n]

  • This is the license that the source is covered by. The second form is for

    multiple licenses, where n is either 0 or a positive integer.

    The license acronyms available are listed on the page LicenseList. For other licenses, the URL should be listed.

PATCHLEVEL

  • This is the patchlevel of the spell, usually the left-most version marker. Increment this if a spell update should rebuild the spell on systems.

    Otherwise, remove it or set it to 0.

SECURITY_PATCH

  • This is the number of times the spell had to be updated because of a

    security reason. This number should never be reset.

SHORT

  • A short description of the package. The entire phrase should fit on one

    line in the DETAILS file, including the spacing for "\s*SHORT=".

SOURCE
SOURCEn

  • This is the name of the source file. For multiple sources, use the second

    form where n is a positive integer.

SOURCE_DIRECTORY
SOURCEn_DIRECTORY

  • This is the directory that the spell will be built in. Depending on the source archive, a directory may have to be created (e.g. if it is a tarbomb). For multiple source directories, use the second form where n is a positive integer.

SOURCE_GPG
SOURCEn_GPG

  • This is the information for GPG verification. Its general format is

    <pubkey file>:$SOURCE.gpg:<verification method>.

    Verification methods, in order of least-secure to most-secure, are:

    • WORKS_FOR_ME (No verification with upstream was done.)

    • UPSTREAM_HASH (Checked the upstream hash file)

    • UPSTREAM_KEY (Checked upstream (gpg) key, signature matched, but the key was not validated)

    • ESTABLISHED_UPSTREAM_KEY (Upstream key was not validated against multiple independent sources, but has been in use for several years)

    • VERIFIED_UPSTREAM_KEY (Upstream key id was verified against multiple independent sources.)

    • ID_CHECK_UPSTREAM_KEY (Key was verified in person with a photo id check.)


  • The topic of GPG is described in more detail in IntegrityCheckingReference.

    The second form is for multiple source verifications, there n is a positive integer.

SOURCE_HASH
SOURCEn_HASH

  • This is the information that sorcery needs for hash verification. The

    currently-used algorithm is sha512. Its format is <algo>:<hash>:<verification method>. This is described in fuller detail in IntegrityCheckingReference.

    The second form is for multiple hash verifications, where n is a positive integer.

SOURCE_IGNORE
SOURCEn_IGNORE

  • Sets the flag to ignore verifying the source archive. Reasons are:

    • signature (Source is a signature)

    • unversioned (Source changes, but not an scm)

    • volatile (Source scm pull such as subversion and git)

SOURCE_URL
SOURCEn_URL
SOURCE_URL[m]
SOURCEn_URL[m]

  • This is the location of the download. Sorcery will automatically determine

    what tool it needs to get the source by the prefix if it is one of cvs, dir, rsync, smgl_tla, svn, svn_http, svn_ssh, or git.

    The first form is for a single source download. The second form is for

    multiple source downloads, with n as a positive integer. The third form is for mirrors of the source in case previous URLs fail, there m is 0 or a positive integer. The fourth form is a hybrid of the second and third forms.

    If this is empty, then the user must grab the correct tarball theirself and

    place it in the spool directory, usually /var/spool/sorcery.

SPELL

  • This is the spell name. If creating a spell, the name should be lowercase

    with spaces replaced as underscores.

UPDATED

  • This is deprecated. Use PATCHLEVEL and SECURITY_PATCH instead.

VERSION

  • This is the version of the spell, including the patchlevel, if any. Spells

    with scm versions should list svn as their version if they should not update, and $(date +%Y%m%d) if they should. A spell should use if statements checking variables gathered from CONFIGURE to change the version accordingly.

WEB_SITE

  • This is the upstream website. This generally should go to the website that

    will lead to source downloads, bug reports, and mailing lists.

cat << EOF

  • This is the long description of the package. This should probably be less than 24 lines as a guide, but not required. This should be wrapped to 80 characters. The text ends with "EOF" on its own line, beginning the in the

    leftmost column.

z-rejected

REJECT

  • This is a short description of why a spell was rejected. This should be

    present.

DetailsReference (last edited 2010-07-09 07:46:18 by DonaldJohnson)