SMK User's Guide

The SMK build tool automatically determines, which pieces of a program need to be recompiled and issues commands to recompile them. It is similar in purpose to the popular make, scons and jam utilities. The smk utility works by reading one or more smkfiles, usually named SMK. The smkfiles construct a database of targets, their prerequisites and the commands, used to update the targets, when one or more prerequisite changes.

This edition documents SMK version 0.4.1.

[TBD: Explain what the following items actually mean.]

The smk utility is distributed under the terms of the GNU General Public License, version 2. A verbatim copy of the license is given in Appendix A, GNU General Public License.

In this section we will discuss a simple smkfile, which describes how to compile and link the venerable "Hello, World!" program.

We will have one source file, hello.c, with the following content:

$ cat hello.c
#include <stdio.h>

int
main ()
{
  puts ("Hello, World!");
  return 0;
}
    

Here's a straightforward smkfile, which describes how the program hello is built from the source file hello.c

$ cat SMK
smk.make_program ('hello', srcs = ['hello.c'])
    

The smkfile instructs the tool to make an executable program via the function smk.make_program. The first parameter of the function is the name of the program and the second is the list of the sources to the program. It can't be any simpler, can it ?

Now run the smk to build the program.

$ smk
    

Surprisingly, nothing happens. The reason is simple - we haven't told smk what to build. Let's try again:

$ smk ./hello
CC         hello.o
CC-LD      hello
$ ./hello
Hello, World!
    

This time everything worked as expected, we have successfully built the hello program and were able to execute it. Note, however, how did we tell smk what to build - using ./hello instead of simply hello. The difference and the need is explained in detail in the section called “Target specification”, for now it's sufficient to say that hello is taken as a literal name, whereas ./hello is replaced with the full path name of the target.

The smk command is not gratuitously verbose - in the normal mode of operation progress is reported via a short tag, designating the command being executed, and a short name of the target being built. This behavior can be modified using the -v (or --verbose) flag, which displays the full command line, and the -q (or --quiet) flag, which suppresses all progress messages.

Just like we are able to build the project, we should be able to clean it too. Fortunately smk can do this for us, by determining what should be cleaned, following the obvious rule - “Clean everything you can rebuild” or put it the other way, “Do not touch anything you CAN'T rebuild”. The smk command line option for cleaning is -c (or --clean) and similarly to building targets, we need to specify what to clean (ignore the SMK.cache file for now):

$ ls
SMK  SMK.cache  hello  hello.c  hello.o
$ smk -qc ./hello
$ ls
SMK  SMK.cache  hello.c
    

Explicitly naming the targets on the command line can become tedious and, naturally, with smk we can do better. With no targets given on the command line, the smk command defaults to building the all target. This is a phony target, one that is not really a name of a file, but whose sole purpose is to provide a name to a group of targets. This grouping is achieved by making our targets prerequisites for the phony one. Here's how:

$ cat SMK
hello = smk.make_program ('hello', srcs = ['hello.c'])
smk.env.all.depends (hello)
$ smk -v
cc -c -g -o hello.o hello.c
cc -g -o hello hello.o
$ ls
SMK  SMK.cache  hello  hello.c  hello.o
$ smk -qc
$ ls
SMK  SMK.cache  hello.c
    

What did we do here? The function smk.make_program has a return value - a Python object ^[1], which represents our program. The variable smk.env.all is the object, which stands for the built-in all target ^[2]. By invoking the method depends we set the hello program as a prerequisite for the all target, thus whenever we build or clean all we perform the corresponding operation on hello too.

Let's add another source file to our project, putting the key functionality of printing "Hello, World!" in a separate function:

$ cat hello-proc.c
#include <stdio.h>

void
print_hello ()
{
  puts ("Hello, World!");
}
$ cat hello.c
extern void print_hello ();

int
main ()
{
  print_hello ();
  return 0;
}
$
    

As we have already learned, we can add the new file to the project by simply listing it along with the hello.c name in the srcs parameter to smk.make_program as follows:

hello = smk.make_program ('hello', srcs = ['hello.c', 'hello-proc.c'])
    

An alternative way is to create a source object for the new source file:

hello_proc_c = smk.make_source ('hello-proc.c')
hello = smk.make_program ('hello', srcs = ['hello.c', hello_proc_c])
    

As we can see, we can mix strings and objects in the srcs parameter of smk.make_program.

Yet another way to achieve our goal of adding more files to the project is to compile the source file and add the resulting object file object as a prerequisite to the hello program target using the objs parameter.

hello_proc_o = smk.compile_source ('hello-proc.c')
hello = smk.make_program ('hello', srcs = ['hello.c'], objs = [hello_proc_o])
    

We will conclude the section by adding yet another source file and using yet another way to create objects and specify dependency relations, using the function smk.make_object. The new source file is called goodbye-proc.c and contains the print_goodbye function. Accordingly, we modify the main to call the new function.

$ cat goodbye-proc.c
#include <stdio.h>

void
print_goodbye ()
{
  puts ("Goodbye, World!");
}
$ cat hello.c
extern void print_hello ();
extern void print_goodbye ();

int
main ()
{
  print_hello ();
  print_goodbye ();
  return 0;
}
$ cat SMK
hello_proc_o = smk.compile_source ('hello-proc.c')
goodbye_proc_o = smk.make_object ('goodbye-proc')
hello = smk.make_program ('hello', srcs = ['hello.c'],
                          objs = [hello_proc_o, goodbye_proc_o])
smk.env.all.depends (hello)
    

There are many more ways to create various source, object file, library, etc instances, which ways are specified in the section called “Factory functions”. Keep in mind that in all of the above cases, we actually ended up with the same set of objects ^[3], the only difference being in which objects we specified explicitly and which objects were created for us by smk.

Since the number of the source files started to grow, it's a good idea to reorganize our project a bit. Let's put the sources hello-proc.c and goodbye-proc.c in the subdirectory libhello and the main program source hello.c in the subdirectory src:

$ mkdir libhello
$ mv goodbye-proc.c hello-proc.c libhello/
$ mkdir src
$ mv hello.c src/
$ smk
Source file ``hello-proc.c'' cannot be located
    

The smk program is no longer able to find our files. We can fix the situation in several ways:

We choose the first method, explicitly naming the parent directory for each target.

Next, instead of linking with the object files, we create a static library and link to it. The library is created with the function smk.make_static_lib as follows:

libhello = smk.make_static_lib ('libhello/hello',
                                srcs = ['hello-proc.c', 'goodbye-proc.c'])
    

and we link to the library, by passing it to the smk.make_program via the libs parameter:

hello = smk.make_program ('hello', srcs = ['hello.c'], libs = [libhello])
    

Since we no longer need the variables hello_proc_o and goodbye_proc_o (which were put there for illustrative purposes anyway), we can simply delete them, ending up with the following smkfile:

$ cat SMK
libhello = smk.make_static_lib ('libhello/hello',
                                srcs = ['libhello/hello-proc.c',
                                        'libhello/goodbye-proc.c'])
hello = smk.make_program ('hello', srcs = ['src/hello.c'], libs = [libhello])
smk.env.all.depends (hello)
$ smk -v
cc -c -g -o libhello/hello-proc.o libhello/hello-proc.c
cc -c -g -o libhello/goodbye-proc.o libhello/goodbye-proc.c
cc -c -g -o src/hello.o src/hello.c
ar ruv libhello/libhello.a libhello/hello-proc.o libhello/goodbye-proc.o
ar: creating libhello/libhello.a
a - libhello/hello-proc.o
a - libhello/goodbye-proc.o
cc -g -o hello src/hello.o -Llibhello -lhello
    

It is worth noting that SMK supports platform independent naming of build objects - it transformed the generic hello library name into a name, appropriate for the current platform and build tools, namely libhello.a. On Windows, it would have created a library named hello.lib.

Our smkfile contains build instructions for both a library and a program. With several such libraries or programs a single smkfile would become too unwieldy. We will separate the build instructions in the subdirectories we already have and let the top smkfile process the sub-smkfile instructions.

The subdirectory smkfiles look as follows:

$ cat libhello/SMK
libhello = smk.make_static_lib ('hello',
                                srcs = ['hello-proc.c', 'goodbye-proc.c'])
$ cat src/SMK
hello = smk.make_program ('hello', srcs = ['hello.c'], libs = [libhello])
smk.env.all.depends (hello)
    

Note that we have removed the parent directories from the target names. The reason is that non-absolute pathnames are taken relative to the current source or build directory.

The subdirectory smkfiles are processed by the function smk.subdirs. This function takes a single parameter - a list of subdirectory names. Thus, the top level smkfile becomes simply:

$ cat SMK
smk.subdirs (['libhello', 'src'])
    

and we can see that everything works as expected:

$ smk -v
cc -c -g -o libhello/hello-proc.o libhello/hello-proc.c
cc -c -g -o libhello/goodbye-proc.o libhello/goodbye-proc.c
cc -c -g -o src/hello.o src/hello.c
ar ruv libhello/libhello.a libhello/hello-proc.o libhello/goodbye-proc.o
ar: creating libhello/libhello.a
a - libhello/hello-proc.o
a - libhello/goodbye-proc.o
cc -g -o src/hello src/hello.o -Llibhello -lhello
    

We should immediately point out that what we have now are not recursive smkfiles. All our smkfiles work towards creating a single database of targets and prerequisites. We call this global view of all dependencies and its immensive utility will become obvious when we discuss building from within subdirectories.

Note, that in our case, the order of the directories in the parameter to smk.subdirs matters. In the src/SMK smkfile we refer to the variable libhello, which should already by assigned to, thus it is important that libhello goes before src.

Following the rule “Do only one thing and do it well” we decide to create not one, but two programs - one outputting Hello, World! and another, outputting Goodbye, World!. The new program's source goes to src/goodbye.c and we modify src/hello.c accordingly. As usual for the libraries, we add a header file libhello/hello.h defining the public interface of the library, thus obtaining:

$ cat libhello/hello.h
#ifndef libhello_hello_h
#define libhello_hello_h 1
extern void print_hello ();
extern void print_goodbye ();
#endif /* libhello_hello_h */
$ cat src/hello.c
#include "libhello/hello.h"

int
main ()
{
  print_hello ();
  return 0;
}
$ cat src/goodbye.c
#include "libhello/hello.h"

int
main ()
{
  print_goodbye ();
  return 0;
}
    

Since both the hello and goodbye programs are built in a very similar way, we can take advantage of the fact that our smkfiles are fully fledged Python sources and write src/SMK thusly (cool, eh?):

$ cat src/SMK
programs = ['hello', 'goodbye']
for prog in [smk.make_program (x, srcs = [x + '.c'], libs = [libhello])
             for x in programs]:
    smk.env.all.depends (prog)
    

Unfortunately, if we attempt to build now, the compiler will fail for being unable to find the header file. We need to modify the way the source files are compiled.

Each project target has an associated command object - an object, which holds all the options, switches, settings, etc. necessary to execute the command, which updates the target. The command objects need not be unique, in fact, all the C source files in our project were compiled using the same object - the default C compiler object, referenced via the global variable smk.env.cc^[2].

In order to solve our problem, we should add the top level source directory to the include search path of the compiler. The top level source directory is held in the global variable smk.env.top_srcdir and we can modify the default include file search path via the method include of the default C compiler, smk.env.cc:

$ cat SMK
smk.env.cc.include ([smk.env.top_srcdir])
smk.subdirs (['libhello', 'src'])
$ smk -v
cc -c -g -I../step6 -o libhello/hello-proc.o libhello/hello-proc.c
cc -c -g -I../step6 -o libhello/goodbye-proc.o libhello/goodbye-proc.c
cc -c -g -I../step6 -o src/hello.o src/hello.c
cc -c -g -I../step6 -o src/goodbye.o src/goodbye.c
ar ruv libhello/libhello.a libhello/hello-proc.o libhello/goodbye-proc.o
ar: creating libhello/libhello.a
a - libhello/hello-proc.o
a - libhello/goodbye-proc.o
cc -g -o src/hello src/hello.o -Llibhello -lhello
cc -g -o src/goodbye src/goodbye.o -Llibhello -lhello
    

When specifying the include search path, we are completely unaware of the command line syntax of the concrete compiler tool. This knowledge is encapsulated in the compiler object itself, thus our smkfile is portable across different compilers.

Since we modified the default (and only) C compiler object, the include search path switch is passed unnecessarily when building the library objects too ^[5]. If this is considered undesirable, we should create a new compiler object, modify only it by the means of the include method and specify that the build of the hello.o and goodbye.o object files should use that compiler object. Probably the easiest way to obtain a new compiler object is to copy an existing one, via the SMK function smk.clone. We can use either one of the smk.make_object or smk.compile_source functions to assign the new compiler object the task of building the object files by using the named parameter build. Thus the src/SMK file becomes:

$ cat src/SMK
cc = smk.clone (smk.env.cc)
cc.include ([smk.env.top_srcdir])
programs = ['hello', 'goodbye']
for name in programs:
    obj = smk.compile_source (name + '.c', build = cc)
    prog = smk.make_program (name, objs = [obj], libs = [libhello])
    smk.env.all.depends (prog)
    

and we remove the unnecessary include path setting in the top level smkfile, so it becomes simply:

$ cat SMK
smk.subdirs (['libhello', 'src'])
    

And we will rebuild the project to make sure everything works as expected:

$ smk -qc
$ smk -v
cc -c -g -o libhello/hello-proc.o libhello/hello-proc.c
cc -c -g -o libhello/goodbye-proc.o libhello/goodbye-proc.c
cc -c -g -I../step6 -o src/hello.o src/hello.c
cc -c -g -I../step6 -o src/goodbye.o src/goodbye.c
ar ruv libhello/libhello.a libhello/hello-proc.o libhello/goodbye-proc.o
ar: creating libhello/libhello.a
a - libhello/hello-proc.o
a - libhello/goodbye-proc.o
cc -g -o src/hello src/hello.o -Llibhello -lhello
cc -g -o src/goodbye src/goodbye.o -Llibhello -lhello
    

Having a header file, we would like to be able to recompile the sources and rebuild the targets, which are affected by changes to it, i.e:

$ touch libhello/hello.h
$ smk -v
cc -c -g -I../step6 -o src/hello.o src/hello.c
cc -c -g -I../step6 -o src/goodbye.o src/goodbye.c
cc -g -o src/hello src/hello.o -Llibhello -lhello
cc -g -o src/goodbye src/goodbye.o -Llibhello -lhello
    

As we can see, smk solves this problem by itself, relieving us from the need to explicitly specify the header file dependencies. The smk scans the source files for preprocessor include directives. It uses the include file search path to find the header files and automatically makes them prerequisites for the target object file. Such a potentially time consuming operation is, of course, not performed on each build, but instead the implicit dependencies are stored (among other things) in a cache file - SMK.cache. SMK will recompute the implicit dependencies only when the corresponding source file changes. For all the other source files it will use the information in the cache file.

The generation of the implicit dependencies is customizable on a tool level. The generic C compiler (smk.tools.cc) uses a source file scan for preprocessor directives, whereas the GNU C compiler tool (smk.tools.gcc) uses the built-in GCC ability to automatically derive prerequisite header files ^[6].

A novel and, as of this writing, an unique feature of smk is its ability to support wide range of source and build directory dispositions with a single set of smkfiles, as well as its ability to perform builds from anywhere within the build tree, thus truly having a global view of all the dependencies.

$ smk -v -s debug
cc -c -g -o libhello/debug/hello-proc.o libhello/hello-proc.c
cc -c -g -o libhello/debug/goodbye-proc.o libhello/goodbye-proc.c
cc -c -g -I../step6 -o src/debug/hello.o src/hello.c
cc -c -g -I../step6 -o src/debug/goodbye.o src/goodbye.c
ar ruv libhello/debug/libhello.a libhello/debug/hello-proc.o libhello/debug/goodbye-proc.o
ar: creating libhello/debug/libhello.a
a - libhello/debug/hello-proc.o
a - libhello/debug/goodbye-proc.o
cc -g -o src/debug/hello src/debug/hello.o -Llibhello/debug -lhello
cc -g -o src/debug/goodbye src/debug/goodbye.o -Llibhello/debug -lhello
      

$ smk -v -o build -s release
cc -c -g -o build/libhello/release/hello-proc.o libhello/hello-proc.c
cc -c -g -o build/libhello/release/goodbye-proc.o libhello/goodbye-proc.c
cc -c -g -I../step6 -o build/src/release/hello.o src/hello.c
cc -c -g -I../step6 -o build/src/release/goodbye.o src/goodbye.c
ar ruv build/libhello/release/libhello.a build/libhello/release/hello-proc.o build/libhello/release/goodbye-proc.o
ar: creating build/libhello/release/libhello.a
a - build/libhello/release/hello-proc.o
a - build/libhello/release/goodbye-proc.o
cc -g -o build/src/release/hello build/src/release/hello.o -Lbuild/libhello/release -lhello
cc -g -o build/src/release/goodbye build/src/release/goodbye.o -Lbuild/libhello/release -lhello
      

$ touch src/hello.c
$ cd build/src/
$ smk -vs release
cc -c -g -I../../../step6 -o release/hello.o ../../src/hello.c
cc -g -o release/hello release/hello.o -L../libhello/release -lhello
      

In the section we'll create a simple double-precision postfix (a.k.a. “reverse polish notation”) calculator, using the example sources from the GNU Bison manual. The source files are as follows:

In smk, Bison parsers are created with the function smk.make_parser. The function takes as a first parameter the parser name and, optionally, as a second parameter the grammar file name. The function returns an object, which stands for the C source file of the parser. Since the output of the bison consists of two files, the header file with token definitions is available via the header member of the source file. The names of the parser source and the parser header are set to the value of the parser name with suffix .c or .h, respectively. However, unlike the case with other smk generated filenames, the parser source and header files are generated in the current source directory, unless the parser name parameter is a full pathname.

Here's the initial version of our smkfile, building only the objects for the moment:

rpncalc_c = smk.make_parser ('rpncalc')
smk.env.all.depends (smk.compile_sources (['main.c', 'rpnlex.c', rpncalc_c]))
    

However, when we attempt to build the project, we immediately get a problem:

$ smk -v
cc -c -g -o rpnlex.o rpnlex.c
rpnlex.c:4:21: rpncalc.h: No such file or directory
    ...
    

The file rpncalc.h is supposed to be generated by bison, but for some reason bison didn't even run. Explanation is simple - smk doesn't know it has to build rpncalc.h, because rpncalc.h is not a prerequisite to any target. How about automatic dependencies ? Unfortunately, the smk support for automatic dependencies generation is designed not to complain about missing dependencies, because it cannot in general decide whether a file is generated or there's insufficient information for finding it ^[9]. While it is possible in principle to keep building the project until the set of generated files (and thus the set of automatic dependencies) stabilizes, a design decision was made to explicitly specify such dependencies instead, like this:

rpncalc_c = smk.make_parser ('rpncalc')
rpnlex_o = smk.compile_source ('rpnlex.c')
smk.depends (rpnlex_o, rpncalc_c.header)
smk.env.all.depends (smk.compile_sources (['main.c', 'rpnlex.c', rpncalc_c]))
    

And we can build the project and see everything works fine:

$ smk -v
bison -d -o rpncalc.c rpncalc.y
cc -c -g -o main.o main.c
cc -c -g -o rpncalc.o rpncalc.c
cc -c -g -o rpnlex.o rpnlex.c
    

However, if we attempt to clean the project, we get another nasty “surprise” - the generated files are not removed:

$ smk -qc
$ ls
SMK  SMK.cache  main.c  rpncalc.c  rpncalc.h  rpncalc.y  rpnlex.c
    

This is not an error though. Each build node can be marked as precious, using its precious attribute. Precious nodes are not cleared by -c or --clean options, but only by -C and --realclean options ^[10]. In this particular case, the generated parser files were marked as precious by the smk.make_parser function.

We can continue now to building the calculator executable file:

rpncalc_c = smk.make_parser ('rpncalc')
rpnlex_o = smk.compile_source ('rpnlex.c')
smk.depends (rpnlex_o, rpncalc_c.header)
rpncalc = smk.make_program ('rpncalc', srcs = ['main.c', rpncalc_c],
                            objs = [rpnlex_o])
smk.env.all.depends (rpncalc)
    

But ^[11] if we attempt to build, the linking will fail due to an unresolved reference to the function pow. We should link with the math library libm.a, by passing its name to the function smk.make_program via the named parameter xlibs. Note the difference between libs and xlibs parameters - we can pass either filenames or build node objects via the former and the smk will create a dependency between the libraries and the program, whereas we can pass only library names via the latter and smk will pass them unchanged to the link editor tool for tool specific processing.

So, the smkfile becomes:

rpncalc_c = smk.make_parser ('rpncalc')
rpnlex_o = smk.compile_source ('rpnlex.c')
smk.depends (rpnlex_o, rpncalc_c.header)
rpncalc = smk.make_program ('rpncalc', srcs = ['main.c', rpncalc_c],
                            objs = [rpnlex_o], xlibs = ['libm.a'])
smk.env.all.depends (rpncalc)
    

and we can finally build and run the calculator:

$ smk -v
bison -d -o rpncalc.c rpncalc.y
cc -c -g -o main.o main.c
cc -c -g -o rpncalc.o rpncalc.c
cc -c -g -o rpnlex.o rpnlex.c
cc -g -o rpncalc main.o rpncalc.o rpnlex.o -lm
$ ./rpncalc
6 7 *
        42
10 2 5 ^ +
        42
    

While one of the features of the SMK is having platform independent specification of commands and dependencies, it nevertheless allows for full customization of the build process.

The command line option -f / --file can be specified more than once. The smkfiles, specified thusly, are executed in the same order as in the command line. The last such file is taken to be the “main” smkfile, in the sense that the top level source directory is set to its parent directory. This feature allows a project configuration to be separated between several platform dependent smkfiles and a fixed set of generic smkfiles. Consider the following (fictitious) examples:

Of course, SMK does not limit one to static configurations. After all the smkfiles, given by the -f options, are loaded, but before loading the last one, the one, which defines the top level source directory, SMK will look into the top level build directory for a file named SMK.cf and load it, if found. The SMK.cf is intended to be produced by a configuration tool, for example a configure script, produced by GNU Autoconf. It is loaded after all the static configuration files (if any), so it is able to override any settings in them.

The SMK leaves the choice of automatic vs. static configuration up to the package developer, without mandating any particular approach, and even allowing mixing approaches. Taking the Canadian cross example, the same configuration could be obtained by getting an automatic configuration tool to generate a SMK.cf file, similar to the following one:

smk.load (smk.env.top_srcdir + '/conf/build/linux.cf')
smk.load (smk.env.top_srcdir + '/conf/host/cygwin.cf')
smk.load (smk.env.top_srcdir + '/conf/target/mips-elf.cf')
    

For the purposes of the tutorial, we will write our SMK.cf files by hand, but remember, it is intended to automatically generated.

We'll continue the tutorial by going back to the “Hello, World!” example and making the static library into a shared one. The function, which creates shared libraries is smk.make_shared_lib, thus the libhello/SMK file becomes:

libhello = smk.make_shared_lib ('hello',
                                srcs = ['hello-proc.c', 'goodbye-proc.c'])
    

On most Unix systems, the shared objects must be compiled as position independent code. The generic compiler tool class, smk.tools.cc, is not capable of doing this, though, as POSIX does not specify ways to compile PIC objects and link shared libraries. Building shared libraries is inherently platform and tool specific, thus, in general, one needs additional platform and tool configuration settings. For the tutorial, we'll assume a generic ELF based platform, using GCC and GNU ld ^[12]

We can modify the default C compiler, by initializing the variable smk.env.cc to an instance of the class smk.tools.gcc. Likewise, we can modify the default linker, by initializing the variable smk.env.ld to an instance of the class smk.tools.gcc_ld. An appropriate place to put such initializations is the file SMK.cf in the top level build directory.

$ cat SMK.cf
smk.env.cc = smk.tools.gcc ()
smk.env.ld = smk.tools.gcc_ld ()
    

Each compiler tool must implement a boolean attribute, named pic and emit the necessary compiler options, needed to produce a PIC file, whenever this attribute is set to True. We will set this attribute in a copy of the default compiler setting object and build the library objects with the newly obtained compiler object.

$ cat libhello/SMK
cc = smk.clone (smk.env.cc)
cc.pic = True

objs = smk.compile_sources (['hello-proc.c', 'goodbye-proc.c'],
                            build = cc)

libhello = smk.make_shared_lib ('hello', objs = objs)
    

At this point we are ready with the smkfiles and can build the project:

$ smk -v
gcc -c -g -fPIC -Wall -W -o libhello/hello-proc.o libhello/hello-proc.c
gcc -c -g -fPIC -Wall -W -o libhello/goodbye-proc.o libhello/goodbye-proc.c
gcc -c -g -Wall -W -I../step7 -o src/hello.o src/hello.c
gcc -c -g -Wall -W -I../step7 -o src/goodbye.o src/goodbye.c
gcc -shared -g -o libhello/libhello.so libhello/hello-proc.o libhello/goodbye-proc.o
gcc -g -o src/hello src/hello.o -Wl,-rpath,/home/velco/smk-tutor/step7/libhello -Llibhello -lhello
gcc -g -o src/goodbye src/goodbye.o -Wl,-rpath,/home/velco/smk-tutor/step7/libhello -Llibhello -lhello
    

Several things are worth noting here. The compiler emits the proper compiler specific option for creating of PIC objects, -fPIC, as well as for creating a shared library, -shared. When linking the now dynamic executables, the compiler provided the proper runtime library search path (-rpath), so we don't need any environment variable settings or wrapper shell scripts or whatever in order to execute or debug the resulting programs.

Building shared libraries on Windows is a little bit different, but nevertheless we can make a portable smkfile. First we need the usual dllexport, dllimport blurb in the library header and the library source files.

In libhello/hello.h we have:

#ifndef libhello_hello_h
#define libhello_hello_h 1

#ifdef _WIN32
# ifdef HELLO_DLL
#  define HELLO_FUNC __declspec (dllexport)
# else /* !HELLO_DLL */
#  define HELLO_FUNC __declspec (dllimport)
# endif /* HELLO_DLL */
#else /* !_WIN32 */
# define HELLO_FUNC
#endif /* _WIN32 */

HELLO_FUNC void print_hello ();
HELLO_FUNC void print_goodbye ();

#endif /* libhello_hello_h */
    

And in libhello/hello-proc.c and libhello/godbye-proc.c, respectively:

#include <stdio.h>
#include "hello.h"

HELLO_FUNC void
print_hello ()
{
  puts ("Hello, World!");
}
    

and

#include <stdio.h>
#include "hello.h"

HELLO_FUNC void
print_goodbye ()
{
  puts ("Goodbye, World!");
}
    

When we compile the DLL itself, we have to define the macro HELLO_DLL, so the functions are exported from the library. This is done via the define method of the compiler object:

cc = smk.clone (smk.env.cc)
cc.pic = True
cc.define ('HELLO_DLL')

objs = smk.compile_sources (['hello-proc.c', 'goodbye-proc.c'],
                            build = cc)

libhello = smk.make_shared_lib ('hello', objs = objs)
    

We can proceed with building now:

d:\smk-tutor-win\step7>smk -v
cl.exe -nologo -c -Zi -W4 -DHELLO_DLL -Folibhello\hello-proc.obj libhello\hello-proc.c
hello-proc.c
cl.exe -nologo -c -Zi -W4 -DHELLO_DLL -Folibhello\goodbye-proc.obj libhello\goodbye-proc.c
goodbye-proc.c
cl.exe -nologo -c -Zi -W4 -I..\step7 -Fosrc\hello.obj src\hello.c
hello.c
cl.exe -nologo -c -Zi -W4 -I..\step7 -Fosrc\goodbye.obj src\goodbye.c
goodbye.c
link.exe -dll -nologo -incremental:no -debug -out:libhello\hello.dll -implib:libhello\ehlo.lib libhello\hello-proc.obj libhello\goodbye-proc.obj
   Creating library libhello\ehlo.lib and object libhello\ehlo.exp
link.exe -nologo -incremental:no -debug -out:src\hello.exe src\hello.obj -libpath:libhello ehlo.lib
link.exe -nologo -incremental:no -debug -out:src\goodbye.exe src\goodbye.obj -libpath:libhello ehlo.lib
    

By default, when building a Windows DLL, SMK generates an import library with the same name as the DLL ^[13]. We can use the implib parameter to smk.make_shared_lib in order to control the building of the import library. The default value of the parameter is True, which means that an import library should be built and its name must be derived from the name of the DLL. A value of False means not to build an import library at all, useful when the DLL will by used by loading it with LoadLibrary. And, finally, a string value allows the developer to specify a name and/or a location of the import library, as in the following example:

libhello = smk.make_shared_lib ('hello', objs = objs, implib = 'ehlo')
    

SMK supports package installation as an integral part of the build process. Install destinations are targets, dependent on the files being installed. In other words, installation is a special case of building ^[14], and an attempt to install a file results in first making sure it is up to date.

Install targets are created with the functions smk.install or smk.install_as. In both functions, the first parameter specifies where to install, while the second parameter specifies what to install. We can install the libhello.so library as follows:

smk.install ('lib', libhello)
    

If the first parameter is a relative pathname (as in the above example), SMK will append the pathname to the value of the variable smk.env.prefix, thus obtaining the parent directory of the installation target. The target will be installed under its base name, for example, if the value of smk.env.prefix was /usr/local, our library would be installed as /usr/local/lib/libhello.so.

Alternatively, if we wanted the library to be installed under a different name, we could have used use the function smk.install_as, in which the first parameter must denote a file name, as in the following example:

smk.install_as ('lib/libhello.so.0.2', libhello)
    

In addition to the library, we will install the header file, hello.h, and, if we have it at all, the import library, thus obtaining the following libhello/SMK file:

$ cat libhello/SMK
cc = smk.clone (smk.env.cc)
cc.pic = True

objs = smk.compile_sources (['hello-proc.c', 'goodbye-proc.c'],
                            build = cc)

libhello = smk.make_shared_lib ('hello', objs = objs)

smk.install ('lib', libhello)
smk.install ('include', ['hello.h'])
if libhello.implib:
    smk.install ('lib', libhello.implib)
    

The two programs, hello and goodbye are installed thusly:

$ cat src/SMK
cc = smk.clone (smk.env.cc)
cc.include ([smk.env.top_srcdir])

programs = ['hello', 'goodbye']

for name in programs:
    obj = smk.compile_source (name + '.c', build = cc)
    prog = smk.make_program (name, objs = [obj], libs = [libhello])
    smk.install ('bin', prog)
    smk.env.all.depends (prog)
    

The last thing left is to play an autoconfigurator again and specify a proper value of smk.env.prefix in SMK.cf ^[15] :

$ cat SMK.cf
smk.env.cc = smk.tools.gcc ()
smk.env.ld = smk.tools.gcc_ld ()
smk.env.prefix = '/home/velco/local'
    

Now we can execute the smk command with the -i (or --install) option and see what happens:

$ smk -qC
$ smk -vi
gcc -c -g -fPIC -Wall -W -o libhello/hello-proc.o libhello/hello-proc.c
gcc -c -g -fPIC -Wall -W -o libhello/goodbye-proc.o libhello/goodbye-proc.c
INSTALL    /home/velco/local/include/hello.h
gcc -c -g -Wall -W -I../step8 -o src/hello.o src/hello.c
gcc -c -g -Wall -W -I../step8 -o src/goodbye.o src/goodbye.c
gcc -shared -g -o libhello/libhello.so libhello/hello-proc.o libhello/goodbye-proc.o
gcc -shared -g -o ../../local/lib/libhello.so libhello/hello-proc.o libhello/goodbye-proc.o
gcc -g -o src/hello src/hello.o -Wl,-rpath,/home/velco/smk-tutor/step8/libhello -Llibhello -lhello
gcc -g -o src/goodbye src/goodbye.o -Wl,-rpath,/home/velco/smk-tutor/step8/libhello -Llibhello -lhello
gcc -g -o ../../local/bin/hello src/hello.o -Llibhello -lhello
gcc -g -o ../../local/bin/goodbye src/goodbye.o -Llibhello -lhello
    

Since we cleaned the project, a request for installation resulted in building the installation candidates and their prerequisites (which happened to be the entire project in our case). We have emphasized on the installation steps. Our header file is installed via an internal “install tool”, that's why its update command is denoted only by the tag INSTALL regardless of setting the verbose mode. Note how the programs are installed - by linking new executables, but, unlike when linking their in-project counterparts, without the runtime library search path options. The same would have happened to the shared library, if it had in-project shared library dependencies. The reason is that for installed dynamic executables and shared libraries, the location of their shared libraries dependencies should be specified in an operating system specific ways, e.g. via ldconfig(8) in GNU/Linux, and is considered beyond the scope of SMK. Targets without in-project dynamic library dependencies or on platforms, lacking -rpath (e.g. Windows), are installed by simply copying them, just like we did with the above header file.

Uninstallation is performed via the command line option -u (or --uninstall):

$ smk -u
UNINSTALL   libhello.so
UNINSTALL   goodbye
UNINSTALL   hello.h
UNINSTALL   hello
    

All --uninstall does is remove the installed files. It is not meant as a replacement for a real packaging tool.

[TBD]

The non-option arguments, i.e. the arguments, which do not begin with a dash (-) are considered to be target specifications. Target specifications come in three flavors:

$ find build
build
build/src1
build/src1/x.o
build/src1/y.o
build/src2
build/src2/x.o
build/src2/y.o
      

[TBD]

[TBD]

[TBD]