2

I currently have a project at my hand that I'll leave soon (PhD work) and should be left in an understandable form since it is likely to be taken up, though it is not known yet by whom and when.

Therefore, I'd like to leave at least some documentation how it is built. The project consists of 7 packages, each of which is an independent source code package whose compilation only depends on libraries and headers from other packages. The whole build process revolves around open source standards, i.e. each project is built by autoconf and automake, is Debian-ized and the interpackage dependencies are declared in the Debian packages and checked in configure scripts.

However, this feels like a quite specific way of specifying a quite general problem. It is likely that the next maintainer would want to build the software with a Windows GUI thingy that doesn't know anything about autoconf or Debian. I'd like to leave more rigid documentation in this case than a bunch of comments in the assorted INSTALL files and the Build-Depends/Depends declarations in the Debian files.

Is there any toolchain-agnostic established language or standard to document packaging and build order? Bonus points if the actual build system specifications (like Debian Build-Depends) could be generated from that.

Improve this question
3
  • 1
    "The project consists of 7 packages, each of which is self-contained, but possibly relies on others to build." Which is it? Either each package is self-contained and has no reliance on any other package, or some packages have dependencies on at least one other package.
    – Thomas Owens ♦
    Commented Oct 4, 2011 at 11:51
  • You will have to decide if you want to document your current process or make it os independent. Once you make that decision document the entire process from start to finish. You cannot assume anyone that comes in will have the same knowlege as you.
    – Ramhound
    Commented Oct 4, 2011 at 12:38
  • There is no toolchain-agnostic standard for this. Rather, there are dozens of standards, each supported by their own toolchain.
    – Alan Shutko
    Commented Sep 2, 2015 at 3:39

1 Answer 1

Reset to default
1

Graphviz is highly readable and editable in addition to the purpose of generating graphical output for documentation. In a couple different projects over many years, I wrote some simple tools which generated graphviz output, or simply typed up the dep's manually. The result is that the project managers and bosses all printed out copies and taped them to their whiteboards because they found the diagrams so useful.

One of these was for the entire dependency chain for a large gnu/linux embedded systems project, and there were dozens of dependencies between toolchain, binutils, gpl packages, etc, etc, etc. The diagram became too large to fit on legal sized paper.

(Tangentially: this is the huge hidden cost of choosing gnu/linux: dozens of independent packages from authors who don't integrate their packages with each other. If it were netbsd, the "system" would be just one product from one vendor: the netbsd release.)

Improve this answer

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.