In a large project that has files structured in a directory tree structure, is it better to include relative path in source file, or just include header file and instruct compiler via Makefile where to find it?
Is there a preferred way?
Example:
#include "../path/to/file.h"
vs.
#include "file.h"
gcc -I../path/to
I believe that first case may be more readable while second approach would give ability to seamlessly move files...
It depends. For include files inside your project, giving the relative path can be useful, as the sub-directory is another structure-element and you do not have to care about equal file-names (mostly for C++, as C does not support custom-namespaces).
For external paths (e.g. other projects), you should definitively use the second method. Possibly just to the root of that structure. Similar to asm/byteorder.h.
In any way, if using explicit paths (in the source files), you should make sure they are well-documented and any change is tracked to the source files. (There are often common sub-directories, like config, etc. which will not change).
One strong recommendation: always use the project root as working directory. All explicit relative paths are from this root. That way you can avoid the problemativ parent (..) path.
Ultimative rule is not to use explicit paths which cross the project-root.
However, there is no other general rule. The actual layout is often subject to personal preferences. If the directory structure is well-thought, I'd prefer explicit paths.
The second method is more efficient since you don't have to rewrite the path every single time you want to use this file.
Let's take an example.
You want to build a library containing some useful functions.
Then you work on a project on which you need some of the library's functions, not all of them.
So you choose to mv some on those files into your project folder.
This way, the path might not be the same, and you won't have to rewrite everything if you choose to include the path in the Makefile.
Coding your Makefile properly, let you have several $(PATH), which is very useful when working on big projects requiring multiple binaries for example.
I'm trying to be as clear as possible, but I really think, in my opinion, that the Makefile is a very powerful tool which can be used to his best to make the project development easier.
Related
I am fairly unused to compilation and building projects so pardon me if my approach to compilation and build seems a bit odd. Any tip is welcome.
I am currently working on a 3D geometry C++ project (Which is a dll). This project uses external dll's such as BOOST. So when building the project I have to define the directories in which the .dll, .lib and .h/.hpp files are.
Currently I am using scons to build the project and define those paths straight in the SConstruct file.
However those paths are later reused for other build operations. (In the present case compiling the C++ code in MEX for matlab but that's not really the point here).
Thus I currently have to define the same path in different places which is inefficient. In addition the project has to be easy to set up for another user. So having to change and update path in many different files is something I would like to avoid.
From where I stand I see two alternatives:
First I could ask the user to define environment variables and read them from inside my various build scripts. However I am not really satisfied with this solution for it asks the user for additional manipulation and, as far as I've understand, I lose the cross-platform portability that scons offers. (I know it might still possible but requires some extra steps and I'd like to keep things as simlpe as possible)
Second I could define all my path in a single .txt (or something similar) file at the root of my project and read it from my various build scripts. However this makes the process sensitive to typos and parsing errors which is not really to my taste.
So my question is the following:
Is there a better way or good practice to have the user input the paths necessary for compilation that satisfies the following:
Has the user only input once every path
Is done within the project folder through a file or something else
Is as foolproof as possible
Does not require too much additional download/installing (I don't really want to have the user install a brand new software for this. However I'm fine with something like a simple light .exe that I can add in my project files)
SCons's Variables are likely your best choice here.
See: https://scons.org/doc/production/HTML/scons-user.html#sect-command-line-variables
It allows reading defaults from a file:
vars = Variables('custom.py')
You'd have to craft some logic to save any variables specified on the command line.
I am trying to use gnuplot++, but this is really a more general question about downloaded source code. I have downloaded the gnuplot++ source code and it consists of multiple .h and .cc files. I would like to use it in othercopy projects in the future so I am reluctant to add all the files into my project directory.
From what I understand gcc will look in /usr/local/include for header files, so I have put the code there for now. But what is the best way to compile and link the code?
Should I use the makefile to include the directory of the source code?
Should I keep it somewhere easy to find like /usr/local/include?
How do I know the best way to compile the code in gnuplot++?
Typically, if the project itself doesn't come with install instructions, I usually add it somewhere "public", e.g. /usr/local/project/{lib,include,src,...} where "project" in this case would be gnuplot++.
In this case, there doesn't appear to be any support for building this into a library, which makes it a little more awkward, as you need the sources included in your project itself. I'd still keep those sources separate, but you may prefer to just put them into a separate directory within the project [or spend an hour or three making a library of it].
For general practice, yes, keep the source for gnuplot++ (or any other similar 3rd-party project) separate from your own application source code. This makes it much easier to manage updates to the 3rd party projects, etc.
Yes, I would use the makefile for your application to also include the path to the headers for gnuplot++ and I would not copy those files directly into /usr/local/include. Instead, I would consider a couple options: do nothing and point your include path in your makefile to the gnuplot++ directory, or put symbolic links in /usr/local/include to point to the gnuplot++ files.
As for the best way to compile gnuplot++, I would have to look at gnuplot++ myself and see what it has to say, perhaps in a README file or similar.
In general, when using third-party libraries, you build and install those libraries according to the installation description that comes with the downloaded source.
If there is no installation guideline, it is typically a set of steps like
./configure
make
make install
Then it is the responsibility of the library to ensure the relevant headers and library files are easily locatable for use in your project.
gnuplot++ is an exception here, because it does not seem to come with its own build structure.
The best advice in cases such as this is to put the source from gnuplot++ in a directory within your project (possibly parallel to your own sources) and include the files in your own build setup.
This link mentions wildcards as a way to automatically list the SOURCES and HEADERS in the Makefile.am file. It also mentions that some people write external scripts to generate those files.
Do you know of the standard way of automatically including all the *.h *.cpp here, or should I just write my own Perl script to generate them. Do you have such a script already that you use?
PS: I organize the source files in my project according to the following purely-logical separation of directories:
src/dog/woof.h
src/dog/woof.cpp
src/cow/moo.h
src/cow/moo.cpp
Automake won't add this feature. It makes assumptions that a particular .h or .cpp file is associated with a particular project. That assumption holds for a number of common project layouts and fails for any layout that differs.
For example, I've had projects that were laid out as
src/module/code
src/app/code
src/library/code
include/headers
built from one central makefile in the root. Other times, I've had the same layout built from four makefiles in the appropriate local directories.
There's a lot of variability in projects. Some keep public header files mixed with private headers files in the code directories, some keep them separate. Some build shared object libraries, some don't. Some ship code that's not SUPPOSED to compile on incompatible platforms.
To put in a wild card inclusion would actually pose a great risk of limiting the functionality, and for those odd people who do things like 'file.template.c' and such it would be fatal.
If you consider it a flaw of automake, that's fine; however, it's one of those flaws that automake embraces as it's preserved in the effort to make things more flexible. Automake doesn't impose the "how" you do things, it provides a lot of enabling tools, but it goes out of it's way to ensure that you aren't forced into one "method" of laying out or building your code.
Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 3 years ago.
Improve this question
This questions concerns mostly Unix/Linux style C++ development. I see that many C++ libraries store their header files in a "include" folder and source files in an "src" folder. For the sake of conformance I adopted this in my own code. But it is not clear to me whether this should be done for application code as well. I've seen a few cases where a flat directory structure is used for that. What would be the recommended approach?
I also separate them, but not strictly on the extension, but on the access of the file.
Suppose you have a module that manages customer information and uses 2 classes to do this: Customer, CustomerValidityChecker.
Also suppose that other parts in your application only need to know about the Customer class, and that the CustomerValidityChecker is only used by the Customer class to perform some checking.
Based on these assumptions I store the files like this:
Public folder (or include folder):
customer.h
Private folder (or source folder):
customer.cpp
customervaliditychecker.h
customervaliditychecker.cpp
That way, it becomes immediately clear for callers of your module which parts are accessible (public) and which parts aren't.
We have a build system that auto-generates our makefiles. One thing it does is recursively descend any subdirectories and build them as libraries, linking them together with the main directory's objects to make the application. (In practice, these "subdirectories" are usually symbolic links.) Libraries are static unless the directory name ends in ".so". One thing that's nice about this is that a full build of our system, which has many executables, doesn't have to repeatedly compile the common libraries.
However, as a result of this, there's no separation of headers and sources. And it has never been a problem. Honestly, I think it's better this way because headers and source files have commonality of location, and you can grab a directory and know you got everything you need to use it. It also works great with Subversion's "externals" feature, and similar features in other VCSs.
One last place where an include/src separation fails is if you use any code generators, such as flex, bison, or gengetopts. Figuring out where these tools should put their outputs so they get built is tricky if you've spread things out.
It makes sense to separate them for shared libraries because they may be distributed in a compiled form without the source. I've seen projects that separate out "public" headers (headers that may be accessed from code outside your project or library) while leaving "private" headers and source files in the same directory. I think it's good to use a consistent approach whether you're writing shared library or application level code because you never know when you may want to turn something that you've written at the application level into a lower level library that is shared by multiple projects.
A lot depends on the size of project involved. Up to a few dozen files or so, keeping them in one directory tends to be more convenient. For a bigger application that includes hundreds or thousands of files, you start to look for ways to separate them (though in the projects I've worked on, it was done more on functional lines than src/include). In between those, it's probably open to question.
I don't do this; there seems little advantage in it. Since headers tend to have a different extension from source files, you can have your editor show them separately if you really feel the need -- Visual Studio does this by default, but I disable it since I prefer seeing them together
Bottom Line: sources and headers that are still changing go in /src. Code that has crystallised should go in /lib & /include (actually you could keep all .libs and their .hs in /lib).
Keep own sources and headers together, provided they are (a) specific to this project or (b) have not yet been factored out as a shared library.
Once certain sources in the main project have been factored out as a (relatively stable) library, place the .a or .lib into /lib, and its public interface header into /include.
All third party libraries and their public interface headers also go into /lib & /include.
As others note, it is often more compatible for tools / IDEs to access .h/.c from one folder. But from an organisational view it can be useful to separate changing local code from stable lib code.
There is no clear advantage to either in my view. I finally decided to keep program and header files together because my editor (Visual SlickEdit) happens to provide additional referential features when they are not separated.
I almost always create include and src folders to split up my source code. I think it makes the folder less cluttered and files are easier to find in my IDE. But I think this is just a matter of taste.
Either method is valid. It depends on the coding style you want to follow how you do this.
I place include (header) and source files in the same directory (folder). I create different folders for different themes. I get frustrated when trying to find header files (while debugging and also for researching). In some shops, there are only two folders: source and includes. These directories tend to grow exponentially. Reusing code becomes a nightmare at best.
IMHO, I believe organizing by theme is better. Each theme folder should build into at least one library. Different projects can easily include the themes by searching or including the folders. The projects only need to include the libraries. Smart build engines can list the theme folders as dependencies. This speeds up the build process.
The theme organization also adds a bit of safety to the project. Accidental damage to files (such as removing the wrong ones or replacing with different versions) is reduced since files are located in different directories. Deletion of files in the "Person" folder will not affect files in the "Shape" folder.
This is just my opinion, Your Mileage May Vary.
We have a build system which use this rule. This build system is sconspiracy a set of scripts to configure SCons and dedicated to the C++ world. You can see an example which use this tools : fw4spl
I am having a bit of trouble organising my source files.
I have my own small, but growing collection of code that I would like to use in various projects. The file and folder layout is something like this:
library\sub1\source.h
library\sub1\source.cpp
library\sub2\source.h
library\sub2\source.cpp
One of my problems is that I want to include this code, as needed, in my other projects. To date I have used absolute paths to point to the libary code, but there must be a better way.
Futhermore, I need to add every library file I use to a project's files Visual Studio in order for it to compile correctly.
So my question in short is how do I fix this? What is the proper/best way to handle the above situation.
You shouldn't, in general, add source files from libraries directly to other projects. Compile them separatly as a library and use those.
For organising the library's directory structure itself, right now I settled on something like the following structure
library1/widget.h
library1/private/onlyinlib.h
library1/private/widget.cpp
(and if applicable)
library1/private/resources/widget.jpg
library1/private/project/widget.xcode
I put all headers directly in the library path, and have a subfolder private which will contain everything that's only used by the library, but should never be shared / exposed.
The greatest advantage is that every project I start only needs a include path pointing at the directory containing my libraries, then every (public) include is done like
#include "library1/widget.h"
private includes are simply
#include "onlyinlib.h"
This has a number of advantages:
If new libraries are introduced, there's no messing with project /compiler settings to get the headers 'visible'.
Moving to other compilers / platforms is also very little hassle.
The headers are automatically 'namespaced', i.e. by including part of the path too, it's next to impossible to get a nameclash with the includes
It's immediatly obvious where a header comes from, and if a header is part of the public interface or not
I don't think that there's a proper way to do this - it's going to depend on exactly what you are trying to achieve.
Here's some things you might not be aware of:
You can use relative paths in your projects.
You can use environment variables in paths.
You can add directories to Visual Studio's search rules.
This gives you a little more control over where you put the include files and if you add your folders to Visual Studio's search rules you don't have to include any paths at all.
If you must include third-party code instead of just linking with a pre-compiled version (e.g., perhaps you need to make modifications or tweaks to it), consider branching it in whatever you use for source-control:
/trunk/... --- your code goes here
/thirdparty --- pristine copies of third-party libraries go here
/thirdparty/lib1
/thirdparty/lib2
etc.
/trunk/lib1 --- branched from: /thirdparty/lib1, perhaps with local changes
this is the version that you build/link with.
Assuming you use a decent source-control system, this scheme will allow you to easily upgrade to newer versions of third-party libraries and then merge those changes with the changes you've made locally.
For example, suppose "lib1" releases a new version:
Commit the change to /thirdparty/lib1.
Merge from /thirdparty/lib1 to /trunk/lib1
Fix any merge conflicts.
This is, IMO, the only sane way to handle upgrading third-party libraries to which you've made local modifications.
First: Add all used directorys to your project include paths. Add them as relative paths if possible.
Second: You must add all used librarys/source files to your project. This can be either done in the project explorer, or in the Project->Linker tab. In the latter case, you'll have to add the used directories to the projects library paths as well.
Usually its not a good idea to use paths in #include directives.