[Cmake] Re: ADD_CUSTOM_COMMAND etc

[Nils H. Busch]

Hi,

I must say, that I did not understand the necessity of having to use ADD_CUSTOM_COMMAND in
conjunction with ADD_CUSTOM_TARGET either.
For my use of creating docs with doxygen, it was sufficient to place

IF (BUILD_DOCUMENTATION)


  CONFIGURE_FILE(
    ${FOO_SOURCE_DIR}/utilities/Doxygen/doxygen.config.in
    ${FOO_BINARY_DIR}/utilities/Doxygen/doxygen.config.)

  ADD_CUSTOM_TARGET(doc
   ALL
   ${DOXYGEN}
   ${FOO_BINARY_DIR}/utilities/Doxygen/doxygen.config)

ENDIF (BUILD_DOCUMENTATION)

in a CMakeLists.txt file.

When specifying ALL, the target is automatically added to the make all  target ;-), so you
don't have to type
make doc explicitly.

If I remember correctly, ADD_CUSTOM_COMMAND did add a Custom Command entry to the Makefile,
the purpose of which, I did not fully understand as the target entry  did not use it.

So, I am no less confused than you are other than knowing that above approach worked for me.

>
> Hello again
>
> I am endeavouring to use ADD_CUSTOM_COMMAND and ADD_CUSTOM_TARGET
> so that I can build the documentation for my system.  This will
> be a mixture of HTML and LaTeX source.
>
> I have looked at the example in the FAQ, read the manual and searched
> the archives, but I am still left with no clear understanding of how
> this scheme functions.  I've also tried reverse engineering the Makefile
> with no success.
>
> I'll list the FAQ example and ask questions as I go:
> >From the FAQ, here is how to convert a .tex file into .dvi,
> The variables ${Document_SOURCE_DIR}, ${LATEX_COMPILE}, and
> ${Document_BINARY_DIR} are pre-defined.
>
> ADD_CUSTOM_TARGET(LaTeXDocument ALL echo)
> ADD_CUSTOM_COMMAND(
>     SOURCE    ${Document_SOURCE_DIR}/TDocument.tex
>     COMMAND   ${LATEX_COMPILE}
>     ARGS      ${Document_SOURCE_DIR}/TDocument.tex
>     TARGET    LaTeXDocument
>     DEPENDS   ${Document_BINARY_DIR}/TDocument.tex
>     OUTPUTS   ${Document_BINARY_DIR}/TDocument.dvi
> )
>
> I have many questions...   :-(
>
> 1) ADD_CUSTOM_TARGET(LaTeXDocument ALL echo)
>
> What do the arguments mean ?  I assume "LaTeXDocument" is a new generic
> target name made up here.  It is used below so I will defer further
> questions until then.   WHat does "echo" do ?
>
> The docs. say the syntax is
>
>  ADD_CUSTOM_TARGET (Name [ALL] command arg arg arg...)
>
> it describes the meaning of ALL.   But this suggests that I now
> have a command "echo" and no arguments.  WHat does this do ?
>
> I might have thought that this CMake command was going to describe
> how to build a target of type  'LaTeXDocument' and that the 'command'
> would be the one needed to compile a LaTeX document (e.g. a
> CUSTOM_COMMAND) and that 'arg'  might be the arguments, but that does not
> appear to be the case.
>
> So I am left bemused by this example.
>
> 2)  ADD_CUSTOM_COMMAND
>
> I though this would be the custom command  needed to process a target
> of type LaTeXDocument, and it is, although I am not sure why.  This
> custom command does not have a name, and so it can't be associated
> via the 'command' argument of ADD_CUSTOM_TARGET (and it isn't).  The
> only association appears to be the the line below
>
>     TARGET    LaTeXDocument
>
> does that mean this command is used to build CUSTOM_TARGETS of type
> LateXDocument ?  If it does it seems pointless, because I don't
> see how the ADD_CUSTOM_TARGET is then used in any way to add a specific
> target.
>
> ADD_CUSTOM_COMMAND(
>     SOURCE    ${Document_SOURCE_DIR}/TDocument.tex
>
> I assume this indicates that the input file should be found as specified.
> In this example, the actual source file is included (TDocument.tex).  Does
> that mean for every input source file I have to create a complete
> ADD_CUSTOM_COMMAND like this ?  Again I was expecting the CUSTOM_COMMAND
> to essentially be a macro, and ADD_CUSTOM_TARGET would invoke that
> macro/command for each desired target.  It doesn't appear to be that way.
>
>     COMMAND   ${LATEX_COMPILE}
>
> ok this is the command to execute.  In this case, it would be 'latex'
>
>     ARGS      ${Document_SOURCE_DIR}/TDocument.tex
>
> These are the arguments for the command.  What is their relationship
> to the arguments in ADD_CUSTOM_TARGET.  Why is the SOURCE file
> repeated here ?  SUrely the arguments would be things that control
> the functioning of latex, not the input and output becuase there exists
> the SOURCE and OUTPUTS variables.
>
> The only thought I have here is that for each command, you cannot guess
> what order arguments might be required, and therefore you must put the
> input/output on the arguments list here.  In that case, what is the
> purpose oF SOURCE and OUTPUTS ?  I could underestand if they were
> just directories but that is not how they are used in this example.
>
>     TARGET    LaTeXDocument
>
> WHat is the purpose of this line ? DOes it associate with
> ADD_CUSTOM_TARGET in some way ?    If so, what is that association ?
>
>     DEPENDS   ${Document_BINARY_DIR}/TDocument.tex
>
> I assume this means that if this file changes, redo the output
>
>     OUTPUTS   ${Document_BINARY_DIR}/TDocument.dvi
>
> This is the output file ?
> )
>
> My coding of this for my project looks like:
>
> SET (LATEX_COMPILE latex)
> SET(DOC_ROOT ${MITK_SOURCE_DIR}/Documentation}
>
> ADD_CUSTOM_TARGET (LaTeXDocument ALL echo)
> ADD_CUSTOM_COMMAND(
>     SOURCE    ${DOC_ROOT}/junk.tex
>     COMMAND   ${LATEX_COMPILE}
>     ARGS      ${DOC_ROOT}/junk.tex
>     TARGET    LaTeXDocument
>     DEPENDS   ${DOC_ROOT}/junk.tex
>     OUTPUTS   ${MITK_BINARY_DIR}/junk.dvi
> )
>
> Well if I add these commands to my CMakeLists.txt file, the resultant
> Makefile contains precisely nothing  regarding any latex commands etc. and
> produces no output.
>
> Admittedly, the docs. say that 'ADD_CUSTOM_TARGET : adds an extra target
> that does not produce output', so it has certainly lived up to that
> description, unhelpful though it is.
>
> What I was expecting in all of this was something like
>
> 1) define a custom command
>
> ADD_CUSTOM_COMMAND (
>    NAME   MYCOMMAND
>    COMMAND  latex
>    ARGUMENTS
> )
>
> 2) then I make a target and tell it which command to use, something like:
>
> ADD_CUSTOM_TARGET (myDoc.dvi myDoc.tex MYCOMMAND)
>
> Anyway, I am sure it works as it is, but I have no idea how !   I'd really
> appreciate a clear description (please put in docs) and working example
> (please update FAQ) of these  commands.   Sorry this email is so long.
>
> regards
> Neil
>
> --__--__--
>
> _______________________________________________
> Cmake mailing list
> Cmake at public.kitware.com
> http://public.kitware.com/mailman/listinfo/cmake
>
> End of Cmake Digest

--
    Nils H. Busch
    Max-Planck-Institute of Cognitive Neuroscience
    phone:  ++49 (341) 9940-035 fax:  ++49 (341) 9940-204
    e-mail: nilsb at cns.mpg.de