Skip to content

Commit 6ee6ac0

Browse files
committed
Merge branch 'split-readme'
Fixes #10
2 parents 7a9f460 + 60df09c commit 6ee6ac0

File tree

6 files changed

+401
-78
lines changed

6 files changed

+401
-78
lines changed

README.md

Lines changed: 44 additions & 76 deletions
Original file line numberDiff line numberDiff line change
@@ -1,35 +1,28 @@
11
# clj-libssh2
22

3-
![](https://clojars.org/clj-libssh2/latest-version.svg)
4-
5-
A Clojure wrapper around [libssh2](http://www.libssh2.org/). There are three
6-
parts to this library:
3+
A Clojure library for interacting with SSH servers using
4+
[libssh2](http://www.libssh2.org/) under the hood. There are three parts to
5+
this library:
76

87
1. A small API for doing most common SSH and SCP operations. You should use
9-
this for all new code using this library.
8+
this for all new code using this library. Examples of usage can be found in
9+
[doc/Primary-API.md](https://github.com/conormcd/clj-libssh2/blob/master/doc/Primary-API.md).
1010
2. A [JNA](https://github.com/Chouser/clojure-jna) wrap of all of the
1111
functions and constants in the public API of libssh2. You should use this
12-
if you need to do something unusual. Please file an issue or PR with
12+
if you need to do something unusual. Please [file an
13+
issue](https://github.com/conormcd/clj-libssh2/issues) or pull request with
1314
details of what you end up using this for, so that I can expand the main
14-
API.
15+
API. Some notes on this API can be found in
16+
[doc/libssh2.md](https://github.com/conormcd/clj-libssh2/blob/master/doc/libssh2.md).
1517
3. A series of convenience functions designed to make this library a suitable
1618
replacement for [clj-ssh](https://github.com/hugoduncan/clj-ssh). You
1719
should use this if you're transitioning code from `clj-ssh` to this
1820
library.
1921

20-
Documentation for the latest release should always be available at:
21-
http://conormcd.github.io/clj-libssh2/
22-
23-
## clj-libssh2 API
24-
25-
The primary public API for this library is the following set of functions:
22+
Function by function documentation for the latest release should always be
23+
available at: http://conormcd.github.io/clj-libssh2/
2624

27-
- `clj-libssh2.ssh/exec` - Execute a command on the remote host.
28-
- `clj-libssh2.ssh/with-session` - A convenience macro for managing sessions.
29-
30-
### Examples
31-
32-
#### Run a command and get the output.
25+
## Quick Start
3326

3427
```clojure
3528
user=> (require '[clj-libssh2.ssh :as ssh])
@@ -39,70 +32,45 @@ user=> (ssh/exec {:hostname "127.0.0.1"} "uptime")
3932
:err "", :exit 0, :signal {:exit-signal nil, :err-msg nil, :lang-tag nil}}
4033
```
4134

42-
#### Run multiple commands on the same session
35+
See
36+
[doc/Primary-API.md](https://github.com/conormcd/clj-libssh2/blob/master/doc/Primary-API.md)
37+
for more examples.
4338

44-
```clojure
45-
user=> (require '[clj-libssh2.ssh :as ssh])
46-
nil
47-
user=> (ssh/with-session session {:hostname "127.0.0.1"}
48-
#_=> (print (:out (ssh/exec session "uptime")))
49-
#_=> (print (:out (ssh/exec session "date"))))
50-
18:44 up 155 days, 19:07, 4 users, load averages: 2.17 1.93 1.75
51-
Sun 17 Jan 2016 18:44:03 GMT
52-
nil
53-
```
39+
## Release information
5440

55-
## libssh2 API
41+
Releases are done automatically via
42+
[CircleCI](https://circleci.com/gh/conormcd/clj-libssh2). Release builds can
43+
be found on [Clojars](https://clojars.org/clj-libssh2) and on
44+
[GitHub](https://github.com/conormcd/clj-libssh2/releases). Every release tags
45+
this repository with the version number as well, so commands like `git log
46+
0.1.69..0.1.72` and `git diff 0.1.69..0.1.72` should be usable to find out
47+
what's happened between releases.
5648

57-
The namespaces are arranged as follows:
49+
The latest release is:
5850

59-
- `clj-libssh2.libssh2`
60-
- All constant definitions. Constants that started with `LIBSSH2_` have had
61-
that prefix removed.
62-
- `libssh2_banner_set`
63-
- `libssh2_base64_decode`
64-
- `libssh2_exit`
65-
- `libssh2_free`
66-
- `libssh2_hostkey_hash`
67-
- `libssh2_init`
68-
- `libssh2_poll`
69-
- `libssh2_poll_channel_read`
70-
- `libssh2_trace`
71-
- `libssh2_trace_sethandler`
72-
- `libssh2_version`
73-
- `clj-libssh2.libssh2.agent` - All functions named `libssh2_agent_*`
74-
- `clj-libssh2.libssh2.channel` - All functions named `libssh2_channel_*`
75-
- `clj-libssh2.libssh2.keepalive` - All functions named `libssh2_keepalive_*`
76-
- `clj-libssh2.libssh2.knownhost` - All functions named `libssh2_knownhost_*`
77-
- `clj-libssh2.libssh2.scp` - All functions named `libssh2_scp_*`
78-
- `clj-libssh2.libssh2.session` - All functions named `libssh2_session_*`
79-
- `clj-libssh2.libssh2.userauth` - All functions named `libssh2_userauth_*`
51+
![](https://clojars.org/clj-libssh2/latest-version.svg)
8052

81-
## clj-ssh API
53+
Version numbers are structured as follows: MAJOR.MINOR.BUILD-NUMBER. The
54+
first, major version number will only be incremented for breaking changes to
55+
the primary public API of this library. The second, minor number will be
56+
incremented if either there's a backwards-incompatible change in other APIs
57+
exposed by this library OR if the bundled version of libssh2 changes. The last
58+
portion is the build number from CircleCI. Only green builds on the `master`
59+
branch trigger a release so these numbers will be non-sequential and will not
60+
reset to zero when the major/minor portions are incremented.
8261

83-
TODO. :)
62+
N.B. All versions before 0.2.x should be considered early development and
63+
should not be used in production. APIs may be added/changed/removed without
64+
warning.
8465

8566
## License
8667

87-
Copyright (c) 2015-2016, Conor McDermottroe
88-
All rights reserved.
89-
90-
Redistribution and use in source and binary forms, with or without
91-
modification, are permitted provided that the following conditions are met:
92-
93-
1. Redistributions of source code must retain the above copyright notice, this
94-
list of conditions and the following disclaimer.
95-
2. Redistributions in binary form must reproduce the above copyright notice,
96-
this list of conditions and the following disclaimer in the documentation
97-
and/or other materials provided with the distribution.
68+
The majority of this library is released under [a two clause BSD-style
69+
license](https://github.com/conormcd/clj-libssh2/blob/master/LICENSE). The
70+
only exceptions to this are the bundled libraries which have their own
71+
licenses:
9872

99-
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
100-
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
101-
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
102-
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
103-
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
104-
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
105-
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
106-
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
107-
OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
108-
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
73+
- libsimplesocket - This is distributed under its own [two clause BSD-style
74+
license](https://github.com/conormcd/clj-libssh2/blob/master/resources/linux-x86-64/libsimplesocket.so.LICENSE)
75+
- libssh2 - This is distributed under its own [three clause BSD-style
76+
license](https://github.com/conormcd/clj-libssh2/blob/master/resources/linux-x86-64/libssh2.so.COPYING)

doc/Primary-API.md

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
# The main clj-libssh2 API
2+
3+
The primary public API for this library is the following set of functions:
4+
5+
- `clj-libssh2.ssh/exec` - Execute a command on the remote host.
6+
- `clj-libssh2.ssh/with-session` - A convenience macro for managing sessions.
7+
8+
If there are any breaking changes to the above-named functions after version
9+
0.2.x of this library the major version number will be incremented.
10+
11+
## Examples
12+
13+
### Run a command and get the output.
14+
15+
```clojure
16+
user=> (require '[clj-libssh2.ssh :as ssh])
17+
nil
18+
user=> (ssh/exec {:hostname "127.0.0.1"} "uptime")
19+
{:out "18:40 up 155 days, 19:04, 4 users, load averages: 2.45 1.76 1.66\n",
20+
:err "", :exit 0, :signal {:exit-signal nil, :err-msg nil, :lang-tag nil}}
21+
```
22+
23+
### Run multiple commands on the same session
24+
25+
```clojure
26+
user=> (require '[clj-libssh2.ssh :as ssh])
27+
nil
28+
user=> (ssh/with-session session {:hostname "127.0.0.1"}
29+
#_=> (print (:out (ssh/exec session "uptime")))
30+
#_=> (print (:out (ssh/exec session "date"))))
31+
18:44 up 155 days, 19:07, 4 users, load averages: 2.17 1.93 1.75
32+
Sun 17 Jan 2016 18:44:03 GMT
33+
nil
34+
```
35+
36+
### Pipe input to a process on the remote machine
37+
38+
```clojure
39+
user=> (require '[clj-libssh2.ssh :as ssh])
40+
nil
41+
user=> (ssh/exec {:hostname "127.0.0.1"}
42+
#_=> "while read -t 1 s; do echo s; done"
43+
#_=> :in "foo\nbar\n")
44+
{:out "foo\nbar\n", :err "", :exit 0, :signal {:exit-signal nil, :err-msg nil,
45+
:lang-tag nil}}
46+
```

doc/clj-libssh.md

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
# clj-ssh Compatibility API
2+
3+
TODO. :)

0 commit comments

Comments
 (0)