-
Notifications
You must be signed in to change notification settings - Fork 10
ToolkitLayout
This is a proposal on how an IBMStreams SPL toolkit project should be structured:
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) Why optional, using the default namespace will lead to name clashes -
.../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.
- 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.
- provides a cleaner redistribution of the actual toolkit. Consumers of the toolkit are not likely to want the tests (junits etc...).
- simplfies the toolkit structure since there are no longer embedded toolkits within the toolkit.
- There is now a separation and people cant get it all in one package.
- com.ibm.streamsx.abc.test and com.ibm.streamsx.abc.samples look like toolkit names. If they are toolkits, I think that is unnecessarily restrictive. If they are not (eg, they have structure underneath them), then I think their names are misleading.
Same layout as 1, except com.ibm.streamsx.abc.test and com.ibm.streamsx.abc.samples are replaced by tests and samples or streamx.abc.test and streamx.abc.samples, or abc.test and abc.samples respectively. Underneath these directories, we wouldn't suggest a particular structure.
Having a fixed name samples and tests seems a simpler approach, and maybe similar to a maven approach that benefits from a fixed layout.
Would it be better to have a expected structure under samples, in that if they are samples, then they are SPL applications which are are single application toolkits, so it would be expected that the next level down would be a set of toolkits, e.g
samples/feature1/<sample application toolkit>samples/feature2/<sample application toolkit>
It should also be documented that the sample applications should use a namespace to avoid name clashes for the main composite across many toolkits, e.g. com.ibm.streamsx.abc.sample.feature1.
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 -
.../etc/tests- Directory of tests
- 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.
- toolkits contain extras not needed for usage
- Actually not possible with current spl compiler, as I understand it. The compiler will try to build any spl files under test. Did you mean etc/tests? Changed.
- unclear why 2nd point in pros can't be handled with a zip containing all the dirs, especially given that git clone will get everything (toolkit, tests, samples). _Note the comment about the user not caring about source code control systems, they just want to download the toolkit and build and test it. You can download linus packages (e.g. libpcap) as a tar, compile them and run tests, all without know what is being used for source control _