Docs: copy/pastable examples for common custom target types

[IcedQuinn]

Using build_file:

1. • One input one output (ex. one markdown -> one html)
2. • One input multiple outputs (ex. one lex file becomes one .c file which then becomes one compiled dependency)
3. • Multiple inputs one output (ex. creating a zip)
4. • Multiple inputs multiple outputs (ex. a GSL script which runs both a template file and a file to fill the template's data and outputs one or more generated code files)

1 is already done and PR'd

Using build_files:

1. • One input one output (ex. one markdown -> one html)
2. • One input multiple outputs (ex. one lex file becomes one .c file which then becomes one compiled dependency)
3. • Multiple inputs one output (ex. creating a zip)
4. • Multiple inputs multiple outputs (ex. a GSL script which runs both a template file and a file to fill the template's data and outputs one or more generated code files)

Using buildcmd:

1. • One input one output (ex. one markdown -> one html)
2. • One input multiple outputs (ex. one lex file becomes one .c file which then becomes one compiled dependency)
3. • Multiple inputs one output (ex. creating a zip)
4. • Multiple inputs multiple outputs (ex. a GSL script which runs both a template file and a file to fill the template's data and outputs one or more generated code files)

Using buildcmd_files:

1. • One input one output (ex. one markdown -> one html)
2. • One input multiple outputs (ex. one lex file becomes one .c file which then becomes one compiled dependency)
3. • Multiple inputs one output (ex. creating a zip)
4. • Multiple inputs multiple outputs (ex. a GSL script which runs both a template file and a file to fill the template's data and outputs one or more generated code files)

I may be able to PR these as I figure them out.

[waruqi]

One input one output (ex. one markdown -> one html)

use on_buildcmd_file or on_build_file

rule("test")
    set_extensions(".md")
    on_buildcmd_file(function (target, batchcmds, sourcefile, opt)
    end)

One input multiple outputs (ex. one lex file becomes one .c file which then becomes one compiled dependency)

we can also use on_buildcmd_file or on_build_file to generate multiple output files

Multiple inputs one output (ex. creating a zip)

we can use on_buildcmd_files or on_build_files or on_build or on_link

rule("test")
    set_extensions(".xxx")
    on_buildcmd_files(function (target, batchcmd, sourcebatch, opt)
        -- generate single output file
    end)
    on_link(function ()
         -- disable link
    end)

Multiple inputs multiple outputs (ex. a GSL script which runs both a template file and a file to fill the template's data and outputs one or more generated code files)

use on_buildcmd_files or on_build_files or on_build

[IcedQuinn]

single input single output

finished this one; opened a PR in the docs repo for it

multiple inputs one output

yes but that just gives you a list of all .xxx files which were added to the target. if you have (a1, ..., an) -> a then that works fine.

if you have (a1, a2) -> a and (b1, b2) -> b in the same target, you have to set custom properties when you go to do add_files or you have to carry the mappings via set_values.

the cleanest way seems to be to make a separate target for a and b which you then have the project depend on. but this requires using the object kind which loses access to the filename attributes and also breaks generating makefiles (a separate issue.) using the phony kind seems to lose using add_files in addition to filenames attributes.

what i experimented with is using either custom properties in add_rules and carrying meta-data in set_values, and using separate targets. for example you can do something like

target('level02')
set_kind(???)
add_rules('compilemaps')
add_rules('compiletextures')
add_files('blah.map dirt.png grass.png etc.png')