Skip to content
Permalink
Browse files
Merge pull request #2 from geomacy/code-grant-update
Add further updates around build process and licensing.
  • Loading branch information
ahgittin committed Mar 1, 2016
2 parents 8fccde0 + 15a7c5a commit 866eaa1def79798f9230d8da8e67bdea4cc3d390
Show file tree
Hide file tree
Showing 12 changed files with 476 additions and 362 deletions.
378 LICENSE

Large diffs are not rendered by default.

128 README
@@ -0,0 +1,128 @@

Apache Brooklyn Command Line Client

What is it?
-----------

A command line client, "br", for Apache Brooklyn (https://brooklyn.apache.org).

With this tool you can deploy and manage applications on a running Brooklyn server.

Documentation
-------------

There follows below a brief summary of how to use the tool, however, the full documentation for the tool is included
along with the [Brooklyn Documentation](https://brooklyn.apache.org/v/latest/ops/cli/cli-ref-guide.html).

Licensing
---------

Please see the file called LICENSE.

Getting the right binary
------------------------

The release for the tool includes binaries built for a number of platforms and architectures. These binaries are
provided in subdirectories alongside this README, named for the platform and architecture:

darwin.386/br
darwin.amd64/br
freebsd.386/br
freebsd.amd64/br
linux.386/br
linux.amd64/br
netbsd.386/br
netbsd.amd64/br
openbsd.386/br
openbsd.amd64/br
windows.386/br
windows.amd64/br

To use the tool, add the appropriate subdirectory to your PATH, for example, when br is obtained by extracting the
main Apache Brooklyn release into your home directory under "apache-brooklyn", then the command would be like

$ PATH=$PATH:$HOME/apache-brooklyn/bin/brooklyn-client-cli-0.9.0/linux.amd64


Running
-------

Ensure your path contains $GOPATH/bin.

First, log in to your Brooklyn instance with:

$ br login URL [USER PASSWORD]

See the help command for info on all commands:

$ br help

And for help on individual commands:

$ br help COMMAND


Scopes
------

Many commands require a "scope" expression to indicate the target on which they operate. The scope expressions are
as follows (values in brackets are aliases for the scope):

- application APP-ID (app, a)
Selects an application, e.g. "br app myapp"

- entity ENT-ID (ent, e)
Selects an entity within an application scope, e.g. "br app myapp ent myserver"

- effector EFF-ID (eff, f)
Selects an effector of an entity or application, e.g. "br a myapp e myserver eff xyz"

- config CONF-KEY (conf, con, c)
Selects a configuration key of an entity e.g. "br a myapp e myserver config jmx.agent.mode"

- activity ACT-ID (act, v)
Selects an activity of an entity e.g. "br a myapp e myserver act iHG7sq1"


Commands
--------

Commands whose description begins with a "*" character are particularly experimental and likely to change in upcoming
releases. If not otherwise specified, "SCOPE" below means application or entity scope. If an entity scope is not
specified, the application entity is used as a default.

- access Show access control
- activity Show the activity for an application / entity
- add-catalog * Add a new catalog item from the supplied YAML
- add-children * Add a child or children to this entity from the supplied YAML
- application Show the status and location of running applications
- catalog * List the available catalog applications
- config Show the config for an application or entity
- delete * Delete (expunge) a brooklyn application
- deploy Deploy a new brooklyn application from the supplied YAML
- destroy-policy * Destroy a policy
- effector Show the effectors for an application or entity
- entity Show the entities of an application or entity
- env Show the ENV stream for a given activity
- invoke Invoke an effector of an application and entity
- locations * List the available locations
- login Login to brooklyn
- policies Show the list of policies for an application and entity
- policy Show the status of a policy for an application and entity
- rename Rename an application or entity
- restart Invoke restart effector on an application and entity
- sensor Show values of all sensors or named sensor for an application or entity
- set Set config for an entity
- spec Get the YAML spec used to create the entity, if available
- start Invoke start effector on an application and entity
- start-policy Start or resume a policy
- stderr Show the STDERR stream for a given activity
- stdin Show the STDIN stream for a given activity
- stdout Show the STDOUT stream for a given activity
- stop Invoke stop effector on an application and entity
- stop-policy Suspends a policy
- tree * Show the tree of all applications
- version Display the version of the connected Brooklyn
- help


145 README.md
@@ -7,30 +7,41 @@ A command line client for [Apache Brooklyn](https://brooklyn.apache.org).

## Toolchain

You will need the following tools to build the CLI:
The CLI tool is written in Go and should be obtained and built as a standard Go project.
You will need the following tools to build it:

- Go (min version 1.5.1), with full cross-compiler support (see https://golang.org/dl).
On Mac, if using Homebrew, use "brew install go --with-cc-all"
- godep (see https://github.com/tools/godep)

Optional:
- Maven (used by the Brooklyn build process)

- Maven (see note below on the Brooklyn build process)


## Build Pre-Requisites
## Workspace Setup

Go is very particular about the layout of a source tree, and the naming of packages. It is therefore important to
get the code from github.com/apache/brooklyn-client and not your own fork. If you want to contribute to the
project, the procedure to follow is still to get the code from github.com/apache/brooklyn-client, and then to add your
own fork as a remote.

- Ensure your [$GOPATH](http://golang.org/cmd/go/#hdr-GOPATH_environment_variable) is set correctly
to a suitable location for your Go code.
- Install Brooklyn CLI and dependencies (note the "-d" parameter, which instructs Go to download the files but not
build the code).
to a suitable location for your Go code, for example, simply $HOME/go.
- Get the Brooklyn CLI and dependencies. Note the "-d" parameter, which instructs Go to download the files but not
build the code, see why in the note below on dependency management.

`go get -d github.com/apache/brooklyn-client/br`


## A note on dependency management

The CLI has a small number of dependencies, notably on codegansta/cli. To manage the version of dependencies, the CLI
code currently uses godep. When contributing to the CLI it is important to be aware of the distinction. To avoid
potentially bringing in new versions of dependencies, use "godep go" to build the code using the dependencies
saved in br/Godeps. Alternatively, to bring in the latest versions of the dependencies, build with "go get", but in
code currently uses [godep](https://github.com/tools/godep).
When contributing to the CLI it is important to be aware of the distinction. To avoid potentially bringing in new
versions of dependencies, use "godep go" to build the code using the dependencies saved in br/Godeps.
Alternatively, to bring in the latest versions of the dependencies, build with "go get", but in
that case remember to update the dependencies of the project using "godep save" along with your commit.

## Compiling the code with Go for development purposes
@@ -59,92 +70,54 @@ cd $GOPATH/src/github.com/apache/brooklyn-client/br
godep save
```

## Testing

The code includes a test script in the [test](test) directory. This deploys a Tomcat server on a location of your choice
and runs a number of tests against it, to verify that the br commands perform as expected. To use this you must edit
the file "test_app.yaml" to change the location to your own value, and then invoke the test script like the following,
where the username and password need only be supplied if Brooklyn requires them:

```bash
$ sh test.sh http://your-brooklyn-host:8081 myuser mypassword
```

Note, the tests are not yet comprehensive, and contributions are welcome.

## Building the code as part of the Brooklyn build process

## Building the code for release
For consistency with the other sub-projects of the overall [Brooklyn](https://github.com/apache/brooklyn) build, Maven
is used to perform the build when brooklyn-client is built as one of the sub-modules of Brooklyn. Most of the work is
delegated to the release/build.sh script, which cross-compiles the code for a number of platform-architecture combinations.

Invoke the build script via Maven with one of

Either:
- Use the build script in the "release" folder directly (see its usage for details), or
- Invoke the build script via Maven with one of
- ```mvn clean install``` build for all supported platforms
- ```mvn -Dtarget=native clean install``` build for the current platform
- ```mvn -Dtarget=cross -Dos=OS -Darch=ARCH clean install``` build for platform with operating system OS and architecture ARCH

This builds the requested binaries into the "target" directory, each with a file name that includes the version,
timestamp, and architecture details, e.g. br.0.9.0.20151218-195906.linux.amd64, and installs a zip file containing them
all as a maven artifact. To run any of these as "br" of course you will need to create an alias or soft link.
*NOTE* This does *not* build the code into your usual GOPATH. To allow the project to be checked out along with the
other Brooklyn submodules and built using Maven, without any special treatment to install it into a separate GOPATH
location, the Maven build makes no assumption about the location of the project root directory. Instead, the Maven
`target` directory is used as the GOPATH, and a soft link is created as `target/src/github.com/apache/brooklyn-cli` to
the code in the root directory. If godep is already installed in the PATH, it is used, otherwise Go is used to fetch
godep and install it. The CLI dependencies need not be fetched as they are used from the Godeps directory by godep.

This builds the requested binaries into the "target" directory, each in its own subdirectory with a name that includes
the platform/architecture details, e.g. bin/linux.386/br. The build installs a maven artifact to the maven repository,
consisting of a zip file containing all the binaries. This artifact can be referenced in a POM as

```xml
<groupId>org.apache.brooklyn</groupId>
<artifactId>brooklyn-client-cli</artifactId>
<classifier>bin</classifier>
<type>zip</type>
<version>...</version>
```


## Running

Ensure your path contains $GOPATH/bin.

First, log in to your Brooklyn instance with:

$ br login URL [USER PASSWORD]

See the help command for info on all commands:

$ br help

And for help on individual commands:

$ br help COMMAND


## Scopes
Many commands require a "scope" expression to indicate the target on which they operate. The scope expressions are
as follows (values in brackets are aliases for the scope):
- application APP-ID (app, a)
Selects an application, e.g. "br app myapp"
- entity ENT-ID (ent, e)
Selects an entity within an application scope, e.g. "br app myapp ent myserver"
- effector EFF-ID (eff, f)
Selects an effector of an entity or application, e.g. "br a myapp e myserver eff xyz"
- config CONF-KEY (conf, con, c)
Selects a configuration key of an entity e.g. "br a myapp e myserver config jmx.agent.mode"
- activity ACT-ID (act, v)
Selects an activity of an entity e.g. "br a myapp e myserver act iHG7sq1"


## Commands

Commands whose description begins with a "*" character are particularly experimental and likely to change in upcoming
releases. If not otherwise specified, "SCOPE" below means application or entity scope. If an entity scope is not
specified, the application entity is used as a default.

- *access* Show access control
- *activity* Show the activity for an application / entity
- *add-catalog* * Add a new catalog item from the supplied YAML
- *add-children* * Add a child or children to this entity from the supplied YAML
- *application* Show the status and location of running applications
- *catalog* * List the available catalog applications
- *config* Show the config for an application or entity
- *delete* * Delete (expunge) a brooklyn application
- *deploy* Deploy a new brooklyn application from the supplied YAML
- *destroy-policy* Destroy a policy
- *effector* Show the effectors for an application or entity
- *entity* Show the entities of an application or entity
- *env* Show the ENV stream for a given activity
- *invoke* Invoke an effector of an application and entity
- *locations* * List the available locations
- *login* Login to brooklyn
- *policies* Show the list of policies for an application and entity
- *policy* Show the status of a policy for an application and entity
- *rename* Rename an application or entity
- *restart* Invoke restart effector on an application and entity
- *sensor* Show values of all sensors or named sensor for an application or entity
- *set* Set config for an entity
- *spec* Get the YAML spec used to create the entity, if available
- *start* Invoke start effector on an application and entity
- *start-policy* Start or resume a policy
- *stderr* Show the STDERR stream for a given activity
- *stdin* Show the STDIN stream for a given activity
- *stdout* Show the STDOUT stream for a given activity
- *stop* Invoke stop effector on an application and entity
- *stop-policy* Suspends a policy
- *tree* * Show the tree of all applications
- *version* Display the version of the connected Brooklyn
- *help*

See instructions in the included [Runtime README](README) file.

----
Licensed to the Apache Software Foundation (ASF) under one

This file was deleted.

This file was deleted.

@@ -19,37 +19,37 @@
<project name="CLI" >
<property name="build.script" location="${basedir}/release/build.sh"/>

<target name="all" >
<exec executable="${build.script}">
<target name="all" >
<exec executable="${build.script}" failonerror="true">
<arg value="-A"/>
<arg value="-t"/>
<arg value="-l"/>
<arg value="${project.version}"/>
<arg value="-d"/>
<arg value="${project.build.directory}"/>
<arg value="-s"/>
<arg value="${basedir}"/>
</exec>
</target>

<target name="cross">
<exec executable="${build.script}">
<target name="cross" >
<exec executable="${build.script}" failonerror="true">
<arg value="-t"/>
<arg value="-l"/>
<arg value="${project.version}"/>
<arg value="-a"/>
<arg value="${arch}"/>
<arg value="-o"/>
<arg value="${os}"/>
<arg value="-d"/>
<arg value="${project.build.directory}"/>
<arg value="-s"/>
<arg value="${basedir}"/>
</exec>
</target>

<target name="native">
<exec executable="${build.script}">
<arg value="-l"/>
<arg value="${project.version}"/>
<target name="native" >
<exec executable="${build.script}" failonerror="true">
<arg value="-d"/>
<arg value="${project.build.directory}"/>
<arg value="-s"/>
<arg value="${basedir}"/>
</exec>
</target>

0 comments on commit 866eaa1

Please sign in to comment.