Project

General

Profile

Task #735

conversion of manual build system to CMake

Added by Mark Abraham over 8 years ago. Updated about 5 years ago.

Status:
Closed
Priority:
Normal
Assignee:
Category:
documentation
Target version:
-
Difficulty:
uncategorized
Close

Description

There's a useful CMake LaTeX build system, which I've now made the manual build system use. We still build all the special files using the shell scripts, but I've updated most of them to use bash, because C shells are evil.

Building is easier than before. Instead of copying sundry files by hand, and keeping different versions of some files in some repos and not others, cmake lets you specify a directory with the binaries you want to use to generate the LaTeX man files, and another with a source tree that can find programs.txt and mdp_opt.html. Then "make pdf". An "out of source" build is required, and it seems that this works best if the foregoing directories are specified with absolute references, not relative ones.

The README file is updated accordingly.

The new system works for me on two different platforms, so I think it's probably robust enough for common use.

Oops I forgot to tag the commit with an IssueID. It's 550de88

Associated revisions

Revision 7d421085 (diff)
Added by Mark Abraham over 8 years ago

Fixed CMake manual build dependency problem

CMake now issues a fatal error if it finds files that will break its
dependency generation. Documentation is updated accordingly. Absolute
paths to binary and source directories are no longer required. There's
a Makefile that prompts someone attempting an old-style build of the
manual to read the README to do a CMake-style build. That Makefile
will also do "make clean" to get rid of all the files that might
break CMake dependencies.

IssueID #735

Revision 26bd5f7a (diff)
Added by Roland Schulz about 7 years ago

Build man-pages instead of distributing them in the source

One less thing to do manual for releasing the code. And thus
avoiding to accidental releasing which old version of man-pages.

Writing copyright notice to stderr for all programs (was inconsistent)
and caused copyright notice to be displayed during build.

The CPack source package continues to contain the man pages pre-build.
CPack verifies that they are genenerated before building the source
package.

Added .isreposource to distinquish code obtained from git from code
downloaded as CPack source package.

Related to #645, #854, #735
Fixes #878

Change-Id: I7d7145fb99d3f1991d0f3992ca4f3ea20668dd9a

History

#1 Updated by Mark Abraham over 8 years ago

Commit hash is 550de88

#2 Updated by Rossen Apostolov over 8 years ago

what happens if the directory with binaries contains other previously installed ones e.g. mdrun_d , mdrun_mpi_d, mdrun-4.0.7_d? Will all those enter as man pages too?

#3 Updated by Justin Lemkul over 8 years ago

I'm having problems getting this to work. I did the following:

mkdir build_manual
cd build_manual
cmake ../manual -DGMXSRC=/Users/justin/Downloads/GROMACS/git/release-4-5-patches -DGMXBIN=/Users/justin/Downloads/gmx-git/bin
make pdf

The output shows no sign of trying to write mdp_opt.tex:

[  0%] Generating unpubl.bib
[  0%] Generating g_options.tex
[  0%] Generating proglist.tex
generating latex page proglist.tex from /Users/justin/Downloads/GROMACS/git/release-4-5-patches/admin/programs.txt

[  0%] Generating plots/fp-highres.pdf
[  0%] Generating plots/angle.pdf
[  0%] Generating plots/bstretch.pdf
[  0%] Generating plots/chain.pdf
[  0%] Generating plots/dd-cells.pdf
[  0%] Generating plots/dd-tric.pdf
[  0%] Generating plots/decomp.pdf
[  0%] Generating plots/dih-def.pdf
[  0%] Generating plots/dih.pdf
[  0%] Generating plots/distm.pdf
[  0%] Generating plots/drift-all.pdf
[  0%] Generating plots/dssp.pdf
[  0%] Generating plots/dumaro.pdf
[  0%] Generating plots/dummies.pdf
[  0%] Generating plots/dumtypes.pdf
[  0%] Generating plots/f-angle.pdf
[  0%] Generating plots/f-bham.pdf
[  0%] Generating plots/f-bond.pdf
[  0%] Generating plots/f-dih.pdf
[  0%] Generating plots/f-dr.pdf
[  0%] Generating plots/f-imps.pdf
[  0%] Generating plots/f-lj.pdf
[  0%] Generating plots/f-morse.pdf
[  0%] Generating plots/f-pr.pdf
[  0%] Generating plots/f-rbs.pdf
[  0%] Generating plots/flowchart.pdf
[  0%] Generating plots/free1.pdf
[  0%] Generating plots/free2.pdf
[  0%] Generating plots/hbond-insert.pdf
[  0%] Generating plots/hbond.pdf
[  0%] Generating plots/hpr-wheel.pdf
[  0%] Generating plots/int-mat.pdf
[  0%] Generating plots/leapfrog.pdf
[  0%] Generating plots/lincs.pdf
[  0%] Generating plots/maxwell.pdf
[  0%] Generating plots/mdpar.pdf
[  0%] Generating plots/mpmd-pme.pdf
[  0%] Generating plots/msdwater.pdf
[  0%] Generating plots/ngmxdump.pdf
[  0%] Generating plots/nstric.pdf
[  0%] Generating plots/par-lincs2.pdf
[  0%] Generating plots/parsort.pdf
[  0%] Generating plots/pbctric.pdf
[  0%] Generating plots/phipsi.pdf
[  0%] Generating plots/pull.pdf
[  0%] Generating plots/pullref.pdf
[  0%] Generating plots/rama.pdf
[  0%] Generating plots/rdf.pdf
[  0%] Generating plots/rdfO-O.pdf
[  0%] Generating plots/rhododec.pdf
[  0%] Generating plots/ring-imp.pdf
[  0%] Generating plots/ring.pdf
[  0%] Generating plots/sgangle.pdf
[  0%] Generating plots/shiftf.pdf
[  0%] Generating plots/softcore.pdf
[  0%] Generating plots/subst-im.pdf
[  0%] Generating plots/tetra-im.pdf
[  0%] Generating plots/truncoct.pdf
[  0%] Generating plots/vcrf.pdf
[  0%] Generating plots/vsite-4fdn.pdf
[  0%] Generating plots/fp-highres.jpg
[  0%] Generating plots/peregrine.jpg
[  0%] Generating gromacs.tex
[  0%] Generating algorithms.tex
[  0%] Generating defunits.tex
[  0%] Generating implement.tex
[  0%] Generating macros.tex
-- Configuring done
-- Generating done
-- Build files have been written to: /Users/justin/Downloads/GROMACS/git/build_manual
[  0%] Generating special.tex
[  0%] Generating analyse.tex
[  0%] Generating files.tex
[  0%] Generating gmxpar.tex
[  0%] Generating install.tex
[  0%] Generating topology.tex
[  0%] Generating averages.tex
[  0%] Generating forcefield.tex
[  0%] Generating intro.tex
[  0%] Generating programs.tex
[  0%] Generating gromacs.pdf

...

! LaTeX Error: File `mdp_opt.tex' not found.

Type X to quit or <RETURN> to proceed,
or enter new name. (Default extension: tex)

Enter file name: 
! Emergency stop.
<read *> 

l.66 \input{mdp_opt}
                    ^^M
!  ==> Fatal error occurred, no output PDF file produced!

Any ideas? I can provide whatever cache files, etc you'd like to see. I'm still pretty new to cmake, so I can't interpret a whole lot of it, though from what I've found it seems like it should have worked.

#4 Updated by Mark Abraham over 8 years ago

Rossen Apostolov wrote:

what happens if the directory with binaries contains other previously installed ones e.g. mdrun_d , mdrun_mpi_d, mdrun-4.0.7_d? Will all those enter as man pages too?

Yes, they do. The mkmdp script is still being used, and it is a bit hamstrung in this area. All it does is glob the files, and has a list of filenames (e.g. GMXRC) from which it should not attempt to make man pages.

Not having an easy way to know what prefix and suffix combination to use is a problem here. This would be fixed by rolling all the binaries into one :-)

An alternative would be to build the man pages from the executables in a build tree. They don't have prefixes and suffixes there. The CMakeLists.txt files have the executables listed one way or another, so it would not be too hard to communicate that to the manual build system.

Keeping programs.txt in sync is a big pain, however

#5 Updated by Mark Abraham over 8 years ago

Justin Lemkul wrote:

I'm having problems getting this to work. I did the following:

[...]

The output shows no sign of trying to write mdp_opt.tex:

[...]

Any ideas? I can provide whatever cache files, etc you'd like to see. I'm still pretty new to cmake, so I can't interpret a whole lot of it, though from what I've found it seems like it should have worked.

Your symptoms are the same as the problem I thought I had fixed by switching GMXBIN and GMXSRC to absolute filenames. The g_options and proglist.tex dependencies get built before gromacs.pdf. In my case, mdp_opt.tex and progman.tex would build after gromacs.pdf - which makes no sense.

Aha! Now I remember! I bet that you still have progman.tex and mdp_opt.tex files in your manual directory. If I touch those in my manual directory, I get your symptoms. CMakeFiles/pdf.dir/build.cmake will now have spurious make rules for these dependencies. This must have been the real reason for the problem, not absolute/relative paths.

Now I just have to figure out how to flag this as a problem.

#6 Updated by Justin Lemkul over 8 years ago

Mark Abraham wrote:

Justin Lemkul wrote:

I'm having problems getting this to work. I did the following:

[...]

The output shows no sign of trying to write mdp_opt.tex:

[...]

Any ideas? I can provide whatever cache files, etc you'd like to see. I'm still pretty new to cmake, so I can't interpret a whole lot of it, though from what I've found it seems like it should have worked.

Your symptoms are the same as the problem I thought I had fixed by switching GMXBIN and GMXSRC to absolute filenames. The g_options and proglist.tex dependencies get built before gromacs.pdf. In my case, mdp_opt.tex and progman.tex would build after gromacs.pdf - which makes no sense.

Aha! Now I remember! I bet that you still have progman.tex and mdp_opt.tex files in your manual directory. If I touch those in my manual directory, I get your symptoms. CMakeFiles/pdf.dir/build.cmake will now have spurious make rules for these dependencies. This must have been the real reason for the problem, not absolute/relative paths.

Yep, that looks like it. From build.cmake:

gromacs.pdf: g_options.tex
gromacs.pdf: proglist.tex
gromacs.pdf: /Users/justin/Downloads/GROMACS/git/manual/mdp_opt.tex
gromacs.pdf: /Users/justin/Downloads/GROMACS/git/manual/progman.tex
gromacs.pdf: plots/fp-highres.pdf
gromacs.pdf: plots/angle.pdf

#7 Updated by Mark Abraham over 8 years ago

Great. So there's some CMake mechanism being used wrongly (or is broken!). I'll look at it.

#8 Updated by Mark Abraham almost 8 years ago

  • Status changed from In Progress to Closed

#9 Updated by Rossen Apostolov about 5 years ago

  • Project changed from Documentation to GROMACS
  • Category changed from manual to documentation

the issue was moved to project "Gromacs", category "documentation", and the original sub-project "Documentation" was removed.

Also available in: Atom PDF