How to add subprojects to a main project in mercurial?

Question

I'm new to mercurial and tortoise and I have some problems trying to understand how to work with sub-projects.

I have three folders called UART, SPI and ADC. These folders contain code to use the uart, spi and adc for a microcontroller family. These code is not tied to any project and on the contrary, this code is designed and developed individually to be used in any project. So, I created a repository for each one and have them under version control with hg.

But recently I decided to start a project called "Project A" which uses the ADC and the UART. I create the "Project A" folder, create a main.c file, and finally create a repository in the "Project A" folder, add the main.c file, and commit it.

My problem here is that I want to somehow "add" or "link" the UART and ADC code to my "Projet A" without copy-paste the folders manually, I mean, to handle the UART and ADC code as sub-projects independent from the "Project A" and have hg to copy the most recent version for UART and ADC to the "main" project. Then if a change is needed in UART code for example, then the change is made in the UART code, commit the change to the UART project and just "update" it to the last version whithin all projects that have UART code added or linked.

I have read:

Mercurial - Add project which is not within repository folder

Do all files have to be in the 'repository folder' when using Mercurial?

http://hginit.com/index.html

Mercurial for Beginners: The Definitive Practical Guide

And I can't find the answer to my question. I found a very neat and straight-to-the-point tutorial about subprojects but it didn't really help (http://tomtech999.wordpress.com/2011/12/17/getting-started-with-mercurial-subrepositories/ )

Could you give me a series of steps to follow or a link to some tutorial to accomplish this?

Regards!

Answer 1

Thanks for specifying what you've researched before asking; it is refreshing these days.

I think you are thinking about version controlling libraries incorrectly, see if this answer fits the model you have in your mind.

It looks to me that the libraries UART, SPI, and ADC are "libraries" in the strong sense of the word: they provide a service to a calling program like ProjectA. They could also provide these same functions to ProjectB–ProjectZ without change.

If this is so, then maintaining the libraries in a separate repository is the Right Thing To Do. If the UART changes its registers or I find a bug in the UART library, I'd want my change reflected through all users of the UART library, and the way to do that is to have a single, definitive repository for the UART library. That repository should produce a UART.a or UART.so or UART.dll as is appropriate for your system. The library will become part of ProjectA at link time. The alternative would be to have separate un-associated copies of the UART code in multiple project repositories which is an invitation to error.

I won't tell you that library generation and linking with ProjectA is nearly as easy as having all the code in one repo, but that's a limitation of make and friends across multiple directories (a deficiency that is very well known). Your separation of repositories does seem to make sense from a DVCS perspective though.

Answer 2

Like msw, I love that you explain what you've already read! I suggest reading

• Mercurial Kick Start - Subrepositories — a guide a collegue of mine wrote about subrepositories.
• Strongly cupled subrepositories — an answer I wrote where I try to explain some problems you can run into with strongly coupled sub-components. I don't know what build tools you have in your world, but if possible, you should use one to manage the dependencies between the components.
• Keeping subrepo in sync — another answer about keeping subrepos in sync on the server side.
• Mercurial wiki and hg help subrepos.