<commit_before>Building libmapper
==================

This file documents the build process for libmapper for various
operating systems, and will be updated as the libmapper core project
progresses.

Linux and MacOS
--------------

### Dependencies

libmapper depends on version 0.30 of liblo or later.
Please consult the [LibLo project page][liblo] for details.

[liblo]: http://liblo.sourceforge.net

The GNU configure step detects liblo using the "pkg-config" program.
This is usually already installed in Linux systems, but on MacOS, we
recommend installing it via [MacPorts][ports] or [HomeBrew][brew]. In
the future libmapper packages for MacPorts and HomeBrew will be
directly provided, but this is not yet the case.

[ports]: http://www.macports.org
[brew]: http://mxcl.github.com/homebrew

You may wish to manually check that the correct version of liblo is
detected, by running,

    pkg-config --libs --cflags liblo

If the path to liblo is not correct, please set up the
`PKG_CONFIG_PATH` environment variable appropriately and try again.

libmapper also has optional dependencies on the Java SDK as well as
SWIG and Doxygen, for Java and Python bindings, and documentation,
respectively.  The Java SDK may be installed according to your
standard operating system procedure, and you can check if it is
already installed by running,

    javac -version

These should print the installed version numbers of these programs if
correctly configured.  You may install `swig` and `doxygen` packages
using your preferred package manager.

The `examples` folder also contains an audio example, which binds to
`libasound` on Linux, and CoreAudio on MacOS.  On Ubuntu, you may
wish to installed `libasound-dev` package, or the corresponding
package on other Linux distributions.

### Configuring

If you have extracted libmapper from a release tarball, run,

    ./configure
    
to configure the software with default options.  If you are using
libmapper from a repository, you will need to run,

    ./autogen.sh
    
which will create the `configure` script and run it for you.  You can
optionally specify an install location with,

    ./configure --prefix=<location>

It is recommended to either use `/usr/local/` or a directory in your
home directory such as `$HOME/.local`.  Users of HomeBrew on MacOS
should always use `/usr/local`.

If you will be hacking on libmapper or wish to have verbose output
while it is running, we recommended enabling debug mode:

    ./configure --enable-debug

Additionally, Java and Python bindings, and audio examples, may be
disabled with options `--disable-jni`, `--disable-swig`, and
`--disable-audio` respectively.

After `configure` runs successfully, the configuration options will be
printed for your confirmation.  If anything unexpected occurs, be sure
to check `config.log` for information about what failed.

### Building

Once the build is configured, build it with,

    make

Should any errors occur, please inform the [libmapper mailing list][list].

To verify that the library runs without errors, you may run the main
test program, available in the test directory:

    ./test/test -t

This program creates devices and signals and tests sending data between them using maps. The `-t` flag will cause the test program to automatically terminate after sending 200 messages, so omit it if you want to keep the test running indefinately.

Note that the programs in the test directory are _not_ examples of
library usage, as they additionally test some internal functions in
the library.  Please see the `examples` directory for examples of how
to use the library.

### Installing

The software may be installed with,

    sudo make install

This should place headers in `<prefix>/include/mapper`, the library
in `<prefix>/lib`, Python bindings in
`<prefix>/lib/pythonXX/site-packages` (where XX is your Python
version), and a `pkg-config` information file in
`<prefix>/lib/pkgconfig`.

Once installation is successful, you can check that the library is
found by `pkg-config`:

    pkg-config --libs --cflags libmapper

Note that the Java bindings are not installed, as there is no standard
location in which to put them.  However, they can be copied to
wherever is convenient for the classpath and java.library.path in your
project.  Instructions specific to Processing.org can be found in a
dedicated section below.

### Testing

As mentioned, you can test libmapper by running the test program,

    test/test

This should create two devices, link them, connect their signals, and
update a value continuously.  The other device should report that it
received the value.

You may wish to observe the multicast "admin" traffic, which can be
done by watching the multicast UDP port for OSC data using liblo's
`oscdump` utility:

    oscdump 7570 172.16.31.10

You can also use a libmapper GUI, such as [webmapper][webmapper], to
see that the devices and signals are discovered correctly.  You can
use the GUI to modify the connection properties, and observe that the
received values are changed.

[webmapper]: https://github.com/libmapper/webmapper

You should also test the Python and Java bindings if you plan to use
them.  Some other programs may depend on them – for example webmapper uses the Python bindings.

To test that the Python module is working, it is generally enough to
run the following command,

    python -m mapper

This will import the `mapper` module, which will fail if either
`mapper.py` or the native portion of the binding are not found.  You
may need to adjust your `PYTHONPATH` variable to ensure these can be
found.

You can test running programs by `cd`'ing to the `swig` folder and
running,

    cd swig
    python test.py

or,

    python tkgui.py

for a GUI example which brings up a single, mappable slider.  Running
multiple copies of `tkgui.py`, you can try mapping one to another to
make sure libmapper is functional.

Similarly, the Java bindings may be tested by `cd`'ing to the `jni`
folder and running `test` with the correct class and library paths:

    cd jni
    java -cp libmapper.jar -Djava.library.path=.libs test

Cross-compiling for Windows under Linux
---------------------------------------

Since libmapper was developed on Unix-like systems (Linux and Apple's
MacOS), building libmapper uses GNU command-line tools.  However, it is
possible to build it for the Microsoft Windows operating system using
the MingW cross-compiler under Linux, or by using MingW from Windows.
<commit_msg>native windows build instructions<commit_after>Building libmapper
==================

This file documents the build process for libmapper for various
operating systems, and will be updated as the libmapper core project
progresses. Supports Linux, MacOS and Windows platforms.

Linux and MacOS
--------------

### Dependencies

libmapper depends on version 0.30 of liblo or later.
Please consult the [LibLo project page][liblo] for details.

[liblo]: http://liblo.sourceforge.net

The GNU configure step detects liblo using the "pkg-config" program.
This is usually already installed in Linux systems, but on MacOS, we
recommend installing it via [MacPorts][ports] or [HomeBrew][brew]. In
the future libmapper packages for MacPorts and HomeBrew will be
directly provided, but this is not yet the case.

[ports]: http://www.macports.org
[brew]: http://mxcl.github.com/homebrew

You may wish to manually check that the correct version of liblo is
detected, by running,

    pkg-config --libs --cflags liblo

If the path to liblo is not correct, please set up the
`PKG_CONFIG_PATH` environment variable appropriately and try again.

libmapper also has optional dependencies on the Java SDK as well as
SWIG and Doxygen, for Java and Python bindings, and documentation,
respectively.  The Java SDK may be installed according to your
standard operating system procedure, and you can check if it is
already installed by running,

    javac -version

These should print the installed version numbers of these programs if
correctly configured.  You may install `swig` and `doxygen` packages
using your preferred package manager.

The `examples` folder also contains an audio example, which binds to
`libasound` on Linux, and CoreAudio on MacOS.  On Ubuntu, you may
wish to installed `libasound-dev` package, or the corresponding
package on other Linux distributions.

### Configuring

If you have extracted libmapper from a release tarball, run,

    ./configure
    
to configure the software with default options.  If you are using
libmapper from a repository, you will need to run,

    ./autogen.sh
    
which will create the `configure` script and run it for you.  You can
optionally specify an install location with,

    ./configure --prefix=<location>

It is recommended to either use `/usr/local/` or a directory in your
home directory such as `$HOME/.local`.  Users of HomeBrew on MacOS
should always use `/usr/local`.

If you will be hacking on libmapper or wish to have verbose output
while it is running, we recommended enabling debug mode:

    ./configure --enable-debug

Additionally, Java and Python bindings, and audio examples, may be
disabled with options `--disable-jni`, `--disable-swig`, and
`--disable-audio` respectively.

After `configure` runs successfully, the configuration options will be
printed for your confirmation.  If anything unexpected occurs, be sure
to check `config.log` for information about what failed.

### Building

Once the build is configured, build it with,

    make

Should any errors occur, please inform the [libmapper mailing list][list].

To verify that the library runs without errors, you may run the main
test program, available in the test directory:

    ./test/test -t

This program creates devices and signals and tests sending data between them using maps. The `-t` flag will cause the test program to automatically terminate after sending 200 messages, so omit it if you want to keep the test running indefinately.

Note that the programs in the test directory are _not_ examples of
library usage, as they additionally test some internal functions in
the library.  Please see the `examples` directory for examples of how
to use the library.

### Installing

The software may be installed with,

    sudo make install

This should place headers in `<prefix>/include/mapper`, the library
in `<prefix>/lib`, Python bindings in
`<prefix>/lib/pythonXX/site-packages` (where XX is your Python
version), and a `pkg-config` information file in
`<prefix>/lib/pkgconfig`.

Once installation is successful, you can check that the library is
found by `pkg-config`:

    pkg-config --libs --cflags libmapper

Note that the Java bindings are not installed, as there is no standard
location in which to put them.  However, they can be copied to
wherever is convenient for the classpath and java.library.path in your
project.  Instructions specific to Processing.org can be found in a
dedicated section below.

### Testing

As mentioned, you can test libmapper by running the test program,

    test/test

This should create two devices, link them, connect their signals, and
update a value continuously.  The other device should report that it
received the value.

You may wish to observe the multicast "admin" traffic, which can be
done by watching the multicast UDP port for OSC data using liblo's
`oscdump` utility:

    oscdump 7570 172.16.31.10

You can also use a libmapper GUI, such as [webmapper][webmapper], to
see that the devices and signals are discovered correctly.  You can
use the GUI to modify the connection properties, and observe that the
received values are changed.

[webmapper]: https://github.com/libmapper/webmapper

You should also test the Python and Java bindings if you plan to use
them.  Some other programs may depend on them – for example webmapper uses the Python bindings.

To test that the Python module is working, it is generally enough to
run the following command,

    python -m mapper

This will import the `mapper` module, which will fail if either
`mapper.py` or the native portion of the binding are not found.  You
may need to adjust your `PYTHONPATH` variable to ensure these can be
found.

You can test running programs by `cd`'ing to the `swig` folder and
running,

    cd swig
    python test.py

or,

    python tkgui.py

for a GUI example which brings up a single, mappable slider.  Running
multiple copies of `tkgui.py`, you can try mapping one to another to
make sure libmapper is functional.

Similarly, the Java bindings may be tested by `cd`'ing to the `jni`
folder and running `test` with the correct class and library paths:

    cd jni
    java -cp libmapper.jar -Djava.library.path=.libs test

Building on Windows
-------------------

### Dependencies

libmapper depends on version 0.30 of liblo or later.
Please clone the [LibLo repository][liblo] and consult its documentation to build for Windows.

[liblo]: https://github.com/radarsat1/liblo

Cmake is also required to generate visual studio solutions, and can be installed [here][cmake]. Add it to the environment path when prompted for terminal access later on.

[cmake]: https://cmake.org/download/

Zlib is required as well, which you can pick up [from nuget][zlib].

[zlib]: https://www.nuget.org/packages/zlib-msvc14-x64/

Finally, you'll need Visual Studio 2017 or 2019, which you can grab [here][visual_studio]. Be sure to install the C++ developer tools when installing if you don't already have them.

[visual_studio]: https://visualstudio.microsoft.com/vs/

### Configuring

Once libmapper is downloaded, open a terminal in its root folder.

Create a build directory and cd into it

    mkdir ./build
    cd build

Modify the CMakeLists.txt file in the root folder, replacing the paths near the top with your local paths.

Run the following to generate a solution, replacing your version's details:

    cmake -G "Visual Studio 16 2019" ..

### Building

By now, you should have a Visual Studio solution in the ./build directory. Open the .sln and build the libmapper project.

Cross-compiling for Windows under Linux
---------------------------------------

Since libmapper was developed on Unix-like systems (Linux and Apple's
MacOS), building libmapper uses GNU command-line tools.  However, it is
possible to build it for the Microsoft Windows operating system using
the MingW cross-compiler under Linux, or by using MingW from Windows.

{'fraction_non_alphanumeric': 0.06780603029039878, 'fraction_numerical': 0.004168403501458941, 'mean_word_length': 3.975803664016592, 'pattern_counts': {'":': 0, '<': 13, '<?xml version=': 0, '>': 13, 'https://': 6, 'lorem ipsum': 0, 'www.': 3, 'xml': 0}, 'pii_count': 2, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 2, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '790545', 'n_tokens_mistral': 3927, 'n_tokens_neox': 3705, 'n_words': 2070}