2016-09-12 04:09:41 +08:00
|
|
|
This folder contains the input file (``tox.in.h``) that has to be used to generate the ``tox.h`` api with: https://github.com/TokTok/apidsl
|
2015-04-26 08:39:13 +08:00
|
|
|
|
2015-06-20 08:22:46 +08:00
|
|
|
# Minimal requirements
|
2015-04-26 08:39:13 +08:00
|
|
|
|
2015-06-20 08:22:46 +08:00
|
|
|
There are some minimal requirements to contribute to ``tox.h``:
|
2015-06-21 01:54:37 +08:00
|
|
|
* unix environment
|
2015-06-20 08:22:46 +08:00
|
|
|
* ``astyle`` ``>=2.03``
|
2016-09-12 04:09:41 +08:00
|
|
|
* [``apidsl``](https://github.com/TokTok/apidsl) (you can use provided service with curl instead)
|
2015-06-20 08:22:46 +08:00
|
|
|
|
|
|
|
|
## Quick way
|
|
|
|
|
|
|
|
|
|
If you want to do it quickly and you don't have time for anything other than copypasting commands, you should have ``curl`` installed.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
1. Make sure that you have ``curl`` and ``>=astyle-2.03`` installed
|
2016-09-21 17:51:58 +08:00
|
|
|
2. Modify [``tox.api.h``](/toxcore/tox.api.h)
|
2015-06-20 08:22:46 +08:00
|
|
|
3. Run command below ↓
|
|
|
|
|
|
|
|
|
|
Command to run from ``toxcore`` directory (quick way, involves using curl):
|
|
|
|
|
```bash
|
Make self_connection_status callback stateless.
**What are we doing?**
We are moving towards stateless callbacks. This means that when registering a
callback, you no longer pass a user data pointer. Instead, you pass a user data
pointer to tox_iterate. This pointer is threaded through the code, passed to
each callback. The callback can modify the data pointed at. An extra indirection
will be needed if the pointer itself can change.
**Why?**
Currently, callbacks are registered with a user data pointer. This means the
library has N pointers for N different callbacks. These pointers need to be
managed by the client code. Managing the lifetime of the pointee can be
difficult. In C++, it takes special effort to ensure that the lifetime of user
data extends at least beyond the lifetime of the Tox instance. For other
languages, the situation is much worse. Java and other garbage collected
languages may move objects in memory, so the pointers are not stable. Tox4j goes
through a lot of effort to make the Java/Scala user experience a pleasant one by
keeping a global array of Tox+userdata on the C++ side, and communicating via
protobufs. A Haskell FFI would have to do similarly complex tricks.
Stateless callbacks ensure that a user data pointer only needs to live during a
single function call. This means that the user code (or language runtime) can
move the data around at will, as long as it sets the new location in the
callback.
**How?**
We are doing this change one callback at a time. After each callback, we ensure
that everything still works as expected. This means the toxcore change will
require 15 Pull Requests.
2016-08-10 20:46:04 +08:00
|
|
|
# For tox.h:
|
|
|
|
|
curl -X POST --data-binary @- https://apidsl.herokuapp.com/apidsl \
|
2016-09-21 17:51:58 +08:00
|
|
|
< toxcore/tox.api.h \
|
Make self_connection_status callback stateless.
**What are we doing?**
We are moving towards stateless callbacks. This means that when registering a
callback, you no longer pass a user data pointer. Instead, you pass a user data
pointer to tox_iterate. This pointer is threaded through the code, passed to
each callback. The callback can modify the data pointed at. An extra indirection
will be needed if the pointer itself can change.
**Why?**
Currently, callbacks are registered with a user data pointer. This means the
library has N pointers for N different callbacks. These pointers need to be
managed by the client code. Managing the lifetime of the pointee can be
difficult. In C++, it takes special effort to ensure that the lifetime of user
data extends at least beyond the lifetime of the Tox instance. For other
languages, the situation is much worse. Java and other garbage collected
languages may move objects in memory, so the pointers are not stable. Tox4j goes
through a lot of effort to make the Java/Scala user experience a pleasant one by
keeping a global array of Tox+userdata on the C++ side, and communicating via
protobufs. A Haskell FFI would have to do similarly complex tricks.
Stateless callbacks ensure that a user data pointer only needs to live during a
single function call. This means that the user code (or language runtime) can
move the data around at will, as long as it sets the new location in the
callback.
**How?**
We are doing this change one callback at a time. After each callback, we ensure
that everything still works as expected. This means the toxcore change will
require 15 Pull Requests.
2016-08-10 20:46:04 +08:00
|
|
|
| astyle --options=other/astyle/astylerc \
|
|
|
|
|
> toxcore/tox.h
|
|
|
|
|
# For toxav.h:
|
|
|
|
|
curl -X POST --data-binary @- https://apidsl.herokuapp.com/apidsl \
|
2016-09-21 17:51:58 +08:00
|
|
|
< toxav/toxav.api.h \
|
Make self_connection_status callback stateless.
**What are we doing?**
We are moving towards stateless callbacks. This means that when registering a
callback, you no longer pass a user data pointer. Instead, you pass a user data
pointer to tox_iterate. This pointer is threaded through the code, passed to
each callback. The callback can modify the data pointed at. An extra indirection
will be needed if the pointer itself can change.
**Why?**
Currently, callbacks are registered with a user data pointer. This means the
library has N pointers for N different callbacks. These pointers need to be
managed by the client code. Managing the lifetime of the pointee can be
difficult. In C++, it takes special effort to ensure that the lifetime of user
data extends at least beyond the lifetime of the Tox instance. For other
languages, the situation is much worse. Java and other garbage collected
languages may move objects in memory, so the pointers are not stable. Tox4j goes
through a lot of effort to make the Java/Scala user experience a pleasant one by
keeping a global array of Tox+userdata on the C++ side, and communicating via
protobufs. A Haskell FFI would have to do similarly complex tricks.
Stateless callbacks ensure that a user data pointer only needs to live during a
single function call. This means that the user code (or language runtime) can
move the data around at will, as long as it sets the new location in the
callback.
**How?**
We are doing this change one callback at a time. After each callback, we ensure
that everything still works as expected. This means the toxcore change will
require 15 Pull Requests.
2016-08-10 20:46:04 +08:00
|
|
|
| astyle --options=other/astyle/astylerc \
|
|
|
|
|
> toxav/toxav.h
|
2015-06-20 08:22:46 +08:00
|
|
|
```
|
|
|
|
|
|
|
|
|
|
You may want to make sure with ``git diff`` that changes made in ``tox.h`` reflect changes in ``tox.in.h``.
|
|
|
|
|
|
|
|
|
|
And you're done.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
## Manually
|
|
|
|
|
|
|
|
|
|
If you prefer to have more control over what is happening, there are steps below:
|
|
|
|
|
|
2016-09-12 04:09:41 +08:00
|
|
|
1. Install [``apidsl``](https://github.com/TokTok/apidsl)
|
2015-06-20 08:22:46 +08:00
|
|
|
2. Install ``astyle``, version 2.03 or later.
|
2016-09-21 17:51:58 +08:00
|
|
|
3. Modify [``tox.api.h``](/toxcore/tox.api.h)
|
2015-06-20 08:22:46 +08:00
|
|
|
4. Use ``apidsl`` ``??``
|
|
|
|
|
5. Parse generated ``tox.h`` with astyle, minimal command for it would be:
|
|
|
|
|
```bash
|
Make self_connection_status callback stateless.
**What are we doing?**
We are moving towards stateless callbacks. This means that when registering a
callback, you no longer pass a user data pointer. Instead, you pass a user data
pointer to tox_iterate. This pointer is threaded through the code, passed to
each callback. The callback can modify the data pointed at. An extra indirection
will be needed if the pointer itself can change.
**Why?**
Currently, callbacks are registered with a user data pointer. This means the
library has N pointers for N different callbacks. These pointers need to be
managed by the client code. Managing the lifetime of the pointee can be
difficult. In C++, it takes special effort to ensure that the lifetime of user
data extends at least beyond the lifetime of the Tox instance. For other
languages, the situation is much worse. Java and other garbage collected
languages may move objects in memory, so the pointers are not stable. Tox4j goes
through a lot of effort to make the Java/Scala user experience a pleasant one by
keeping a global array of Tox+userdata on the C++ side, and communicating via
protobufs. A Haskell FFI would have to do similarly complex tricks.
Stateless callbacks ensure that a user data pointer only needs to live during a
single function call. This means that the user code (or language runtime) can
move the data around at will, as long as it sets the new location in the
callback.
**How?**
We are doing this change one callback at a time. After each callback, we ensure
that everything still works as expected. This means the toxcore change will
require 15 Pull Requests.
2016-08-10 20:46:04 +08:00
|
|
|
astyle --options=other/astyle/astylerc toxcore/tox.h
|
2015-04-26 08:39:13 +08:00
|
|
|
```
|
|
|
|
|
|
2016-07-13 03:32:35 +08:00
|
|
|
**Always pass output from ``apidsl`` through astyle.**
|
