How to get started with development?

[Huy-Ngo]

The current README appears to be incomplete and it's hard for starters to know:

• What the project is about
• How to use it

[McSinyx]

I'm finalizing my local work at the moment (usually when I work alone I only write the meta doc when I feel the project is ready) but I'll keep in mind giving at least the minimal details for you guys to begin working on it.

[Huy-Ngo]

As of now, both I and @9a24f0 couldn't understand the workflow and models and blah blah of this project. Can you focus on the documentation first, so that we can cooperate more easily? More specifically, something like "Getting started" section of a lib/language.

In addition, I believe that some offline discussion could be helpful too.

[McSinyx]

I don't believe that belongs to documentation (what in my mind means user reference, which is available online here). Thus I'll explain what to be done here and rename this issue accordingly.

So alure is a C++ library, whose functionality is exposed in it's header (alure/include/alure2.h). Our goal is to make that set of functionality (see #5) available on Python using Cython as a bridge. What Cython does is that it translate Cython sauces to a Python extension (a fancy way to call a C/C++ module that can be complied to a Python module). This Python extension can be used in both Python and C/C++ (with Python.h included of course), but the later is not within our interest.

A good tutorial for doing this is available at Cython's doc. TLDR:

1. Wrap the C++ class to a Cython cppclass in a pxd file, which one can think of as a Cython header (which are not exactly the same, but in our case it does not matter that much). The work is pretty much literal translation, e.g. int fooFunction(bar_type&); in C++ is converted to int foo_function 'fooFunction'(bar_type&) except +. Changing camelCase to snake_case is purely aesthetic, as except + is to turn C++ exception to Python one--this is not needed of the C++ function/method is noexcept.
2. Wrap the Cython cppclass in a Cython extension class, since it's obvious that Python cannot use C++ objects. The Cython cdef class may have C/C++ members, while being visible at Python level, thus we use the (sorta) pimpl idiom: store the C++ object as a attribute (e.g. impl) and write method wrappers that call the C++ method, e.g. def foo(self): return self.impl.foo(). This is done in palace.pyx.

The main issues are with how to handle cases when it is not that straight forward (not every C++ data type can be automatically converted to Python and vice-versa, so we need to do some extra wrapping, see the beginning of palace.pyx.

To compile, run ./setup.py install --user, which compile palace.pyx to palace.cpp, which is then compile to a binary module (i.e. *.so or *.dll depending of platform), so you can use it in Python. For sample Python usage, see the examples directory.

In addition, I believe that some offline discussion could be helpful too.

Sure that'd help. The matter is when (take a look at our study schedule lmao). Maybe this friday morning?

[McSinyx]

Since you both got started, I'm closing this.