feedback: experiences with libssh

[Simon <simonhf@xxxxxxxxx>]

Last week I spent a day and half spiking on compiling and using
libssh. In the end I decided not to use it. Although I had success at
modifying and compiling the Linux-only samplesshd on Windows, the
learning curve seemed a little bit too steep for my purposes. As a
developer with over 30 years experience then there's a bunch of libssh
things which didn't happen intuitively during my experience and this
e-mail is me trying to give constructive feedback in an unbiased way
with good intentions:

Regarding the cmake outputs: If a project is called lib-something then
I would expect a library to result when making it. However, with
libssh then you only get example applications. Example applications
are good but I would expect them to use the library.

Regarding the example applications: Definitely useful but not
described well what each one does. Rather than having many example
applications then I would prefer a single example which mimics much of
the command line behaviour of the openssh client and server. This
would be much easier for folks like me to understand with even no
documentation because everybody knows how to use openssh.

Regarding cross compilation on Linux and Windows: Having hung around
on the IRC #libssh channel then I was unable to find libssh developers
who felt at home on Windows. I feel just as at home on Linux or
Windows and it was obvious to me that Windows was a definite 'second
class citizen' in the libssh world. I think these days it's possible
to find ways to do things nearly exactly the same way on Linux and
Windows and there shouldn't be the necessity for dual sets of
instructions compiling and testing etc. I would welcome Windows
getting bumped up to being a 'first class citizen' in terms of
compilation & instructions, testing, and the range of example
functionality which compiles. So everything that works on Linux work
on Windows unless there is a very good reason. Apart from fork() and
some kernel allocation differences then Linux and Windows are not that
different for scripting things up. Some Linux developers find it
difficult to live without the beloved shell. That's fine. But please
consider that a lot of the shell commands which are missing by default
on Windows can be replaced by cross platform scripting languages like
Perl which actually give you more functionality and flexibility than
the usual shell commands and work on Linux and Windows. For example,
using Perl you can do cross-platform wget, grep, tee, tar, etc. So
instead of having .sh files on Linux and .bat/.cmd files on Windows
which duplicate functionality then you can have a single set of
cross-platform .pl files. I'm only talking about Perl because that's
how I do it. But I wouldn't be surprised if there are other scripting
languages offering the same level of cross-platform support and
ability to do script-file-less-one-liners.

Regarding cmake build folders: One of the most annoying things about
libssh for Windows is cmake. I easily wasted half a day trying to
pamper it into building. It's non intuitive to have build folders
which 'link back' to the source files. I don't think libssh developers
should expect new libssh users to already be using cmake or find its
paradigm intuitive. Therefore, I would suggest trying to explain this
a bit better in the compilation instructions and also try to make the
process more the same on Linux and Windows.

Regarding libssh dependencies: There seems to be some friction between
the idea that on Linux then dependencies will likely be available and
just need to be checked for and on Windows there will likely be no
dependencies available and therefore where to get them and install
them? I have also seen rare installations where multiple products on
Windows install there own slightly different versions of openssl DLLs
in the Windows directory which ends up partially breaking one of the
products. My suggestion: Things like openssl and zlib don't change
very often. I would suggest importing them into the libssh code-base.
Then on Linux the default would be to not compile and link them. And
on Windows the default would be to compile and link them. That's way a
new libssh Windows user only have to download the latest libssh and
cmake and start compiling... no dependencies necessary because they
are included.

Regarding automated testing: Again, I would expect this to just work
at least as easily as getting regular compilation to work. But the
reality I found is that it uses extra dependencies on Windows with
special install instructions which don't appear to be captured
anywhere. After a few hours I gave up trying to get this to work on
Windows after I learned that the bulk of the tests don't run on
Windows anyway. I couldn't figure out how to install cmockery on
Windows the way that libssh wants it. And I also couldn't figure out
how to configure cmake to run the unit tests even though there is some
documentation available for this on the libssh wiki. It seems that
almost nobody is running unit tests on Windows with libssh. One of the
libssh developers on IRC didn't want to take the time to explain to me
how to set up the unit test environment unless I was willing to become
a libssh contributor. This statement seems to be a sure sign that
automated testing with libssh is too complicated to get going. But I
think it great that there are tests at all which is unusal for open
source projects. I would love to see automated coverage testing one
day too.

Regarding logging: I thought it was really good that there is logging.
I'd prefer to see even more and having the logs more 'groomed' and
telling a run-time story.

I know you guys have limited time and probably want to do some of
these points but just don't have the time. I hope that this feedback
is greeted with the same positive spirit that it has been written.

--
Simon