How to Structure C Projects: These Best Practices Worked for Me

https://www.lucavall.in/blog/how-to-structure-c-projects-my-experience-best-practices

by ingve • 2 years ago

180 157 2 years ago

lucavall.in

foofie• 2 years ago

This sounds like a carbon copy of the project tree layout specified in C++'s pitchfork conventions.

https://github.com/vector-of-bool/pitchfork

Joker_vD2• 2 years ago

The downside of this approach is that you will need to keep the Makefile updated with the new files you add to the project so that they are compiled and linked correctly.

Does it? IIRC something like

    build/%.o: src/%.c include/*.h
        $(CC) -c $(CFLAGS) $(CPPFLAGS) -c -o $@ $<

works well enough for small projects.

seabass-labrax2• 2 years ago

You don't even need to specify that rule with GNU Make: building %.o is a built-in rule[1].

Personally, I tend to prefer specifying the files individually - it doesn't take up that much developer time nor much space in your Makefile, and makes it considerably easier to debug building issues when using a sandboxed environment (such as Nix or Bazel).

[1] https://www.gnu.org/software/make/manual/html_node/Catalogue...

Joker_vD2• 2 years ago

Doesn't the built-in rule put files in the wrong folder? That is, the same folder the source file is in?

lsllc• 2 years ago

I use make's `wildcard`, for example to locate all of my unit tests with the project sources (I don't use a `test` subdir):

  TEST_SRC = $(wildcard *_test.c)

If you follow TFA's guidelines about having a `src` dir, then:

  SRC = $(wildcard src/*.c)

And if you need to convert that to a list of matching .o files, `patsubst` is your friend:

  OBJ = $(patsubst %.c,%.o,$(SRC))

So now simply dropping a file into the right place (or a unit test ending in _test.c) won't require any makefile changes.

I tend to copy my most recent Makefile into my next project and generally it stays 90% the same (I have to edit a few macro definitions and rules, but not many).

aninteger• 2 years ago

I've always preferred Stephen Brennan's approach mentioned here: https://brennan.io/2020/05/08/meson/

This is the approach I take with my C and C++ projects, although I've swapped meson out for CMake. I still have my CMake projects generate pkg-config files as well so that I don't force CMake on any consuming projects (just because I suffered with CMake doesn't mean you have to, although you can as well :))

emmelaich• 2 years ago

FWIW practices is misspelled "pratices" twice.

Just remove best-practices, it's a silly phrase.

veltas• 2 years ago

Keeping .c and .h files separate is pointless, *.c and *.h can pick them out when necessary. 'include' is a good choice for libraries, the external interface, but not necessary for internal headers.

actionfromafar• 2 years ago

If you have a bunch of platform specific code it can be quite neat to have .c and .h files separately.

Then each platform gets its own directory with .c files.

masfoobar• 2 years ago

When I build C projects which, admittedly, is making a game, I always start off with platform specific code. This is very handy by splitting up .h and .c files.

ie... platform.h

platform_windows.c platform_linux.c etc.

This way, my build file for windows uses platform_windows.c, etcetc.

kerkeslager22• 2 years ago

This (among other reasons) is why I'm moving a few of my C projects over to Rust. Whenever I'm spending a half hour debugging why my build system isn't picking up some file or some flag is getting passed wrong, I end up asking myself, "Why am I doing this?"

My entire build system in Rust projects consists of the commands "cargo build", "cargo run", and "cargo test" and I have yet to find a reason to deviate from the default filesystem structure or configurations.

To be clear there are real reasons to still be writing C. No hate to the author of this post. I just don't want to be doing it any more in most cases.

colonwqbang• 2 years ago

Your problems are not with C the language but with the chosen build tools. Have you tried using a more modern tool like Meson? It is more comparable to Cargo.

To start a new project today using plain GNU Make like the author of the article recommends, is not a good idea unless you enjoy fiddling with the build.

flykespice• 2 years ago

Have you tried using a more modern tool like Meson? It is more comparable to Cargo.

Not comparable at all.

The difference is Cargo is the official standard package manager of the Rust language. Meson is one among the sea of incompatible build systems for the C language.

jjgreen• 2 years ago

With make, you don't have to install anything, it's POSIX

kerkeslager22• 2 years ago

Your problems are not with C the language but with the chosen build tools.

That's not a distinction I care about. The tooling around a language should be a part of discussing the merits of a language. Your language can be the most ergonomic language in the world, but if all your development gains are lost fiddling with build tools, you haven't gained anything.

Have you tried using a more modern tool like Meson?

I haven't, but now that I know about it, I'll give it a try. Thanks for the info! It looks promising.

To start a new project today using plain GNU Make like the author of the article recommends, is not a good idea unless you enjoy fiddling with the build.

Maybe, but that just brings up the problem that there isn't really a clear second-tier system outside the standard library for tools. Certain tools (i.e. Valgrind) are well-known, but there are a million different ways to install a million different tools and for most things it's ultimately more common to just roll your own.

nanolith12• 2 years ago

It is true that C does not have a single tool enforced by the language platform.

But, there is plenty of excellent documentation available for using build and packaging tools of your choice to work similarly to Cargo.

jerf3• 2 years ago

In practice this comes off as a rather motte and bailey argument. "There's plenty of ways to make building C as easy as Cargo." OK, show me. "Well, you use this and do this and this." OK, that didn't work because of $THIS_REASON. "Oh that's easy to fix you just do this thing." {Repeat several times.} OK, I guess it's working now, but there's no way that was as easy as cargo. "What are you talking about, it was a series of easy steps that only involved reading dozens of pages of docs, a couple of not-quite-current-but-close-to-accurate Stack Overflow posts, upgrading to the correct version of the build tool, and directly posting on a couple of mailing lists!"

To be honest, the moment I have to evaluate a dozen tools, pick one, and use it, even if that tool does manage to be "$TOOL build" and literally nothing else which I don't think is anywhere near something people can count on in the C world, it has already proved to be harder than "cargo build".

kerkeslager22• 2 years ago

But, there is plenty of excellent documentation available for using build and packaging tools of your choice to work similarly to Cargo.

Sure, and there's plenty of documentation for Cargo too. Or at least I assume there is, but I've never had reason to read it.

Do you see the problem with what you're saying?

lelanthran3• 2 years ago

Every C discussion on the net always gets derailed by Rust proselytising.

No other language community does this to other language discussion. Even C++ fanatics didn't do this back when C++ was being sold as a C replacement.

This is an entirely new and somewhat sad, phenomenon: the need for the rust community to derail any and all discussion about some other language reeks of a community that feels threatened.

twic• 2 years ago

The comment you're responding to wasn't written by "the rust community", it was written by kerkeslager, who has written a bunch of C programs, but has found that the Rust build tools are better. There is nothing new or sad about it.

keybored3• 2 years ago

Every <lang> discussion here gets sidetracked/sidethreaded by <lang2> mentions.

- Rust? Why not Nim?

- Nim? Why not Zig?

kerkeslager22• 2 years ago

1. I've written, at most, 10,000 lines of Rust. Calling me "the Rust community" is quite a stretch.

2. For comparison, I've almost certainly crossed the million lines of C mark years ago--if anything, I'm the C community.

3. You and I remember very different things about the C++ community. In fact, I also remember a number of other languages being offered as alternatives to C over the years including some obvious ones like Pascal or Basic, and also including some real absurdities like Lua (nothing wrong with Lua, but it's really not for the same kinds of projects as C). The idea that comparing your language to C is some sort of new phenomenon, is flat wrong.

4. You're ascribing a lot of intent to me bringing up Rust which isn't there. I'm not trying to derail the discussion--if you want to talk about C, do it.

5. The idea that the Rust community is threatened by C is a bit bizarre.

jvanderbot• 2 years ago

I have the same problem with Rust modules:

e.g., where do I put crate::, vs module X, vs module X{ } again? Do I have to specify it in the automatic lib.rs too? Or ...

C at least lives on the filesystem and you tell it where to grab things.

treyd• 2 years ago

Module definitions in Rust have simple rules that resolve `mod foo;` into foo.rs or foo/mod.rs, which lives in the filesystem layout just as it does in C, you just don't have to use quotes and it has to form a tree from a root module at lib.rs. If you want to be even more explicit about it there's an attribute you can put on a `mod` item to override the normal path resolution rules.

kerkeslager22• 2 years ago

e.g., where do I put crate::, vs module X, vs module X{ } again? Do I have to specify it in the automatic lib.rs too?

Sure, but there's one clear answer to that question which you can refresh your memory of in under 3 minutes of reading.

C does live in the filesystem, but where in the filesystem? Oh and it doesn't always live in the filesystem--sometimes it lives in the package system.

cmovq• 2 years ago

I don’t understand why people bother with complex build systems for small C projects.

Here is a C build system:

    cat all.c
    #include "foo.c"
    #include "bar.c"
    #include "main.c"

    clang all.c

eschneider• 2 years ago

#include "/dev/tty0"

so you can add run-time defines.

humanrebar5• 2 years ago

Now add an address sanitizer pass, reasonable unit tests, and wire it up to CI so you don't accidentally break things or trash memory.

kerkeslager22• 2 years ago

Sure, trivial problems only require trivial solutions. Obviously.

But I don't want to solve trivial problems. That's not where the value is.

hgs34• 2 years ago

"cargo build", "cargo run", and "cargo test"

What about "gcc mycode.c" or "make"? You shouldn't need to reinvent your build system every project.

kerkeslager22• 2 years ago

`gcc mycode.c` has to be some sort of joke you're making. I'm not trying to compile "Hello, world" in C, I'm writing C code that will be run in production to solve real-world problems.

For projects of any significant size, you're going to run into some constraint which requires you to use `make` differently than you have before.

fforflo2• 2 years ago

I'm not so sure about having bin/lib in the project dir.

I've found it more helpful to have a PREFIX=$(pwd)/build or even PREFIX=$HOME/.local as an installation destination. And have a .env add PATH=$PREFIX/bin:PATH

fforflo2• 2 years ago

I'm not so sure with having bin/lib in the project dir.

I've found it more helpful to have a PREFIX=$(pwd)/build or even PREFIX=$HOME/.local as an installation destination. And have a .env add PATH=$PREFIX/bin:PATH

Arch-TK3• 2 years ago

The recommended Makefile has several issues, not least of which being that it relies on dependency fulfilment order which can be non-deterministic (e.g. if you pass -j).

The project structure includes flavour-of-the-week litter like .devcontainer, .github, .vscode.

compile_commands.json should be getting generated, not stored.

Not sure if I would recommend anyone follow this information.

The build system situation in the C world is dire. And I should know, given I write my own build systems for C.

I would say, while I've never actually used it, Meson seems the least non-sensical out of the box experience.

Ideal in some ways but not in others is designing and implementing your own build system because genuinely everything else out there has some major shortcoming or other.

If you are insistent on make, stick to GNU make, read the GNU make manual, understand make and then write something simple and non-recursive.

This is the most recent Makefile I helped create:

    CXX ?= clang++
    CXXFLAGS += -std=c++20 -Wall -Wextra -fsanitize=address -ggdb3 -MMD -MP
    LDFLAGS += -fsanitize=address
    
    OBJ := program.o parse.o
    
    all: program compile_flags.txt
    
    program: $(OBJ)
            $(CXX) $(LDFLAGS) $(TARGET_ARCH) $^ $(LDLIBS) -o $@
    
    $(OBJ): Makefile
    
    compile_flags.txt: Makefile
            printf "%s\n" $(CXXFLAGS) >$@
    
    clean:
            $(RM) *.o *.d program compile_flags.txt
    
    -include $(OBJ:.o=.d)
    
    .PHONY: clean

If you want to do something like run a linter, code formatter, etc, before building, then this should be performed by a script which calls into make. Make is not designed to be used as a switch statement for your bash snippets.

ReleaseCandidat2• 2 years ago

The build system situation in the C world is dire.

Meta's Buck 2 (written is Rust) would be my choice, if I would write "new" C or C++.

Examples using Vcpkg

https://github.com/Release-Candidate/Cxx-Buck2-vcpkg-Example...

And Conan

https://github.com/Release-Candidate/Cxx-Buck2-Conan-Example...

humanrebar5• 2 years ago

If you're writing C, you might not want tools written in higher level languages required for your build environment.

This is why you still see a lot of important C project support autotools even though it's a pretty awful developer experience.

eska2• 2 years ago

It seems weird to me to write your own build system and give advice on build systems when your basic makefile already completely violates what the manual suggests.

Arch-TK3• 2 years ago

Unnecessarily vague and uncharitable comment but I'll bite.

While I recommend anyone who uses GNU make should read the manual, the manual is full of outdated best practices which can be safely ignored.

If I was going to use this makefile for my own project, I would even drop the clean target entirely. phony targets are mostly a misfeature. Although it looks like the makefile as accepted by the project hasn't marked the all target as phony.

But go on, tell me what it is that is not recommended specifically. I am aware of many deviations from what the GNU make manual claims is recommended. A large portion of deviations is the lack of many of the standard targets it thinks should be provided. Another deviation might be the uppercase OBJS should be lowercase according to the manual, but in this case I was trying to minimize the number of immaterial changes from the original makefile I modified to arrive at this point since it was not my project.

LabMechanic3• 2 years ago

You can consider using MinUnit and Clang-Tidy together with Clang-Format as well, further, for C it should be something more like this:

    CC = clang
    CFLAGS = -g -std=c2x -Weverything -fsanitize=undefined,address
    
    all: app.exe
    

    app.exe: src/main.c
      $(CC) $(CFLAGS) src/main.c


  clean:
    rm -rf /build

See my comment here with an example of an NMAKE Makefile. Consider:

https://nullprogram.com/blog/2017/08/20/

UncleEntity• 2 years ago

...not least of which being that it relies on dependency fulfilment order which can be non-deterministic (e.g. if you pass -j).

Didn't actually know that was a thing until I accidentally ran into it yesterday when I ran the make command in the wrong terminal window and the build was very, very unhappy.

At least it didn't bork my entire /home directory like that time we don't talk about...

My general rule is Make for simple things and CMake if it involves distro-packed library deps or I'm building python modules with complicated enough builds that I don't wan't to beat the dead horse of distutils into submission.

Honestly, if I can't tell what the build system is doing without having to ask google then it's way too complicated.

ReleaseCandidat2• 2 years ago

Am I missing something, or are the examples both projects with less than 20 C source files?

JonChesterfield8• 2 years ago

I write a lot of C. I'm somewhat prone to writing things in C that shouldn't be. There are two somewhat unusual things that make that more viable than it sounds.

One, write unit tests in the same source as the implementation. Tests that run through the interface are good too and can be in separate source files, maybe in another directory. Fine grain poke at the internals of static functions really should be written as well and those are best placed where they can call said static functions directly. Make adding tests really low friction and write lots of them.

Two, embrace code generators. I've seen it written that C++ solves problems by extending the language and C solves problems by writing more C and that sounds about right. Make adding a code generator as low friction as adding a C source file. It should take seconds to convert an existing source file into a generator that recreates said existing source file.

People love ceremony. All the source files are written in lists in cmake files. All their build dependencies are written down in the cmake files as well. All the tests are written in list of tests to run. Every code generator is introduced as an independent project with it's own documentation and careful integration into the build systems.

I love writing C because I do none of that overhead. The files to compile are whatever is on disk. The tests to run are all the tests in the source, they aren't listed somewhere else as well. Any file called *.lua.c is a lua program that writes the intended contents of *.c to stdout. *.c.h will be compiled as C and then run to write a C header on stdout.

Convention over configuration with a language that requires zero cognitive overhead to write.

memoryperson10• 2 years ago

Wild, I was just thinking about how I wanted to do reflection on C structs using LuaJIT FFI for serialization.

JonChesterfield8• 2 years ago

It's worth considering the other direction - write the struct definition in json or xml, or dicts in python source or whatever, and generate the C structs and the associated functions and data from that.

Go slightly further and write out function types like that and you get something equivalent to swig, where instead of parsing C and trying to emit wrappers for other languages from that framework, you have the data in native lua tables that you emit code from.

bluetomcat2• 2 years ago

In procedural C land, unit testing is nowhere near as relevant as it is in memory-safe OO lands. Assertions are far more relevant. You want to detect illegal program states in development as early as possible. In C11, you also have static_assert for things like "is this static lookup table as big as needed".

monsieurbanana2• 2 years ago

I get why assertions would be more important than in memory safe languages, but why are unit tests less important in C than in higher-level languages? Or you just mean relative to assertions? (which to me don't really influence each other in that way)

hgs34• 2 years ago

In procedural C land, unit testing is nowhere near as relevant as it is in memory-safe OO lands.

I'm not sure why you'd say this. Testing has more to do with the developer than the language. The SQLite project is written in C and has 590 times more test code than source code [1].

[1] https://www.sqlite.org/testing.html

iainmerrick• 2 years ago

People love ceremony. All the source files are written in lists in cmake files. [...] I love writing C because I do none of that overhead. The files to compile are whatever is on disk.

I couldn't agree more. I can't stand build tools that don't take globs! I shouldn't need to list the same thing in multiple places just to make it work. Almost all the time, the files on disk should be the only list needed.

ndiddy2• 2 years ago

The reason why people write all the source files in a list in a cmake file is that it means that when one developer adds a new file, everyone else's build system automatically regenerates the next time they try to build the project. When you use globs (which cmake does support), it means that the CMakeLists.txt file doesn't get modified when adding a new file, so the cmake generated makefiles/ninjafiles/whatever have no way of knowing that the build was modified. Instead of having the build system regenerate and then the build go through, they get a linker error and have to manually run "cmake -B build" or whatever to fix it.

humanrebar5• 2 years ago

CMake supports globs. It just has notes in the reference docs about why that can lead to slower build times or even incorrect builds (like undetected new files) in some cases.

rwbt2• 2 years ago

I'm curious how your build process works with the codegen approach. Do you have the codegen run a pass everytime you build the project? Or is it a manual process?

I've always wanted to use Lua to generate boilerplate C code (like typesafe vectors) instead of relying on macros, so might actually start thinking in this direction going forward.

turtledragonfly• 2 years ago

Not the person you asked, but this sort of thing is pretty easy with templating languages, such as Perl's Template::Toolkit[1] or Python's Jinja2[2].

The advantage of a system like that over a plain programming language (such as Lua you mentioned) is that there's less escaping and string.format(xxx) sorts of things. The output text is the primary thing and the templating language has its own special syntax to "activate" it when you need it, rather than the other way around.

That being said, Lua's square-bracket strings are pretty good for bulk text, too (:

[1] http://template-toolkit.org/about.html

[2] https://jinja.palletsprojects.com/en/3.1.x/templates/#synops...

JonChesterfield8• 2 years ago

Instead of code generation as a special case, let it be the default. That kills most of the complexity.

src/ contains lots of code in lots of languages, all describing code generators of varying complexity. src/foo.c uses 'cp' as the code generator. src/bar.c.py uses 'python'.

gen/ contains the result of the ad hoc code generators. Same tree layout as src, one to one map from those files. All of that is C. Files that get #included and don't make sense standalone I tend to suffix .data, e.g. src/table.data.lua runs to create gen/table.data.

obj/ contains all the C compiled to object code or llvm bitcode, depending on the toolchain.

I originally did that with the idea that I could distribute gen/ as the source code for people who wanted to build the project without dealing with the complexity of the build system, strongly inspired by sqlite's amalgamation. Sqlite is built from a chaotic collection of TCL and C code generators but you don't see that as a user of sqlite.c.

It turns out that debugging the stuff under gen/ when things go wrong is really easy. Valgrind / gdb show you the boring code that the generators stamped out. So in practice I keep that separation because it makes it easier to trace through the system when it behaves unexpectedly.

Lua does that really well. Good multiline string literal support. A template string that you call gsub() on a few times then dump to stdout is very quick to put together. You've got string format for more complicated things, maybe using one of the string interpolation implementations found on their wiki.

hgs34• 2 years ago

embrace code generators.

You also don't need to limit yourself to the C pre-processor. There are other dedicated pre-processing languages, like M4, and templating languages you can use.

bch• 2 years ago

Sort of happy to see m4 mentioned, but for the uninitiated: m4 is the receiver of an awful lot of hate, because things can get unwieldy quickly. Go in with your eyes open.

JonChesterfield8• 2 years ago

Definitely don't limit yourself to the C preprocessor. That way lies a tarpit. M4 took several months off me, it can definitely be used to do things but maybe shouldn't be. A really bad play was generating C++ from cmake as a compromise that delighted noone.

Python is good at generating C source. I changed to mostly using lua five years ago as python climbed the complexity curve. Sometimes the right thing is C itself, e.g. laying out data based on sizes of various C types. Currently I'm trying to use xslt to emit syntax trees that pretty print to get the generated source in what is probably a dead end.

beamsen• 2 years ago

I love writing C because I do none of that overhead. The files to compile are whatever is on disk. The tests to run are all the tests in the source, they aren't listed somewhere else as well. Any file called .lua.c is a lua program that writes the intended contents of .c to stdout. *.c.h will be compiled as C and then run to write a C header on stdout.

Do you have any sample projects that showcase both the tests and the code generation? I'd love to take a look.

JonChesterfield8• 2 years ago

The tests look much like https://github.com/JonChesterfield/EvilUnit/blob/master/evil.... That's from the self tests for the test framework. It's syntactically modelled on catch2. The name is because I built the thing out of preprocessor macros to run on freestanding c89.

The projects using code generation in that fashion are proprietary. There's a makefile at https://github.com/JonChesterfield/boring-makefile/blob/mast... set up to do the src/gen/obj codegen by default structure.

Just made the ad hoc xml codegen hackery public, some examples of tests written a couple of days ago at https://github.com/JonChesterfield/xml/blob/main/tools/intse...

thesnide• 2 years ago

I sense incoming bikeshedding in the comments.

Just have a look at how many C make replacement exists

whiterknight• 2 years ago

Start by actually writing code. Use gcc command to compile. Put the command in a shell script or make file when you start to get more than a few arguments. Done.

LabMechanic3• 2 years ago

Use MinUnit.h

https://jera.com/techinfo/jtns/jtn002

Consider using Clang-Tidy with

  `-*,cert-*`

(Which disables all default options, and checks your code according to the Secure coding standard (CERT) ruleset.)

Use Clang-Format as well. If you use Clang, consider `-Weverything -fsanitize=address,undefined` and disable options that you do not need. Consider using NMake or Make (or just write a simple script to automate building the stuff).

Here's a Google-esque style guide for C:

https://gist.github.com/davidzchen/9187878

At least, this is my approach.

LabMechanic3• 2 years ago

Here's a simple NMAKE Makefile using MSVC to compile a Win32 application on Windows 11:

  CC = cl.exe
  LD = link.exe
  CFLAGS =  /Od /Zi /FAsu /std:c17 /permissive- /W4 /WX
  LDFLAGS = /DEBUG /MACHINE:X64 /ENTRY:wWinMainCRTStartup /SUBSYSTEM:WINDOWS
  LDLIBS = user32.lib gdi32.lib
  PREFIX = ../src/

  all: app.exe

  app.exe: app.obj
  $(LD) $(LDFLAGS) /OUT:app.exe app.obj $(LDLIBS)

  app.obj: $(PREFIX)app.c
  $(CC) /c $(CFLAGS) $(PREFIX)app.c

  clean:
   rmdir /q /s build

hashtag-til• 2 years ago

Sounds like the perfect theme for a Cookiecutter template.

https://cookiecutter.readthedocs.io/en/stable/

TheCipster• 2 years ago

In recent times I prefer Xmake[0] to CMake.

[0] https://xmake.io

Alifatisk2• 2 years ago

My only wish was that C had a package manager, and maybe a dynamic analyzer to could catch bugs that a static analyzer would miss.

Also, being able to cross-compile would be cool. But I guess cosmopolitan solves this.

GuestHNUser• 2 years ago

zig cc is a top notch cross compiler that you should check out[0].

[0] https://andrewkelley.me/post/zig-cc-powerful-drop-in-replace...

Alifatisk2• 2 years ago

That’s so cool, It can compile to many different targets!

teunispeters• 2 years ago

Ah satire. ;)

Package manager: dynamic libraries! Or if you want to get really advanced, pkg-config and related. (or static libraries even. Common enough in embedded space!)

Dynamic analyzer : valgrind, gdb, Visual Studio, xCode, ...

Cross compiling : more platforms supported by C compilers than by any other build tool. Oh sure, you need to eventually watch byte sizes (as 8 bit bytes are a fairly narrow set of platforms), and know something about the platform's kernel API (if any, lots of embedded platforms are just hardware interactions!).

So I'll assume this is satire.

skydhash• 2 years ago

That makes a while since I wrote C, but I was surprised by GP's comment. I think C has the most tooling available nowadays (they may not be easy to use). And with its interoperability, can be used together with a lot of languages.

jll292• 2 years ago

Nobody is held back from adding further components to the GNU GCC or Clang/LLVM compiler suites.

Conan, gdb/DDD, Rational Purify etc. exist and can be replaced/improved by better tools.

JonChesterfield8• 2 years ago

The C++ world is keenly interested in having a package manager. I believe there are a few competing ones now.

All I've seen in practice is "vendoring", which amounts to copy the source into your tree with some degree of review or patching, and then go on as before. After being initially indignant that we didn't use libboost from the OS that approach has really grown on me.

Dependency management is a horrendous mess. Moving the logic into package managers hides that mess from the day to day development which is very nice. However, following a debugger into the binaries that came from apt install is not a great time. Patching the source to behave differently while trying to work out what is going wrong is rather harder too.

If you do the vendored thing, you also get the interesting feature where you can checkout the source tree as it was eight months ago to correspond with whatever a customer is asking about and it builds and runs, instead of telling you that the dependencies no longer exist.

I'm now heading further in that direction. All the libraries should be built from source in the same repo, but preferably by tools that are also in that repo. I'm going to end up with a C compiler checked in as well, much like the embedded toolchain people are prone to doing.

mhh__• 2 years ago

Some open source types really hate vendoring on some level (it's hard to say if it's genuinely technical or just an immune system turning on) — not everything supports it that well (e.g. python really doesn't, it's terrible), but when you have it working it's so nice for the things you mention.

We had a build fail for a few days because a git commit with a given hash didn't exist upstream. Solution? Pin to a branch of course! Vendoring as that solution takes a surprisingly deep realignment.

danjl• 2 years ago

Isn't this basically, "how to structure a large project". The bits that are C-specific are small. This could easily be changed to JavaScript, Rust, Java or any language with only small modifications.

ww520• 2 years ago

Just this week I start looking into Zig. It's a joy to use the language. The compiler and the build tool come in one executable. Most of the needs to decide on the project structure are eliminated. The project scaffold including the directory layout, build files and initial source files is generated with the init command. The build file is written in Zig itself, and have all the directory layout configured. You can modify it but the default structure is pretty sensible.

Zig really removes a lot of hurdles in the onboarding process and let you jump into building software right the way.

jll292• 2 years ago

What's proposed as the "modular" approach is close to what I use, perhaps with the following modifications:

1. instead of folders for sub-systems at the top level, put them all into src/.

2. I use the name ext/ instead of lib/ for external libraries, because in POSIX, the lib/ name indicates where the binaries of static and dynamic/shared libraries reside (not their sources).

I use a simple sh script called mkprj <project-name> to create that folder hierarchy for a new project.

o11c2• 2 years ago

Compiling with `-Werror=missing-declarations -Werror=redundant-decls`, and having a test rule that verifies that every .h file is included on exactly the first line of the corresponding .c file, is very useful at enforcing proper headers. Non-`static` declarations should be forbidden outside of headers. Violating this rule is often the only thing needed to make a project hard to understand. Easy-to-understand projects usually only have to add a few `static`s on unintentionally-exported symbols.

For libraries, it is critical that a distinction be made between "header files that will be installed" (which should use the project name as a directory prefix!) and "header files used internally". I put the latter in src/ but practice varies widely.

I argue that the flat layout is somewhat harmful (though at least using src/ beats shoving everything in ./), because even small projects eventually grow a distinction between "source files that are part of the main installed project" and "source files used solely for maintenance tooling".

Making a distinction between "code that needs to be cross-compiled" and "code that needs to be native" is useful even if you're not planning to do cross-compilation.

JonChesterfield8• 2 years ago

An alternative to the ritual include foo.h as the first line of foo.c strategy is to compile each header individually, `clang -x c -Wall foo.h -c -o /dev/null` or similar. That catches roughly the same developer intent.

Similar to the cross compiled / native distinction, it's probably a good idea to put platform specific things behind an interface up front. Link time is a good point to swap out win32 for linux or similar and implementing the second target is much easier if you drew the line up front. The platform layer might also be one worth writing a mock for as part of testing.

o11c2• 2 years ago

The problem with `-x c foo.h` is that `#pragma once` isn't legal in the top-level source file. There might be other problems too.

Using manual header guards is a bug-prone waste. Nobody has ever demonstrated me a case where `#pragma once` fails to work with compilers from the last decade or two.

IYasha• 2 years ago

build intermediate build files e.g. *.o (created by make)

In all these years I've yet to see another person (other than me) to use ramdrive for temporary files. Is everyone okay with slow compilation and SSD rape or am I missing something?

How to Structure C Projects: These Best Practices Worked for Me

Related Stories