11

I want to incorporate some open source libraries into my C project. This is the first time I do that, so I don't know what is the right or most common way of doing it.

I see two possible paths I can take:

  1. Download the code of each library I'll use, add them to my project folder and modify them as I need.
  2. Just list each library as a dependency. So the user would download them to its machine and include them to the project with (maybe) some makefile configuration.

I think option #1 is better for two reasons:

  1. I release the user from the task of downloading and configuring the dependency.
  2. In my project two libraries have overlapping code. Part of one library is a subset of the other. They have the same functionalities and the same identifiers names (variables, functions, #defines). So I would have some conflicts that I don't know how to fix.

But I just think option #1 is better. I really don't know what's the best. Maybe someone knows how to fix the conflicts between the libraries and then my opinion may change. I'm asking this question because I don't know what is the path programmers usually take. I also don't know what are the pros and cons of each alternative. And I also don't know if there are other alternatives.

Update: The expected users are programmers.

  • 2
    Who are your expected users? Do you expect your project to be used by fellow programmers, or do you want it to be used by your next-door neighbor who doesn't really know the difference between Firefox and MS-Word? How likely is it that your users already have the right versions of those dependencies installed? – Bart van Ingen Schenau Mar 23 '18 at 11:46
  • My project is an embedded Operating System. It will run on microcontrollers. The expected users are programmers. One of the dependencies is certainly already installed on the user's machine. I'm talking about the libraries that comes with the C compiler for each microcontroller. The problem is that compilers for microcontrollers usually have a minimal version of the C Standard Library. So I'll need to add a more complete implementation in my project. But then I'll have conflicts between the two implementations. And that's why I think option #1 is better. –  Mar 23 '18 at 12:00
  • I didn't include all of this info in the question to avoid turning it into an off-topic question. –  Mar 23 '18 at 12:03
  • Regardless of how you distribute them, how do you propose to link two libraries with overlapping symbols into the same binary? – Blrfl Mar 23 '18 at 12:17
  • Do you need to include source or can you include a .lib for linking? – NetJohn Mar 23 '18 at 14:09
  • Who are "users"? Do you mean other developers using your code? – gnasher729 Apr 10 '18 at 06:58

4 Answers4

10

@17of26 gave a lot of good reasons why #2 is dangerous, and why #1 makes more sense. But I think there is one thing missing, for which I recommend the following:

  • download the code of the library you will use,
  • add it to the project folder,
  • but don't modify it arbitrarily!!

Avoid modifications if possible. If that is not possible, try to keep the direct modifications down to a minimum and keep everything else in separate files. If necessary, use script files or patch files. So make sure all changes to the libs or to the makefile configuration are documented and can be reproduced.

This gives you a way better chance to update to newer versions of those libs at a later point in time, if needed.

Of course, there will be no guarantee the patches or configuration changes applied to version 1.0 of a lib can be directly applied to version 2.0 of that lib, too. But the chances are the much higher when there are only a few number of patches/changes, and the effort to apply them will be likely smaller.

Doc Brown
  • 199,015
  • 33
  • 367
  • 565
  • Very useful answer. I appreciate it. When you say I can modify the libraries with script or patch files you mean I can have an unchanged directory with the original library code and the modifications somewhere else? Could you indicate some material where I can learn how to do that? I'm googling about it but didn't find anything yet. –  Mar 23 '18 at 14:12
  • 3
    @rrd: google for "diff patch", these are standard Unix/Linux tools for this, or inform yourself about the possibilities to create patches with SVN or Git. But the very least thing you can do is to write a simple, but detailed "readme" so you know can reproduce the changes you did last year to the lib's codebase. – Doc Brown Mar 23 '18 at 15:10
6

You always want to package any dependencies with your project.

Your software is going to be built and tested with a particular version of a specific library. It's not guaranteed to work with any other version.

You need to ship your code with that exact version of the library. If you don't, your are opening the door to a support nightmare.

For example, let's say you build and test your code with library Foo v1.0. You don't ship Foo v1.0 with your product and instead say "Hey users, go get this library Foo v1.0".

Now imagine:

  • Foo disappears from the internet. Maybe it's hosted by a company that goes out of business. Or maybe the developer of Foo v1.0 gets sick of emails from angry users and removes public access to the library.
  • Foo is very actively developed. Foo is now on v8.0. Foo developer decides to stop supporting anything older than v7.0 and removes access to earlier versions.
  • Foo developer makes a breaking change to v1.0 but doesn't actually increment the version. Now when users download v1.0, they are getting a different library than what you used and it just doesn't work.

You avoid all of these potential headaches by shipping the exact binaries that software needs to work.

17 of 26
  • 4,818
  • 1
  • 21
  • 25
  • "always" is a pretty strong position. – whatsisname Mar 24 '18 at 00:13
  • 2
    Generally people greatly exagerate the need for one particular version to ensure stability. Keeping a copy around is one thing -- packageing it with your software an entirely different thing. – Clearer Apr 10 '18 at 13:08
1

A common way of managing 3rd party code is via "vendor branches" (I assume that you are using some sort of version control system such as git, svn etc).

Vendor branches allow you to keep track of changes to the 3rd party code and easily incorporate those changes into your code along with any changes you need to make to your code to work with those changes.

The subject of vendor branches is too complicated to go into here (and the details would depend on what vcs you are using) but there are many useful guides on the web.

Dipstick
  • 161
  • 1
-1

1 is the way to go.

You can add the original source code to your project and the changes you made in a diff patch file.

Then it is easy possible to see the changes you have made and the user will have no problems if the library dissapears from the internet.

Community
  • 1
Nils
  • 99
  • 4