diff options
| -rw-r--r-- | README | 4 | ||||
| -rw-r--r-- | defs.txt | 53 | ||||
| -rw-r--r-- | ideas.txt | 35 | ||||
| -rw-r--r-- | intro.txt | 5 | ||||
| -rw-r--r-- | must.txt | 33 | ||||
| -rw-r--r-- | naming.txt | 206 | ||||
| -rw-r--r-- | version.txt | 89 |
7 files changed, 425 insertions, 0 deletions
@@ -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. |