Bndtools Template README
========================

Welcome to your new Bndtools template! Here are some notes on how to make your
template do what you want.

bnd.bnd
-------

The bnd.bnd file declares a Provide-Capability in the 'org.bndtools.template'
namespace. This enables Bndtools to find your template bundle in the
repository. The attributes on the capability are as follows:

 * 'org.bndtools.template': either 'project' or 'bndrun'
 * 'name': the name of the template
 * 'category': the category of the template (optional)
 * 'dir': the base dir of the template resources within your bundle; defaults
   to 'template'
 * 'help': path to a document within your bundle that will be displayed in
   the template selection dialog (optional) 
 * 'icon': the URL of an icon for the template (optional)

For performance, is it strongly recommended to use the "data" URL scheme for
the icon, as defined in RFC 2397 of the IETF. The Base64 encoding of a file
can be embedded using a bnd macro (be careful about the file size!). For example:

	icon="data:image/gif;base64,\${base64;icons/mytemplate.gif}"


Template Files
--------------

Within your template directory, create a folder structure that matches what you
want the template to generate. For example to generate the following layout:

	bnd.bnd
	src/Main.java

Then just create the same layout inside your template directory:

	bnd.bnd
	src/Main.java

Unless the file name is a recognized binary format, or has been explicitly
ignored (see below), it will be processed through StringTemplate before being
written out.

The default delimiter character used with StringTemplate is '$', so you can put
template expressions in the file as follows:

	Bundle-SybolicName: $projectName$

See below for a list of the parameter names passed into the template by Bndtools.

The output file names can also be processed by template. For example:

	$srcDir$/$basePackageDir$/Main.java

When the expected output is a single file (e.g. a bndrun file), that filename will be
supplied as the parameter 'fileName'. Therefore the template sources should contain a
file named '$fileName$'.


Parameter Names
---------------

Project templates can use any of the following parameter names:

	projectName -- name of the project
	version -- version of the project
	srcDir -- Java source directory
	basePackageName -- base Java package name
	basePackageDir -- base package dir (=basePackageName, with dots replaced by slashes)
	binDir -- output classes directory
	testSrcDir -- Java source directory for tests
	testBinDir -- output classes directory for tests
	targetDir -- bnd's target directory

Bndrun templates can use any of the following parameter names:

	fileName -- the name of the output file, as selected by the user
	fileBaseName -- the name of the output file, minus any extension
	projectName -- the name of the enclosing Eclipse project, if any

	 
Customizing the Template Processor
----------------------------------

The processor can be customized by including a special file named
'_template.properties' in the template directory. For example this can be used
to use a different pair of delimiter characters:

	leftDelim: <
	rightDelim: >

These alternative delimiters will be used for filenames and templates.

You can also add instructions to process (or not process) certain filetypes
(this will be in addition to the recognised file types in bnd):

	# don't process .img files
	process.before: !*.img

	# don't process OR copy readme.* files
	ignore: readme.*

Version Information
-------------------

This project was generated by the ${Bundle-Name}, version ${Bundle-Version}
(git commit ${Git-SHA}).
