As I have been working in PROS I have been slightly confused on how the Hot/Cold linking works. With the new PROS kernel, it stated that libraries could be excluded from cold download this makes things a little more confusing. When I have a multi-file program that has .h declarations and .cpp definitions. If the header file is updated, ex: added a variable or changed function prototypes does the entire project need to be rebuilt or does the hot download include the new header file and declarations. Thank for any help in advance!
1069B - Argonauts
As of the 3.2.0 release, you won’t need to rebuild a whole project anymore when making header file-only changes (this PR). This doesn’t mean that you don’t need to build the project, it just means you won’t need to clean before you build- the default rule will perform an incremental build incorporating only the things you’ve changed.
As such, if you have a library embedded in your project, and you change a header file related to that library, the dependency tracking should be able to figure out that it needs to rebuild the archive.
Let’s walk through an example of what this looks like. I made a new PROS project, that I’ll call test-project. Within that, I’ve added a folder to both src and include named libtest.
Here’s include/lib.hpp:
#pragma once
void hello_world();
And here’s src/lib.cpp:
#include "libtest/lib.hpp"
#include <iostream>
void hello_world() {
std::cout << "hello world! -from libtest" << std::endl;
}
When we build, we can see that src/libtest.cpp is compiled and bin/libtest.a is created (src/main.cpp was already compiled when after I made the project):
X:\code\test-project>prosv5 make
Compiled src/libtest/lib.cpp [OK]
Creating bin/libtest.a [DONE]
Creating cold package with okapilib,libm,libc,libpros,libtest [OK]
Stripping cold package [DONE]
Section sizes:
text data bss total hex filename
1.31MB 3.67KB 47.62MB 48.93MB 30ec39f bin/cold.package.elf
Adding timestamp [OK]
Linking hot project with ./bin/cold.package.elf and okapilib,libm,libc,libpros,libtest [OK]
Section sizes:
text data bss total hex filename
1.17KB 4.00B 2.00B 1.17KB 4ae bin/hot.package.elf
Creating cold package binary for VEX EDR V5 [DONE]
Creating bin/hot.package.bin for VEX EDR V5 [DONE]
Now let’s say I want to change the signature of hello_world, maybe to something like this:
#pragma once
#include <string>
// TODO: use this in the source file
void hello_world(std::string name = "");
Building the project again shows that we compile src/libtest.cpp even though we only changed the header file! Make even knew to rebuild bin/libtest.a.
X:\code\test-project>prosv5 make
Compiled src/libtest/lib.cpp [OK]
Creating bin/libtest.a [DONE]
Creating cold package with okapilib,libm,libc,libpros,libtest [OK]
Stripping cold package [DONE]
Section sizes:
text data bss total hex filename
1.31MB 3.67KB 47.62MB 48.93MB 30ec39f bin/cold.package.elf
Adding timestamp [OK]
Linking hot project with ./bin/cold.package.elf and okapilib,libm,libc,libpros,libtest [OK]
Section sizes:
text data bss total hex filename
1.17KB 4.00B 2.00B 1.17KB 4ae bin/hot.package.elf
Creating cold package binary for VEX EDR V5 [DONE]
Creating bin/hot.package.bin for VEX EDR V5 [DONE]
Like I mentioned before, this is not only the case when you have a library. The same will be true of the rest of the project as well.
As far as the EXCLUDE_COLD_LIBRARIES Makefile variable goes, you can take a look at the motivation behind adding it here.
I hope this was able to clear up some of your questions.
3 Likes
Thank you very much that does clear a lot of the confusion but I have one question. When I tried to copy what you did the message I got in the terminal this:
prosv5 build all
Cleaning project
Creating cold package with libc,libm,libpros,okapilib [OK]
Stripping cold package [DONE]
Section sizes:
text data bss total hex filename
1124106 3751 49929240 51057097 30b11c9 bin/cold.package.elf
Compiled src/lib.cpp [OK]
Compiled src/main.cpp [OK]
Adding timestamp [OK]
Linking hot project with ./bin/cold.package.elf and libc,libm,libpros,okapilib [OK]
Section sizes:
text data bss total hex filename
1248 8 3 1259 4eb bin/hot.package.elf
Creating cold package binary for VEX EDR V5 [DONE]
Creating bin/hot.package.bin for VEX EDR V5 [DONE]
Capturing metadata for PROS Editor…
Note the difference in that it doesn’t state that it creates the bin/libtest.a and that libtest doesn’t show up in the cold packages. I tested the functionality and it seems to be doing what you said(Recompiling all the files that use the header file). I don’t think that it is any major concern but I am curious about the difference.
1 Like
Guess I forgot to mention that I enabled building libtest as a separate library by changing the relevant lines in the Makefile:
# Set this to 1 to add additional rules to compile your project as a PROS library template
IS_LIBRARY:=1
# TODO: CHANGE THIS!
LIBNAME:=libtest
1 Like
Is this something you recommend doing or is it a unnecessary?
I did it as part of the example to show that changing a library’s header files would indeed rebuild the library.
In your original question you had asked about the EXCLUDE_COLD_LIBRARIES variable, which is why I brought up libraries at all. If you want to learn more about why you’d enable a library in your project, check out this tutorial about hot/cold linking for large projects.
3 Likes