[Cmake] ADD_CUSTOM_COMMAND etc

Wed Apr 9 07:33:10 EDT 2003

Hi Niel,

On Wed, 2003-04-09 at 02:13, Neil Killeen wrote:
> 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.

Good for you. Let me try to explain.

> 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)

This is inheritance from Visual Studio. Every thing in VS is a target.
For example executable, libraries, and also the entry points for custom
rules. The ALL argument means that it will be part of all target. That
essentially means it will happen every time. The echo argument is not
necessary any more. It is there because in CMake 1.4 there had to be
command there. Now the command is optional. 

> 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

Yes. All custom commands (rules) are associated with a target. This can
be executable, library, or custom target.

> 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

Each custom command is attached to a source. It means check this source
before running command.

> 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 arguments are simply arguments to the command. You run latex like
this:

latex sourcefile.tex

and since the source file is ${Document_SOURCE_DIR}/TDocument.tex, the
command is:

latex ${Document_SOURCE_DIR}/TDocument.tex

> 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 ?

DEPENDS is where you put extra dependencies. You do not have to put the
one from SOURCE, but if you do, nothing bad should happen. There has to
be one SOURCE, but you do not need DEPENDS. 

OUTPUTS is where you put what the custom command will generate. This is
so that CMake can chain custom commands.

> 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.

So much to do and so little time...

Ok, here is a hopefully working example:

SET (LATEX_COMPILE latex)
SET(DOC_ROOT ${MITK_SOURCE_DIR}/Documentation}

ADD_CUSTOM_TARGET (LaTeXDocument ALL)
ADD_CUSTOM_COMMAND(
    SOURCE    ${DOC_ROOT}/junk.tex
    COMMAND   ${LATEX_COMPILE}
    ARGS      ${DOC_ROOT}/junk.tex
    TARGET    LaTeXDocument
    OUTPUTS   ${MITK_BINARY_DIR}/junk.dvi
)
ADD_CUSTOM_COMMAND(
    SOURCE    LaTeXDocument
    TARGET    LaTeXDocument
    DEPENDS   ${MITK_BINARY_DIR}/junk.dvi
)

You need the second custom command to drive the first one.

I will try to update faq at some point. I have to imagine good example
first. I am planning to add a test to CMake which will do some custom
command magic, but you will have to wait. 

We have on the board as one of major things to overall the whole custom
rules thing. 

				Andy