Single-header C library is causing linking errors. How can I restructure the project to fix this?

I'm currently using small3dlib with SDL to try and make a simple 3D game.

I included the library to my C project by simply putting the headerfile into my source directory, and I made two files, gfx.c and gfx.h, to serve as the graphics control for the entire project.

My current project structure looks like this:

tsa-3d/
| bin/
| build/
| src/
|-- gfx.c
|-- main.c
|-- include/
|---- gfx.h
|---- logger.h
|---- loggerconf.h
|---- models.h
|---- small3dlib.h
|---- tgc.h
|-- lib/
|---- logger.c
|---- loggerconf.c
|---- tgc.c
|-- models/
|---- carModel.c
|---- cityModel.c
|---- cityTexture.c

Of these, the only files that include small3dlib (indirectly) are main.c, gfx.c/.h, models.h, and all of the models.

The library requires that a few macros are defined before being included, so I am required to call my graphics interface header gfx.h rather than small3dlib.h each time.

#ifndef GFX_H
#define GFX_H

#define S3L_FLAT 0
#define S3L_NEAR_CROSS_STRATEGY 3
#define S3L_PERSPECTIVE_CORRECTION 2
#define S3L_SORT 0
#define S3L_STENCIL_BUFFER 0
#define S3L_Z_BUFFER 2

#define S3L_PIXEL_FUNCTION draw_pixel

#define S3L_RESOLUTION_X 640
#define S3L_RESOLUTION_Y 480

#define TEXTURE_W 256
#define TEXTURE_H 256

#define WINDOW_TITLE "hello, world"

#include <SDL2/SDL.h>
#include <stdint.h>
#include "small3dlib.h"
#include "models.h"

...

As a result of this layout, I have the following linking error for every function defined within small3dlib.h:

/usr/bin/ld: src/main.o:(.bss+0x0): multiple definition of `S3L_zBuffer'; src/gfx.o:(.bss+0x0): first defined here
/usr/bin/ld: src/main.o: in function `S3L_zBufferRead':
main.c:(.text+0x7d): multiple definition of `S3L_zBufferRead'; src/gfx.o:gfx.c:(.text+0x7d): first defined here
/usr/bin/ld: src/main.o: in function `S3L_zBufferWrite':
main.c:(.text+0xb9): multiple definition of `S3L_zBufferWrite'; src/gfx.o:gfx.c:(.text+0xb9): first defined here
/usr/bin/ld: src/main.o: in function `S3L_mat4Copy':
...

I had the same problem for all of the models as well (all were sourced from the project and had variable/function definitions in the headers originally until I split them into just .c files and a single shared header.

I've looked around as much as I can and I'm not sure what I need to do to fix this. I'm aware that variable and function definitions are not supposed to go into header files, but this entire library is built around having all definitions in a singular header. All of the example programs for this library have small3dlib.h included by only a singular .c file, so in that case, how is this library intended to be used when included by multiple files?

The full code for the project thus far can be found here. It is an attempted adaptation from the city example on the library's repository

I have tried splitting up the library into a headerfile and a source file so that all of the functions would now simply be prototyped in the header. This option failed because the header itself is incredibly large, and converting each function definition to a declaration and knowing which functions need to be converted and which don't is tiresome and tedious for 2800 lines of C. After attempting it for about half an hour, I assumed that I am most likely just doing something wrong in attempting to link the library, and that the library is most likely not at fault for this issue.

Edit: This is a minimal reproducible example of this:

Here is an example of what is going on here:

file structure:

project/
| Makefile
| src/
|-- main.c
|-- foo.c
|-- include/
|---- something.h
|---- lib.h

Makefile

# Global

SRC := $(wildcard src/*.c) \
	   $(wildcard src/**/*.c) \
	   $(wildcard src/**/**/*.c) \
	   $(wildcard src/**/**/**/*.c)

OUT := program

# Default Build

EXE := ./build/${OUT}
CFLAGS := -I./src/include
LIBFLAGS := -lSDL2 -ldl
OBJ := ${SRC:.c=.o}

build: clean-obj dir ${OBJ}
	gcc ${OBJ} -o ${EXE} ${CFLAGS} ${LIBFLAGS}
	${call clean-obj}

%.o: %.c
	gcc -c $< -o $@ ${CFLAGS}

run: build
	./bin/${OUT}

# Utility

dir:
	mkdir -p ./bin ./build/

clean-obj:
	rm -f ${OBJ} ./bin/*

clean: clean-obj
	rm -f ${EXE}

lib.h -> representation of small3dlib.h

#ifndef LIB_H
#define LIB_H

#include <stdint.h>
#include <stdio.h>

#ifndef SOME_MACRO
    #error SOME_MACRO NOT DEFINED!
#endif

#define ARRAY_LENGTH 3
const uint8_t array[ARRAY_LENGTH] = { 1, 2, 3 };

void hello(uint8_t x) {
    for (uint8_t i = 0; i < x; i++)
        printf("%d", i);
}

#endif

something.h

#ifndef SOMETHING_H
#define SOMETHING_H

#define SOME_MACRO 3
#include "lib.h"

void bar();

#endif

main.c

#include "include/something.h"

int main(int argc, char* argv[]) {
    hello(array[2]);
    bar();
}

foo.c

#include "include/something.h"

void bar() {
    hello(8);
}

This results in:

...
/usr/bin/ld: src/main.o:(.rodata+0x0): multiple definition of `array'; src/foo.o:(.rodata+0x0): first defined here
/usr/bin/ld: src/main.o: in function `hello':
main.c:(.text+0x0): multiple definition of `hello'; src/foo.o:foo.c:(.text+0x0): first defined here
collect2: error: ld returned 1 exit status
make: *** [Makefile:18: build] Error 1

Header-file-only libraries are ... erm ... not easy to handle. You cannot include them in more than one translation unit (vulgo source). Else you have as many definitions as translation units that included it, and in consequence build errors. Plus, there is a potential mismatch in their controlling #defines.

Therefore, as for your example, you need to write an implementation that provides the single translation unit. I named it "lib_impl.c". To centralize the necessary definitions, I wrote a separate header file, named "lib_defs.h":

#ifndef LIB_DEFS_H
#define LIB_DEFS_H

#define SOME_MACRO 3

#endif

Unfortunately you need to write a separate header file, which contains all the declarations of the objects you use in your application. You don't need to declare all possible objects of the library. I named it "lib_decl.h":

#ifndef LIB_DECL_H
#define LIB_DECL_H

#include <stdint.h>

extern const uint8_t array[];

void hello(uint8_t x);

#endif

The single implementation file is this:

// lib_impl.c

#include "lib_defs.h"
#include "lib_decl.h"

// Actually, this is a source file, not a header file!
#include "lib.h"

You can let the compiler check that you wrote this declaration header file correctly, if you include it in the implementation file.

You can now include the declaration header file where you need to access the library's objects.

In your example, you seem to use some kind of "global" include file, "something.h". Apparently it collects the declarations of multiple modules:

#ifndef SOMETHING_H
#define SOMETHING_H

#include "lib_decl.h"
 
void bar();

#endif

All other files are unchanged, and the application builds without problems.

Note 1: Since you provide the path to the include files to the compiler, you don't need to use "include" in the #include directives.

Note 2: When removing all object files, in general intermediate files, you drop a main feature of "make": Run only the necessary commands to build dependent target files.

Final note: I understand why authors like header-file-only libraries. It is just one file to maintain. However, this comes with several disadvantages:

1. A user needs to #define all the features that she wants to use.
2. If the library gets bigger, it becomes a bloated piece of source without any organization on the file level.
3. Users are urged to include it only in one translation unit.

This actually removes one-time effort from the library's author and gives it to each user, multiplying the effort by the number of usages. Judge for yourself.