ToolkitLayout

Toolkit Layout

This is a proposal on how an IBMStreams SPL toolkit project should be structured:

Proposal 1

A SPL toolkit project in IBMStreams is expected to have a common layout like this, for the project streamsx.abc. Note the toolkit is named com.ibm.streamsx.abc:

• LICENSE.md - Project license file
• README.md - Project README file
• com.ibm.streamsx.abc - SPL Toolkit directory
• .../LICENSE.md - Project license file (duplicated here so that distributions of the toollkit maintain the license)
• .../com.ibm.streamsx.abc - Top-level namespace (optional)
• .../com.ibm.streamsx.abc.efg - Sub-namespaces (optional), structure can be as deep as is required.
• .../standard toolkit layout - Expected layout for a SPL toolkit.
• .../doc - Documentation created by SPL doc (optional, but recommended)
• com.ibm.streamsx.abc.samples - Directory for samples using the toolkit. Samples are self-contained and do not depend on any other toolkits that need to be downloaded. Thus a sample in this directory depends on the toolkit and optionally toolkits shipped with IBM InfoSphere Streams.
• .../com.ibm.streamsx.abc.samplename - A SPL toolkit with sample use of a feature of the com.ibm.streamsx.abc` toolkit (optional). Note a project may have multiple samples in a single toolkit or multiple toolkits for the toolkit.
• com.ibm.streamsx.abc.tests - Directory of tests
• `.../??' - Structure to be defined, may be SPL toolkits with test applications, JUnit tests etc.

Note each toolkit that may be distributed independently of the project, must contain a LICENSE.md file.

Sample or demonstration use of the com.ibm.streamsx.abc toolkit that require additional toolkits are expected to be a project under IBMStreams/samples.

Pros:

1. separates the samples from the toolkit. Enables people to get either or both depending on what is required. By moving the samples out of the toolkit it is simpler to create packaging where all the samples are in a samples directory for all toolkits.
2. provides a cleaner redistribution of the actual toolkit. Consumers of the toolkit are not likely to want the tests (junits etc...).
3. simplfies the toolkit structure since there are no longer embedded toolkits within the toolkit.

Cons:

1. There is now a separation and people cant get it all in one package.

Proposal 2

Similar to above, but moves tests and samples to be within the SPL toolkit directory as:

• com.ibm.streamsx.abc - SPL Toolkit directory
• .../samples - Directory of samples
• .../tests - Directory of tests

Pros:

• Matches the current layout for samples recommended by the product
• Allows a single toolkit to be downloaded and contain samples and tests. In some cases developers may want to run tests for an toolkit in their environment without having to use git, e.g. to test a toolkit with a different version of a shared library or jar. This is typical for open source downloads in Linux, where the code is downloaded as a package and can be built and tested as required, without interacting SCM.

Cons:

• toolkits contain extras not needed for usage
• unclear why 2nd point in pros can't be handled with a zip containing all the dirs