Improve sample bundle code

[Tristan Croll]

The sample bundle found at https://www.rbvi.ucsf.edu/chimerax/docs/devel/writing_bundles.html is a bit daunting to the beginner - in particular, the sample C++ code using the low-level Python C API. That side of Python is ugly as sin and personally I always find it very hard to follow even after a lot of experience. I also think the Makefile is out of date. If you want to get more third-party developers on board, I'd suggest expanding on it somewhat - e.g. providing a few different examples of how C++ code can be bound, adding some verbose documentation to cmd.py, etc..

I've made a start at a suggested approach: splitting the actual code defining the C++ function to be wrapped into its own header, _sample.h, which is then #included in different _sample_xxx.cpp files demonstrating different wrapping approaches. At the moment I've just added a PyBind11 example, but it'd probably be a good idea to add an example using ctypes, and (maybe?) SWIG. Give people as many options as possible, so they can use whichever they're most comfortable with.

Can't do more for now - about to jump on a flight to Australia (for the Lorne conference).

[Tristan Croll]

Modified sample bundle

[pett]

Yes, the example bundle in "Building and Distributing Bundles" needs a lot of revision. I have revised the bundle examples in the "ChimeraX Developer Tutorial" to reflect the migration away from DataFormat, etc., tags, but had missed the one in "Building and Distributing Bundles" because the bad tags weren't referenced in any .rst files. This is on top of all the other deficiencies you pointed out.

Will probably happen sooner rather than later because we really don't want the bad tags in there, but still I have a few other things that need doing first. Nonetheless, will probably happen in the next month.

[pett]

Hi Tristan,

Thanks for this -- it's really excellent and it must have been a lot of work. I have incorporated it as is, with minor enhancements to update it to the current open/save paradigm, and committed it. It should show up tomorrow. Hopefully it will help a lot of folks.

--Eric

[Tristan Croll]

Glad you like it. :)

I'll have to take a look - I started in on updating Clipper to use the 
new open/save, but got sidetracked by other things. Having a clean 
minimal example to work from should make things much easier.

On 2020-05-20 22:54, ChimeraX wrote:

[Tristan Croll]

I see the online documentation is updated, but the zip file it links to 
is still the old version. One suggestion for the documentation: under 
the "Building and Testing Bundles" heading, it should probably be noted 
that in Windows you need to run ChimeraX-console.exe in order for the 
--nogui switch to work. Same for --debug (otherwise the debugging info 
just disappears into the ether).

On 2020-05-20 22:54, ChimeraX wrote:

[pett]

Conrad and/or Greg:

The CGI script that generates the sample-code zip file (URL: ​https://www.cgl.ucsf.edu/chimerax/cgi-bin/bundle_sample.zip ; file: plato:/usr/local/projects/chimerax/www/preview/cgi-bin/bundle_sample.zip), uses the "develop" branch from git, and therefore has not picked up the changes to the sample code. Should we temporarily change that to "release/v1.0"? Is there a better solution?

--Eric

[pett]

I made the sample-code Makefile use the console executable, which is what we already do in our own Makefile.bundle. I also updated the "Building and Testing Bundles" docs to discuss it.

[Tristan Croll]

Thanks. I don’t typically use Cygwin or MinGW, so the Makefile approach doesn’t work for me in Windows (unless I’m missing something). Instead I use a simple batch file to call ChimeraX. I’m sure there will be others who prefer to do the same.

 
 

 

[pett]

The ticket to fetch the correct sample code is #3332