20210528 - a Slackware upgrade causes the page rendering to fail. Apologies and I am looking for the cause.
Reported as https://forum.dokuwiki.org/d/19270-dokuwiki-instance-no-longer-rendering-some-syntax-correctly

Welcome to the Slackware Documentation Project

This is an old revision of the document!


Anatomy Of a Slackbuild

Preamble

I guess all Slackware users will have used at sometime a SlackBuild script in order to create a package of software that could be easily and cleanly installed and removed later if needed. My experience was that I ran the SlackBuild script to create a package and never actually looked at the code it contained until one day the source version did not match that stated in the script.

Why would you bother looking at the code in a SlackBuild script? Well firstly you can use it if you are learning bash. Secondly you may not want to submit a SlackBuild script but perhaps you want to create a package that does not exists for software you want.

So here i would like to go through a SlackBuild script as best as I can (verbosely). I openly welcome edits from all others at all levels. In fact I think it important that people from all levels contribute. What is obvious to one person may need explaining to another person.

There are different approaches to a SlackBuild script and for instance Alien Bob has his very useful SlackBuild creator at : Aliens SlackBuild Toolkit

These days at SlackBuilds.org they prefer submissions using a SlackBuild template. I think it would be useful to go through a SlackBuild script which is currently on SlackBuilds.org. For this I will use the SlackBuild script I submitted for latex2html latex2html to SlackBuilds.org and which is currently available for Slackware 14.2 .

That way we are talking about a contemporary working SlackBuild script that you can actually download, use and hopefully relate to after reading this.

The other thing to mention is that the context of this page, when you read it, regarding a latex2html script is that a whole “slackbuild” from slackbuilds.org has been downloaded, is somewhere convenient (say on my desktop) that it is unpacked and into the unpacked directory called “latex2html” the software source called latex2html-2019.2.tar.gz has been placed.

Also that you have kick started the script :

bash-5.0# chmod a+x latex2html.SlackBuild 
bash-5.0# ./latex2html.SlackBuild 
Bash

In the days before Windows on Unix, a shell or Bourne Shell (Stephen Bourne, Bell Labs) was a way of communicating with the system. In a nod to Stephen Bourne , Brian Fox came up with a new version in 1989 and called it Bourne again Shell (bash).

If you open up a terminal in Slackware - say Menu → System → Console and type at the $ prompt:

bash --version

, you should get something like:

GNU bash, version 5.0.11(1)-release (x86_64-slackware-linux-gnu)
Copyright (C) 2019 Free Software Foundation, Inc.
License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>

In simple terms , the input was received and acted upon. The input is somewhat short lived, since when you close the window the input has gone.

A bash script in simple terms is bash code that can be saved as a file on say a hard drive.

The first line of a bash script has this line:

#!/bin/sh

This is commonly referred to as a shebang. This defines that the file is a shell script and also the path to the shell interpreter.

SlackBuild Script

We have so far described that a SlackBuild script is in essence bash code presented in a more permanent presentation of a file.

At the top is the shebang.

After that in line with slackbuilds.org requirements the next lines are the name of the package, who wrote the script and optionally a copyright notice is added.

I will attempt to go through the 14.2 latex2html slackbuild line by line. If there are blanks, it's a prompt for others to chip in. It also probably means I don't fully understand that bit.
PRGNAM=latex2html
VERSION=${VERSION:-2019.2}
BUILD=${BUILD:-1}
TAG=${TAG:-_SBo}

If I look at the package I have installed on my current 64 Bit Slackware it's : latex2html-2019.2-x86_64-1_SBo. Now if you look at the first line above you will see PRGNAM (program name). This is a variable and its value is set to the string latex2html.

The version is related to the software source release; if you go to the latex source web page, you will see that there was a source release on June 5th 2019. Thus I simply named the version after that release. For those learning bash (I still am): on the second line VERSION= on the left assigns a value to the variable called VERSION.

When assigning a value to VERSION, why use VERSION=${VERSION:-2019.2} and not simply VERSION=2019.2?
Take the expression ${VERSION}. This means “the value contained in variable VERSION”. The more complex notation ${VERSION:-2019.2} means “the value contained in variable VERSION, but if that variable does not yet have a value then use the default value of '2019.2'”.
So that second line simply boils down to VERSION=2019.2.
A value for VERSION can be set outside of the script: if you specified a value for VERSION on the SlackBuild command line or if it has been defined in your Bash environment.

In the same way the variable TAG is set to SBo and when the package is created this shows it's a “slackbuilt” package. If you look at packages in other repositories, you will see in the name eg chromium-77.0.3865.75-x86_64-1alien that the package is by Alien Bob.

The next block of code is as follows:

if [ -z "$ARCH" ]; then
  case "$( uname -m )" in
    i?86) ARCH=i586 ;;
    arm*) ARCH=arm ;;
    *) ARCH=$( uname -m ) ;;
  esac
fi

In computer programming languages such as php, python and others including bash there are common practices and logic. One common principle is the procedure of having a test in code. A test is applied and of course there will be a result depending on the outcome. An example of a bash “if” block statement is:

if[ test condition]
then
code to be executed depending on result
fi

In the above block, quite simply the “if” is the start of an If test condition and “fi” denotes the end of a If test condition.

Going back to bash for a minute you can set a bash variable like so

ARCH=something

and you can get the value of a variable and see what value the variable “ARCH” contains by putting a dollar sign in In front of it like so:

echo $ARCH

A -z flag can be used in an “if” statement to see if a string is empty. So lets have a look at the first line again and work out what it means.

if [ -z "$ARCH" ]; then

In the above we don't need to see the value of ARCH; as long as we can access its value and be able to use it in the script. So the first part before the “then” simply equates to , if the value of the variable ARCH is expressed as a string and its value is empty, do something. ARCH could represent a string value of the architecture of the PC the script is running on.

Another common algorithm is called in for instance php is the “switch statement” . This put in its simplest terms is a list and the test is to see if a certain value you have can be found in that list. If its not found you can place on the line last in the list would you would like to do, if nothing is matched.

In bash its in principle the same idea but its referred to as “case statement” .In principle you can put anything you like in the case block, but if you think about the fact we want to find out the “architecture” of a computer and already know there are only certain possibilities then it makes sense to try out a couple of known possibilities in the list first and if there is no match do something to get an answer. arm and i586 are of course two types of computer architecture.

Now if you try out this code in a terminal window:

uname -m 

it should display the architecture of you PC, in my case its x86_64.

So to summarize regarding the block of code. First an “if” statement is run to see if the variable “ARCH” is empty. If there is a value for the ARCH variable nothing in the block of the “if” and inner “case” will run;but if an empty string is found (ARCH has no value) a “case statement” is run(within the if block of code) to find a match.If a match was found the variable ARCH would be set to the value of the match found, and the execution of the case would come to a stop. If the ARCH variable was empty and no match was found in the case list , then the bottom line comes int play which is:

uname -m 

is used to get a result and ARCH set to the result.

Don't be fazed by the question mark in i?86 ,the question mark is a place holder that allows for possibilities via regex. it could be “3” (i386) , “6”( i686) etc.

Next block of code

CWD=$(pwd)
TMP=${TMP:-/tmp/SBo}
PKG=$TMP/package-$PRGNAM
OUTPUT=${OUTPUT:-/tmp}

Before we go into this let me have a look in my slackware file system and see whats there at /tmp/SBo.Taking a quick look at the image will give you a clue that the slackbuild works, by using the /tmp/SBo/ directory and creates a directory with the syntax package-packagename.So if we now have a look at the code above. CWD (current working directory) is a variable and is set to the value of pwd. If you run that in a terminal window, it will tell you where you in a bash context where you are working from.

TMP is going to be set to /tmp/SBo. Now lets have a look at

PKG=$TMP/package-$PRGNAM

You might guess PKG is going to be set for latex2html to :

/tmp/SBo/package-latex2html

If you look closely at the image (taking into account /tmp/SBo/ at top of image) you will see exactly that in the image.OUTPUT is set to /tmp

Next block of code:

if [ "$ARCH" = "i586" ]; then
  SLKCFLAGS="-O2 -march=i586 -mtune=i686"
  LIBDIRSUFFIX=""
elif [ "$ARCH" = "i686" ]; then
  SLKCFLAGS="-O2 -march=i686 -mtune=i686"
  LIBDIRSUFFIX=""
elif [ "$ARCH" = "x86_64" ]; then
  SLKCFLAGS="-O2 -fPIC"
  LIBDIRSUFFIX="64"
else
  SLKCFLAGS="-O2"
  LIBDIRSUFFIX=""
fi

Probably we need, before we look at the rest of the code for latex2html slackbuild to introduce some basic concepts.

Historically computer software is installed in a three step process called configure, make, make install. Configure gets ready to build the software , see if everything needed is there and builds a new make file. A make file is a file that contains instructions to build a program.

You can from the command line install software just using configure, make and make install. A slackbuild does the job of creating a package so that the process of installing is more manageable and reliable fashion. When you have a slackbuild downloaded on your system should there be a new release of source code its a simple matter of putting that source in your unpacked slackbuild and a quick edit to the slackbuild script.

Computer program source are written in “high level “ languages but are converted into a form that the computer can readily understand.Code written in the C language involves a C compiler converted it to binary.

The whole goal of any system installing a program, is that it should involve the concept of making it “tailor made” for the computer its being installed. Obviously that is going to involve the computer Architecture. During the compile process the system can be tweaked by passing in options from variables.

So lets now have a look at the block of code above. The block of code is simply an “if , else block” , where the code is executed top to bottom and amounts to -if the architecture is i586 set SLKFLAGS to .. if not go to next line.

CFLAGS and CXXFLAGS are variables holding values that can be passed in at compile time. We will see later that the variable SLKFLAGS will be used to set them.

Next block of code:

set -e
rm -rf $PKG
mkdir -p $TMP $PKG $OUTPUT
cd $TMP
rm -rf $PRGNAM-$VERSION
tar xvf $CWD/$PRGNAM-$VERSION.tar.gz
cd $PRGNAM-$VERSION
chown -R root:root .
find -L . \
 \( -perm 777 -o -perm 775 -o -perm 750 -o -perm 711 -o -perm 555 \
  -o -perm 511 \) -exec chmod 755 {} \; -o \
 \( -perm 666 -o -perm 664 -o -perm 640 -o -perm 600 -o -perm 444 \
  -o -perm 440 -o -perm 400 \) -exec chmod 644 {} \;

set -e: this stops the execution of the script if there is an error executing this code following this command
rm -rf $PKG: this deletes any previous directory (and contents) of package-latex2html at of /tmp/SBo/package-latex2html
mkdir -p $TMP $PKG $OUTPUT :mkdir with the “ -p ” flag creates directories, but only if they don't exist already.

that would be /tmp/SBo , /tmp/Sbo/package-latex2html, /tmp

Its unlikely that the SBo directory doesn't exist unless no other slackbuilds have been run in the past . /tmp should be there as default with the slackware installation.
cd $tmp : moves location where bash is working from to /tmp/SBo

rm -rf $PRGNAM-$VERSION will get rid of any previous directory entries(maybe failed) for latex2html-2019.2

tar xvf $CWD/$PRGNAM-$VERSION.tar.gz : This equated to unpacking of latex2html-2019.2, which would be inside the unpacked slackbuild from slackbuilds.org namely “latex2html”.


andy brookes 2019/12/12 20:43 (UTC)and iu embedding a little English.

Sources

I am using a SlackBuild script that i submitted to slackbuilds.org: https://slackbuilds.org/repository/14.2/academic/latex2html/?search=latex2html * Originally written by andy brookes


In Other Languages
Translations of this page?:
QR Code
QR Code howtos:misc:anatomy_of_a_slackbuild (generated for current page)