No subject

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