initial commitHEADmaster

7 files changed, 425 insertions, 0 deletions

diff --git a/README b/README
new file mode 100644
index 0000000..9e14b0f
--- /dev/null
+++ b/README
@@ -0,0 +1,4 @@
+This is a work in progress, early days.
+
+At some point it'll have to be something fancier than text files.
+Maybe RST that can get converted to HTML.
diff --git a/defs.txt b/defs.txt
new file mode 100644
index 0000000..9697d64
--- /dev/null
+++ b/defs.txt
@@ -0,0 +1,53 @@
+SBo - SlackBuilds.org. The website and git repository. Also, sometimes
+(incorrectly) used to mean a SlackBuild (as in "I installed the SBo
+for <whatever>").
+
+SlackBuild - hopefully this is obvious: A script (with accompanying .info
+file and README) that runs on a Slackware system and creates a Slackware
+package. In these HOWTOs, SlackBuild is used to specifically mean a
+SlackBuilds.org SlackBuild (unless otherwise stated).
+
+Package - Usually used to mean an installable Slackware package.
+These are .tgz (or .tgz, .tlz, etc) archives with a specific
+layout. Occasionally, the word "package" will be used to refer to the
+source archive or the SlackBuild itself. This is confusing, so try not
+to do it.
+
+Project - whatever your build is packaging. Usually this is a program,
+but it may also be shared libraries, data, or any combination of the
+above.
+
+Upstream - the author(s) and/or maintainer(s) of the project. Many
+projects ship a file called AUTHORS that tells who this is. Also,
+projects hosted on GitHub or GitLab have a username that
+owns/publishes the project.
+
+Tarball - an archive file, created with tar(1) and optionally
+compressed. In these HOWTOs, there are two types of tarball discussed:
+source tarballs (what your .info file lists as DOWNLOAD), and
+submission tarballs (what you upload to the SBo site, when you use the
+submission form; also, what you download from the SBo site when you
+download a SlackBuild).
+
+Maintainer - the person who's responsible for a given SlackBuild
+on SBo. When a SlackBuild is first submitted, this is the author.
+However, builds can change maintainership for various reasons, so the
+current maintainer might not be the original author.
+
+Orphaned - An orphaned build is one that has no maintainer. There's a whole
+FAQ about orphaned builds here [link]
+
+Tree - a copy of the SBo repository. This could have been created with
+"git clone", or rsync, or recursive wget.
+
+Mailing List - see [link]
+
+Build System - the software used to build a Project. Examples would be: make,
+autotools (aka ./configure), cmake, meson (and ninja). Most of these have
+build-system-specific templates [link]
+
+Binary Repack - A SlackBuild that simply creates a Slackware package
+from precompiled binaries released by the project's upstream. Usually
+(but not always), these have the suffix -bin in their SBo build names.
+The "source" for a binary repack can be a tarball, a single executable
+(rare), an AppImage, a package for another distro (.deb or .rpm), etc.
diff --git a/ideas.txt b/ideas.txt
new file mode 100644
index 0000000..8c6056c
--- /dev/null
+++ b/ideas.txt
@@ -0,0 +1,35 @@
+Definitions
+
+Things a SBo SlackBuild MUST do
+
+Things a SBo SlackBuild SHOULD do
+
+Things a SBo SlackBuild SHOULD NOT do
+
+Things a SBo SlackBuild MUST NOT do
+
+Package naming and categorization
+
+Writing READMEs
+
+Guide to .desktop files
+
+Guide to icons
+
+Build errors and tips on fixing them
+
+No-architecture (noarch) packages
+
+How to pass SLKCFLAGS to various build system types
+
+Realtime scheduling with filesystem attributes (jack and others)
+
+How to fix specific sbolint and sbopkglint errors
+
+Intro to repology
+
+Finding patches (in other distros' repos)
+
+Creating patches
+
+Writing man pages
diff --git a/intro.txt b/intro.txt
new file mode 100644
index 0000000..4cb3541
--- /dev/null
+++ b/intro.txt
@@ -0,0 +1,5 @@
+I'm writing or updating a SlackBuild, and I'm stuck. Can anyone help?
+
+Probably, yes. First, have a look at the SBo Maintainer HOWTOs. If
+your issue isn't addressed there, you can try asking on the mailing
+list or the IRC channel (#slackbuilds on irc.libera.chat).
diff --git a/must.txt b/must.txt
new file mode 100644
index 0000000..ee73844
--- /dev/null
+++ b/must.txt
@@ -0,0 +1,33 @@
+Things a SBo SlackBuild MUST do
+===============================
+
+- Create a valid Slackware package, of course. This includes a valid
+  install/slack-desc, a /usr/doc/$PRGNAM-$VERSION directory with
+  the package documentation (if any) and the SlackBuild.
+
+- The SlackBuild and software it installs must work on a full install of
+  the latest stable release of Slackware, with all patches applied. Do
+  not submit SlackBuilds that only work on -current, or require newer
+  libraries/etc from testing/. Binary repacks must not require a newer
+  glibc than Slackware -stable has. Currently (for Slackware 15.0),
+  this is glibc-2.33.
+
+- Install shared libraries in the correct directory. This is /usr/lib for
+  32-bit and /usr/lib64 for 64-bit.
+
+- Strip all binaries and shared libraries.
+
+- All files and directories must be owned by root:root, unless there is a
+  specific reason for them to be owned by someone else.
+
+- All directories must be mode 0755, unless there is a specific reason to
+  use some other permission.
+
+- All executables and shared libraries must be mode 0755, unless there's
+  a specific reason not to.
+
+- All non-executable files must be mode 0644, unless there's a specific
+  reason not to.
+
+- List any required dependencies from SBo in REQUIRES, in the .info file.
+  Required packages from Slackware are not listed.
diff --git a/naming.txt b/naming.txt
new file mode 100644
index 0000000..19bdec9
--- /dev/null
+++ b/naming.txt
@@ -0,0 +1,206 @@
+Guide to Naming and Categorizing SlackBuilds
+============================================
+
+Parts of this are requirements, and parts are matters of taste.
+
+Choosing a name
+---------------
+
+The easiest thing to do is use the upstream name of the project for
+the build name. For most builds, this is fine.
+
+Some of us prefer not to use uppercase in build names (whether
+ALLCAPS, MixedCase, or camelCase). It's perfectly OK for the build to
+have an all-lowercase name (in which case you'll likely use SRCNAM for
+the upstream name and PRGNAM will be your lowercase form). There's no
+*requirement* to avoid capitals letters; it's a personal preference.
+
+One thing we *don't* want to happen: Please don't submit a build
+that's the same name as another build, but with different case.
+We have libreoffice and LibreOffice, and it's a source of great
+confusion and annoyance. Eventually one of them will be renamed (to
+libreoffice-bin). Please don't make this worse by naming more builds
+this way.
+
+We have a few requirements for specific types of build:
+
+- Perl modules (aka libraries) must be in the perl/ category, have the
+prefix perl- on the build name, and be named after the module (or
+actually the CPAN/MetaCPAN distribution name), with sequences of ::
+characters replaced with a dash. For example, if the module on CPAN is
+called Ugly::Fruit, your build must be called either perl-Ugly-Fruit
+or perl-ugly-fruit. Note that just because something is *written in*
+perl, doesn't mean it has to have a perl- prefix or be found in the
+perl/ category. Applications belong in their appropriate categories.
+For instance, mobiperl is an application that converts between e-book
+formats, and it's in the office/ category (where the other e-book
+stuff is), and doesn't have the perl- in the name. Another example is
+games/pangzero.
+
+- Python modules (aka libraries) must be in the python/ category and
+have a python2- or python3- prefix. There are existing exceptions
+to this rule, which just have a python- prefix. This probably
+means the build installs both python2 and python3 versions of the
+module. This is discouraged for new builds, though: Please submit
+separate python2- and python3- builds, or just the python3- one if
+there's not a specific need for python2 support. As with Perl, just
+because something's written in Python, doesn't mean it's a module. As
+an example, iotop is written in Python 2, and lives in the system/
+category.
+
+- Ruby modules (aka libraries or gems) must be in the ruby/ category,
+and if they're gems (installed with "gem install"), must have
+a rubygem- prefix on the build name. As with Perl and Python,
+applications written in Ruby belong in their appropriate category.
+
+- Haskell libraries are similar: haskell- prefix and haskell/ category.
+Applications belong in their appropriate category.
+
+Occasionally, there will be a name conflict. Two completely different
+projects will use the same name. If you find an existing build in the
+repo with the same name as your proposed new build, you should rename
+your build. Made-up example: If e.g. it's a word processor called
+FastWord, and there's also a game called FastWord (or fastword) in
+the repo, you could rename your build to e.g. "FastWord-wordproc" or
+"fastword-wp". You could check repology.org to see how the ambiguity
+is resolved there.
+
+Choosing a category
+-------------------
+
+For some builds, the category is obvious. Games belong in games/.
+Ham radio stuff belongs in ham/.
+
+For some builds, it's not so obvious. We don't have categories for
+fonts or emulators, for instance. The catch-all category for
+things that don't seem to belong in any category has historically
+been system/... though we do have misc/.
+
+Some things seem to fit in more than one category. For instance,
+a program that downloads random images from the Internet, applies
+filters to them, then sets them as your desktop wallpaper... could
+legitimately be thought of as "desktop", "graphics", and "network".
+Most likely, this one would be in desktop/, since that's where its
+visible effect is.
+
+What you're looking for is the primary purpose of the software. A
+programming language that's designed for generating music would be
+better in audio/ than development/, even though programming languages
+normally go in development/.
+
+Some things have to be in a certain category (Perl, Python, Ruby,
+and Haskell libraries, as described above). Libraries that don't
+include an application (or that only include a simple "test" or
+"demo" command-line tool) belong in libraries/ (and no, a library for
+extracting CD audio wouldn't belong in either audio/ or multimedia/;
+those are for applications).
+
+The following list of categories shows what kinds of applications
+have historically been put in each, for applications we don't yet have
+categories for.
+
+academic/
+  Equation editors/resolvers.
+  Statistical analysis.
+  Bioinformatics.
+  Astronomy.
+  Calculators, especially 'scientific' ones.
+  Chemistry.
+  Educational.
+  Electronics Engineering.
+
+games/
+  Emulators for game consoles, or old computers with large game libraries (even
+  if they also had other kinds of software).
+
+system/
+  Text editors (as opposed to word processors, which go in office/).
+  Fonts.
+  Emulators, especially for old computers with lots of non-game software.
+  Encryption.
+  Shells (and shell-related utilities like completion).
+  Man pages (for non-English languages, mostly).
+  System monitoring.
+  Compression (and tools for recovering compressed files).
+  Filesystems (FUSE and otherwise).
+  Hardware drivers (printers, wireless cards, etc).
+  Password managers.
+  Terminal emulators (X/Wayland; also the serial port kind).
+
+office/
+  Office suites (obviously).
+  Speadsheets, word processors, presentation.
+  Anything to do with PDF or e-book (.epub, etc) files, whether it's a
+  viewer, an editor, or a utility to modify/create such files.
+
+graphics/
+  Comic book readers. Though at least one of these has ended up in
+  office/ instead... and an app that displays multiple e-book formats
+  (PDF/EPUB/etc), only one of which is comic books, should go in office/.
+  Image viewers and converters.
+  Screenshot creators.
+  Font editors.
+
+libraries/
+  Do not put applications here. Some libraries ship with a
+  config utility (e.g. wx-config for wxWidgets), or a simple
+  test app that isn't very useful byt itself; these don't count as
+  applications. Most of the time, if the upstream project name begins
+  with "lib", it belongs in this category.
+
+The list above is not exhaustive (even though I've gotten exhausted
+while writing it). You would benefit from looking at the repo and
+clicking on random builds in each category, to get your own idea
+of what things have been categorized as. Also note that there are
+no category police: there are builds that are probably in the wrong
+category. Don't take a single example as authoritative.
+
+Keywords
+--------
+
+In addition to the name and category of the build, you can choose a
+set of keywords that will be found by the website's search page.
+
+It's hard to guess up-front what people will search for, when they're
+looking for software by description/function rather than by name.
+This is where you can make up for the lack of a more specific
+category. E.g. a font editor that goes in graphics, you can
+include "font editor" as a keyword (yes, spaces are allowed).
+
+There is no need to include a build's name as a keyword. This just
+wastes a bit of space in our database. The site search will already
+find the build by its name.
+
+If you have a keyword, there's no need to include another keyword
+that's a substring of the longer one. Example: if you include
+"cross assembler", then there's no need to include either "cross" or
+"assembler" because the site search uses a substring match (searching
+for "cross" will also find "cross assembler").
+
+Specific hints:
+
+For an emulator, you should include "emulator" as a keyword, plus the
+name of the system it emulates, possibly with variant spellings (e.g.
+"c64", "c-64", "c=64", "commodore 64" for the Commodore 64). If it
+emulates a whole line of computers (e.g. atari800 emulates the 400,
+800, 800XL, etc), you can include the different models as separate
+keywords. You might also want to include the CPU the emulated system
+uses (e.g. "6502" for atari800).
+
+For assemblers, "assembler" (or "cross assembler if that's its
+purpose), "asm", and the name(s) of the platform(s) it assembles code
+for (which should include both the CPU architecture and the system
+name(s) if it produces executables for specific systems).
+
+For image or document file viewers/editors/converters, the filename
+extensions of the files it supports (e.g. png, gif, webp), if it's
+not already part of the build name (e.g. gifsicle doesn't need "gif"
+as a keyword, though "gif89a" would be a good one since it's the full
+name of the file format). MIME types would also be good candidates,
+such as image/gif (though make sure you use MIME types that actually
+exist; see the output of "file --mime-type" or the contents of
+/usr/share/mime/).
+
+If you're going to include "regular expression" as a keyword, you
+should also include "regexp" (which will match searches for either
+"regex" or "regexp").
diff --git a/version.txt b/version.txt
new file mode 100644
index 0000000..dd95c1b
--- /dev/null
+++ b/version.txt
@@ -0,0 +1,89 @@
+Guide to SlackBuilds.org Version Numbers
+========================================
+
+For the most part, you should just use upstream's version number.  The
+only restriction there is that - (hyhen) characters are not allowed in
+Slackware package version numbers. This is a limitation of Slackware's
+pkgtools, so it applies to all SlackBuilds, not just SBo ones.
+
+Illegal Characters
+------------------
+
+If upstream's version number has a - in it, such as "1.2.3-4", change
+it to an underscore (_) and use code like this in the SlackBuild:
+
+VERSION="${VERSION:-1.2.3_4"
+SRCVER="$( echo $VERSION | tr - _ )"
+
+The second line could also be written as:
+
+SRCVER="${VERSION//-/_}"
+
+...which is either more readable, or a hideoous abomination, depending
+on your background.
+
+Packaging a git/SVN/etc Commit
+------------------------------
+
+Sometimes, the software you're packaging doesn't have releases,
+or else the latest release can't be packaged because it contains
+bugs that have been fixed in a later git/svn/etc revision. If you
+have to package a git revision, please don't just use the git commit
+(e.g. a912dead). These are annoying because they can't be sorted or
+compared. SVN revisions do increase so you can sort or compare them,
+but it's still better to use a more informational version number. It's
+recommended that you use either:
+
+[version]+[date]_[revision]
+
+...where [version] is the latest release, [date] is the 8-digit ISO
+date (YYYYMMDD format), and [revision] is the git/SVN/etc commit,
+or else:
+
+[date]_[revision]
+
+...if the upstream project has never done a release.
+
+Examples:
+
+VERSION="1.0+20260829_a912dead"
+VERSION="20260829_a912dead"
+
+If you're packaging a git commit, you'll have to either find a URL
+for a tarball (see github.txt, gitlab.txt, codeberg.txt), or find a
+way to host it on a web server (see hosting.txt).
+
+No Version Number
+-----------------
+
+Some projects just don't have a version number. Usually these are
+simple "one-off" utilities that Just Work and don't need later
+updates (for examples, see system/crc32_simple and audio/alsacap).
+
+The best way to choose a version number for these, if you can't
+find a version in any of the files inside the tarball, is just to
+take the modification date of the newest file in the archive.
+For alsacap, after downloading the source:
+
+$ tar xvf alsacap.tgz
+alsacap/alsacap.c
+alsacap/alsacap.1
+alsacap/alsacap.pod
+alsacap/Makefile
+alsacap/LICENSE
+$ cd alsacap/
+$ ls -lt
+total 40
+-rw-r----- 1 urchlay users 18660 Aug 21  2020 alsacap.c
+-rw-r----- 1 urchlay users  7795 Apr  4  2013 alsacap.1
+-rw-r----- 1 urchlay users  3500 Apr  4  2013 alsacap.pod
+-rw-r----- 1 urchlay users   306 Apr  4  2013 Makefile
+-rw-r----- 1 urchlay users   784 Apr  4  2013 LICENSE
+
+The newest file is listed first. It's Aug 21, 2020, so the
+VERSION for alsacap is 20200821.
+
+Another thing to beware of when packaging a tarball without a
+version in the filename is md5sum mismatches, if upstreams changes the
+tarball. This is especially a problem for active projects that provide
+only a "project-latest.tar.gz". See download.txt for more information.