improve docs, make clear different APIs and static/dynamic
This commit is contained in:
electronstudio
parent
47c4d0d1b4
commit
9e17046408
49 changed files with 5467 additions and 17850 deletions
|
|
@ -59,8 +59,7 @@ Build and install Raylib from the raylib-c directory.
|
|||
|
||||
To update the dynamic libs, download the official release,
|
||||
e.g. https://github.com/raysan5/raylib/releases/download/3.7.0/raylib-3.7.0_win64_msvc16.zip
|
||||
and extract ``raylib.dll`` into ``raylib/dynamic``. Delete the files for
|
||||
other platforms, unless you want them in your distribution.
|
||||
and extract ``raylib.dll`` into ``dynamic/raylib``.
|
||||
|
||||
To build a binary wheel distribution:
|
||||
|
||||
|
|
@ -111,7 +110,7 @@ Build and install Raylib from the raylib-c directory.
|
|||
sudo make install
|
||||
|
||||
.. note:: Optional: Build the Raylib shared libs, if you plan to use
|
||||
``raylib.dynamic`` binding.
|
||||
``raylib_dynamic`` binding.
|
||||
|
||||
::
|
||||
|
||||
|
|
@ -148,8 +147,8 @@ Build
|
|||
|
||||
::
|
||||
|
||||
rm raylib/dynamic/*.so*
|
||||
cp -P /usr/local/lib/libraylib.so* raylib/dynamic/
|
||||
rm dynamic/raylib/*.so*
|
||||
cp -P /usr/local/lib/libraylib.so* dynamic/raylib/
|
||||
|
||||
To build a binary wheel distribution:
|
||||
|
||||
|
|
@ -158,12 +157,6 @@ To build a binary wheel distribution:
|
|||
pip3 install wheel
|
||||
python3 setup.py bdist_wheel
|
||||
|
||||
Alternatively, if you don’t want the static binaries and just want to
|
||||
use DLLs with raylib.dynamic:
|
||||
|
||||
::
|
||||
|
||||
python3 setup_dynamic.py bdist_wheel
|
||||
|
||||
Then install it:
|
||||
|
||||
|
|
@ -183,8 +176,8 @@ To build a complete set of libs for Python 3.6, 3.7, 3.8 and 3.9:
|
|||
``./raylib/static/build_multi_linux.sh`` )
|
||||
|
||||
.. TODO::
|
||||
move the dynamic libs into a separate package rather than include
|
||||
them with every one.
|
||||
Separate the instructions for preparing the dynamic module
|
||||
from the instructions for building the static module!
|
||||
|
||||
|
||||
|
||||
|
|
@ -200,12 +193,13 @@ Raylib.
|
|||
|
||||
git clone --recurse-submodules https://github.com/electronstudio/raylib-python-cffi
|
||||
|
||||
Build Raylib from the raylib-c directory.
|
||||
Build and install Raylib from the raylib-c directory.
|
||||
|
||||
::
|
||||
|
||||
cd raylib-python-cffi/raylib-c/src
|
||||
make
|
||||
sudo cp libraylib.a /usr/local/lib/libraylib.a
|
||||
cd ../..
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -14,32 +14,39 @@ statically link and use in non-free / proprietary / commercial projects!
|
|||
|
||||
We distribute a statically linked binary Raylib wheel:
|
||||
|
||||
pip3 install raylib
|
||||
python3 -m pip install raylib
|
||||
|
||||
Problems may be caused by out of date pip:
|
||||
|
||||
python3 -m pip install --upgrade pip
|
||||
|
||||
Some platforms that _should_ be available: Windows 10 x64, MacOS 10.15 x64, Linux Ubuntu1804 x64.
|
||||
|
||||
If yours isn't available then pip will attempt to build from source, so you will need to have Raylib development libs installed.
|
||||
If yours isn't available then pip will attempt to build from source, in which case you will need to have Raylib development libs installed, e.g.
|
||||
using homebrew, apt, etc.
|
||||
|
||||
[If it doesn't work, build from source](BUILDING.md)
|
||||
|
||||
There is now a separate dynamic version of this binding:
|
||||
|
||||
python3 -m pip install raylib_dynamic
|
||||
|
||||
[Read this before using raylib_dynamic](https://electronstudio.github.io/raylib-python-cffi/dynamic.html)
|
||||
|
||||
|
||||
# How to use
|
||||
|
||||
There are three different ways of using this binding. You only need to pick one method, but you
|
||||
There are two different ways of using this binding. You only need to pick one method, but you
|
||||
can combine two methods in one program if you want to.
|
||||
|
||||
### If you are familiar with C coding and the Raylib C library and you want to use an exact copy of the C API
|
||||
|
||||
Use [raylib.static](https://electronstudio.github.io/raylib-python-cffi/raylib.html).
|
||||
Use [the C API](https://electronstudio.github.io/raylib-python-cffi/raylib.html).
|
||||
|
||||
### If you prefer a slightly more Pythonistic API and don't mind it might be slightly slower
|
||||
|
||||
Use [raylib.pyray](https://electronstudio.github.io/raylib-python-cffi/pyray.html).
|
||||
Use [the Python API](https://electronstudio.github.io/raylib-python-cffi/pyray.html).
|
||||
|
||||
### If you insist on dynamic bindings and don't care that they are slower and less safe
|
||||
|
||||
Use [raylib.dynamic](https://electronstudio.github.io/raylib-python-cffi/dynamic.html).
|
||||
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -1,28 +1,38 @@
|
|||
raylib.dynamic
|
||||
==============
|
||||
|
||||
CFFI ABI dynamic bindings exist in order to avoid the need to compile a C extension module.
|
||||
|
||||
See https://github.com/electronstudio/raylib-python-cffi/blob/master/test_static.py for how to use.
|
||||
|
||||
Currently the github version may include bundled DLLs in ``raylib/dynamic`` but the pypi version requires a system installed Raylib.
|
||||
You can put your own DLLs in ``raylib/dynamic`` if you prefer.
|
||||
|
||||
If your system already has the Raylib library installed, you can set the environment variable ``USE_EXTERNAL_RAYLIB`` and it will
|
||||
always be used instead of the bundled DLLs.
|
||||
|
||||
If you want to build your own wheel with just raylib.dynamic and not even attempt to compile the static libraries,
|
||||
the command is::
|
||||
|
||||
python3 setup_dynamic.py bdist_wheel
|
||||
Dynamic Bindings
|
||||
================
|
||||
|
||||
CFFI ABI dynamic bindings avoid the need to compile a C extension module. They now been moved to a separate module::
|
||||
|
||||
python3 -m pip install raylib_dynamic
|
||||
|
||||
.. warning::
|
||||
|
||||
There have been some weird failures with dynamic bindings and ctypes bindings before and often the
|
||||
failures are silent
|
||||
so you dont even know. Also the static bindings should be faster. Therefore I personally recommend the static ones.
|
||||
But the dynamic bindings have the big advantage that you don't need to compile anything to install. You just need a Raylib DLL.
|
||||
so you don't even know something has gone wrong and you don't get proper stacktraces. Also the static bindings are faster.
|
||||
Therefore I personally recommend the static ones.
|
||||
But the dynamic bindings have the advantage that you don't need to compile anything to install. You just need a Raylib DLL.
|
||||
|
||||
API is the same as raylib.static.
|
||||
API is exactly the same as the static one documented here. (Therefore you can't have both modules installed at once.) The only difference is you can't do::
|
||||
|
||||
from raylib import *
|
||||
|
||||
Instead you have to do::
|
||||
|
||||
from raylib import rl
|
||||
|
||||
Then you access the functions with ``rl.`` prefix. See
|
||||
|
||||
See https://github.com/electronstudio/raylib-python-cffi/blob/master/dynamic/test_dynamic.py for an example.
|
||||
|
||||
If you use the ``rl.`` prefix then code will work on both static and dynamic bindings.
|
||||
|
||||
.. warning::
|
||||
|
||||
If you access functions via ``raylib.pyray`` then there is no difference at all, but be warned this hasn't been tested.
|
||||
|
||||
|
||||
.. important::
|
||||
|
||||
If your system already has the Raylib library installed, you can set the environment variable ``USE_EXTERNAL_RAYLIB`` and it will
|
||||
always be used instead of the bundled DLLs.
|
||||
|
|
|
|||
|
|
@ -1,5 +1,5 @@
|
|||
raylib.pyray
|
||||
============
|
||||
Python API
|
||||
==============
|
||||
|
||||
.. comment::
|
||||
|
||||
|
|
@ -10,7 +10,7 @@ raylib.pyray
|
|||
autoapi/raylib/pyray/index
|
||||
|
||||
|
||||
This is a wrapper around the static bindings.
|
||||
This is a wrapper around the C API with some syntactic sugar.
|
||||
|
||||
The API is *still the same as Raylib*, so you should still reply on `the official Raylib docs <https://www.raylib.com/cheatsheet/cheatsheet.html>`_, except:
|
||||
|
||||
|
|
|
|||
|
|
@ -1,14 +1,14 @@
|
|||
raylib.static
|
||||
C API
|
||||
=============
|
||||
|
||||
The goal of raylib.static is make usage as similar to the original C as CFFI will allow. The `example programs <https://github.com/electronstudio/raylib-python-cffi/tree/master/examples>`_
|
||||
The goal of the C API is make usage as similar to the original C as CFFI will allow. The `example programs <https://github.com/electronstudio/raylib-python-cffi/tree/master/examples>`_
|
||||
are very, very similar to the C originals.
|
||||
|
||||
Example program:
|
||||
|
||||
.. code-block::
|
||||
|
||||
from raylib.static import *
|
||||
from raylib import *
|
||||
|
||||
InitWindow(800, 450, b"Hello Raylib")
|
||||
SetTargetFPS(60)
|
||||
|
|
@ -27,18 +27,30 @@ Example program:
|
|||
EndDrawing()
|
||||
CloseWindow()
|
||||
|
||||
If you want to be more portable you can prefix the functions like this:
|
||||
|
||||
.. code-block::
|
||||
|
||||
from raylib import ffi, rl, colors
|
||||
|
||||
rl.InitWindow(800, 450, b"Hello Raylib")
|
||||
rl.SetTargetFPS(60)
|
||||
|
||||
...
|
||||
|
||||
|
||||
See also https://github.com/electronstudio/raylib-python-cffi/blob/master/test_static.py
|
||||
|
||||
Also useful to read whenever you need to convert stuff between C and Python: https://cffi.readthedocs.io
|
||||
.. note:: Whenever you need to convert stuff between C and Python see https://cffi.readthedocs.io
|
||||
|
||||
Your **primary reference** should always be `the official Raylib docs <https://www.raylib.com/cheatsheet/cheatsheet.html>`_
|
||||
.. important:: Your **primary reference** should always be `the official Raylib docs <https://www.raylib.com/cheatsheet/cheatsheet.html>`_
|
||||
|
||||
However, here is a list of available functions:
|
||||
|
||||
Functions API reference
|
||||
-----------------------
|
||||
|
||||
.. autoapimodule:: raylib.static
|
||||
.. autoapimodule:: raylib
|
||||
:members:
|
||||
:undoc-members:
|
||||
|
||||
|
|
|
|||
Reference in a new issue