-
Notifications
You must be signed in to change notification settings - Fork 24
Scenarios
2016-01-22
Install the service client library into my development environment so I can use it from my usual development process. If a needed tool doesn't exists (e.g., Maven), handle it gracefully. This may only be a problem if the user is trying to install all languages; a Node developer is likely to have npm, etc.
quark install java https://example.com/slack.q
Output the generated source code so that the user can build it using the same system he's using to build his own code, and so that he can distribute all the source code (generated code plus whatever he wrote) conveniently. This should also output a list of dependencies in a human-consumable manner, i.e. dependencies.txt.
quark compile java https://example.com/slack.q
qbuild
|-- dependencies.txt
|-- slack
| |-- Channel.java
| |-- SlackClient.java
| |-- ...
| `-- event
| |-- ChannelArchive.java
| |-- ...
| `-- UserTyping.java
`-- slack_md
|-- Root.java
|-- ...
Output the source as above, but additionally include enough packaging metadata so that the library can be installed or pushed to a repository. This should incorporate the dependency information into the packaging metadata.
quark pkgsrc javascript https://example.com/slack.q
qbuild
|-- index.js
|-- package.json
|-- slack
| |-- event
| | `-- index.js
| `-- index.js
`-- slack_md
`-- index.js
Generate a package artifact that can be installed or redistributed manually. This may not make sense for Java.
quark package python https://example.com/slack.q
qbuild
`-- slack-0.1.0-py2-none-any.whl
We should figure out some sort of developer setup command too, which would need to be told what sort of build tool for which quark should generate support, e.g., Eclipse or whatever.
quark develop <mumble>
Another idea for quark install: Does it matter whether the compilation et al happens on the server or client? Not really. If it happens on the server, we could offer a lighter command-line utility that just fetches and installs.
quark install https://example.com/slack/java
quarkinstall https://example.com/slack/java
Can it do something cool/relevant at all?
One language which isn't necessarily the user's language is fine
- Run slack-bot
- Look slack-bot, understand how to use Quark's output
Please comment: What other ways might evaluator phase 1 decide that Quark does something cool or relevant?
Can it do something cool/relevant in my environment?
Can I use it in my language? Even better, with my existing toolset?
- Above steps
- Look at slack.q, understand how to speak HTTP and WS
- Look at generated code
- Same-ish as above?
- ...?
Please comment: How else might evaluator phase 2, i.e. someone who has decided Quark is interesting, determine whether Quark may be a fit for his/her environment?
- does it support my languages/toolsets?
- does it make using my languages/toolsets easier?
- does it help me test or deploy my app more easily?
- does it simplify one or more difficult tasks I need to do?
- Writing a brand new client.q incrementally from scratch
- Taking an existing example client.q and tweaking it to fit another problem
- Taking an existing/debugged client.q and building an app on top of it
- Taking an existing/debugged client.q and easily distributing all packages that can be produced from it
- Taking the output package from client.q (Wheel or JAR or NPM package) and building an app on top of it -- no client.q file required. Can Quark help on this end at all? Maybe generate a skeleton for the user code? Boilerplate? See also: Adaptive (or Thrift or GRPC).
- committed service author
- committed service user
- committed protocol author
The key difference between service author and protocol author is that protocol author will need to write and debug Quark code, service author likely will not (they will use annotations)
Note: this requires the ability for third party annotation development
- service already exists
- client.q does not exist
- developing client.q means developing client API in quark and the client unit tests in java
- should support developing in an IDE
- client.q
- client unit tests
- useable development source tree
quark --java develop --java-package org.foo.api client.q
produces the following layout:
client/
+ -- pom.xml
+ -- src/main/quark/client.q
+ -- src/test/java/org/foo/api/ClientTest.java
The pom.xml references a quark-maven-plugin that will invoke
quark compile --out ${project-build-directory}/generated-sources/quark
API is developed using a text editor
The test template can contain a factory method to instantiate the default quark runtime
API tests are written by the user using a text editor
user implements API in quark against the server and tests
A new quark sub-command to generate the above structure
A simple maven plugin that integrates quark compilation into the maven build process. Good examples to adapt is protobuf-maven-plugin
delta to above is that client.q already exists.
quark develop --java client.q
the command notices that client.q already exists and it can either:
- generate the pom.xml with a different source location for the client.q, or
- ask user for permission to move client.q into the 'standard location' as per above scenario
no other changes to above are needed
quark install --java client.q
emits dependency section to put into your pom.xml
quark install --java client.q --into path/to/users/pom.xml
same as above, but quark modifies users pom.xml
Taking an existing/debugged client.q and easily distributing all packages that can be produced from it
quark publish --java client.q
emits dependency and repository sections to put into your pom.xml
Taking the output package from client.q (Wheel or JAR or NPM package) and building an app on top of it
no client.q file required. Can Quark help on this end at all?
Maybe generate a skeleton for the user code? Boilerplate? See also: Adaptive (or Thrift or GRPC).
When generating or installing a package from Quark code, we will use the annotated version, but if there is a text tag at the end (e.g., alpha), then we will append an incrementing number on each subsequent build. 1.0.3-alpha -> 1.0.3-alpha-2303 (JS) or 1.0.3a2303 (Py) or 1.0.3-2303 (Java). This will facilitate rapid iteration of Quark code.
This is in my (ark3) tree, but needs to be reconsidered based on the above discussion.
Quark compiler.
Usage:
quark [options] <command> <file>...
quark -h | --help | help
quark --version
Commands (One target language)
develop Create a project directory skeleton
package Emit package artifact in the current directory
install Generate, install, and discard package artifact
docs Emit HTML documentation
publish Push installable artifacts to language repository
(Maven Central, PyPi, npmjs.org) and show the
corresponding usage commands.
Developer Commands (One or more target languages, defaults to all)
compile Emit code in target language(s) to the output directory
build Compile, then run the target language compiler(s)
build-docs Build, then build the target language documentation
Target languages:
--java Emit Java code
--python Emit Python code
--javascript Emit JavaScript code
Options:
-h --help Show this information
--version Show version
-o DIR, --output DIR Directory for output files (caution; see below)
[defaults to basename of the first input file]
Developer Command options:
--all Emit code for all available target languages
--java-out DIR Subdirectory for Java code [default: java].
--python-out DIR Subdirectory for Python code [default: py].
--javascript-out DIR Subdirectory for JavaScript code [default: js].
--in-place Output everything to the current directory. This option
overrides all other directory/subdirectory options. It
does not delete existing output files, but can overwrite
almost anything in the current directory. Use with
extreme care. Not recommended. Deprecated, i.e. will be
removed in a future release.