Commit 0fe4b756 authored by Arnaud Blanchard's avatar Arnaud Blanchard

Much more documentation

parent aab1ff2d
DEVELOPMENT
=============
Compiling
--------------
Use `./compile.sh <project directory> [Release|Debug|RelWithDebugInfo|RelMinSize]` (blc, blv4l2, ...)
The binaries will be in `build/<Release|Debug|RelWithDebugInfo|RelMinSize>`and the libraries in the subdirectory `lib`.
The cmake builds will be in `build/cmake_files_<Release|Debug|RelWithDebugInfo|RelMinSize|eclipse|xcode>/`.
`build/` is a symbolic link toward a real directory which is outside your current directory usually :`../blaar_build`.
The prefix automatically takes the value of your directory (i.e. if you are in `test_blaar/` the real build directory will be `../test_blaar_build/`. This allows you to have different versions in different directories (we recommend to use git branches instead of different copies).
When your are coding on your project you should use `./run.sh <project directory>` instead of directly calling your binary. Like this, you are sure to use the last compilation of your code. **./run.sh** automatically compiles you code before executing it.
The compile and install process uses [CMake](https://cmake.org). The intermediate files generated are in `build/cmake_files_<Release|Debug|RelWithDebugInfo|RelMinSize|eclipse|xcode>` . Do not hesitate to remove them to solve problems during cmake compilation.
Remove the **cmake_files_<Release|Debug|RelWithDebugInfo|RelMinSize|eclipse|xcode> as soon
Installing
----------
Some projects like the libraries need to be installed. In this case you can do `./install <project> [<Release|Debug|RelWithDebugInfo|RelMinSize>]`
This will compile and install the project. You can use it for all the projects enven those which does not need install. You computer password may be requested.
If you want install all the submodules use `all`: **`./install.sh all [<Release|Debug|RelWithDebugInfo|RelMinSize>]`**
If your project is not a git submodule it will not be installed and compiled. Use `./run.sh` as explained above.
Debugging
---------------
In case of problem you may debug: `./debug.sh <project directory>` or realize memory check with valgrind: `./valgrind.sh <project directory>`. The project is automatically recompiled in debug mode and the appropriate debugger (gdb, lldb, valgrind) is called.
If the problem appear in another project you may reinstall all the projects in Debug mode: ` ./install.sh all Debug`
Eclipse
----------
```bash
./eclipse_create_project.sh <project dir>
```
Follow the instruction to import the project
If you want to debug: **debug->debug configurations->new C/C++ application->browse: `<blaar_build>/Debug/<project>`**
Xcode (Mac OSX)
-----------------------
```bash
./xcode_project <project>
```
**xcode** will be automatically launched with the project
Source documentation
====================
To build the source documentation with **doxygen**: `./doc_api.sh <project>`.
Add **-c** option if you want only the C accessible API.
The built documentation will be opened automatically. For information, it is in `build/<cpp_api|c_api>/<project>/html/index.html` and will be opened automatically.
Each time, press 'q' to quit the test
Each test will generate intermediate blc_channels. You can see them using `blc_channels` you can remove them unsing: **`blc_channels --unlink_unused`**
For each executable you can see the possible options with --help
Input and output with sound
===========================
- [asound](https://framagit.org/blaar/asound) **On OSX you need coraudio**
- [sndfile](https://framagit.org/blaar/sndfile)
- [o_gnuplot](https://framagit.org/blaar/o_gnuplot)
Display the graph of the microphone
-----------------------------------
i_asound | o_gnuplot --min=-1
* min=-1 is to display negative values (default: min=0, max=1)
Record the microphone in a file
-------------------------------
i_asound | o_sndfile --file=record.wav
Replay the file
---------------
i_sndfile --file=record.wav | o_asound
Show the graph of the file
--------------------------
i_sndfile --file=record.wav | o_gnuplot --min=-1
Display oscillator of 440hz
---------------------------
i_oscillator --size=4096 --frequency=440 --refresh=92.88 | o_gnuplot
* --size request a buffer of 4096 floats (float is default type)
* --refresh refresh the buffer each 92.88 ms (This timing will be important for the sound)
* --frequency fill the buffer in order to generate a signal of 440Hz
![image](http://blaar.org/images/examples/graph_440Hz.png)
Produce a sound of 440Hz (in music LA)
------------------------
i_oscillator --min=-1 --size=4096 --frequency=440 --refresh=92.88 | o_asound
This means that i_oscillator will fill a buffer of 4096 floats each time the sound is ready to play.
The sound play at a samplerate of 44100 therefore each 92.88ms (4096/44100).
We need to give this information to the oscillator to let it compute the wav form in function of the frequency.
* --min=-1 give the bottom value of the oscillator (usually 0)
Analyse with a fast fourier transform
=====================================
Need submodules: [fftw](https://framagit.org/blaar/fftw)
Apply a fft on sound to get the spectrum and display the result in a graph
--------------------------------------------------------------------------
i_asound | f_fftw --spectrum | o_gnuplot --label-max=22050 --text="xlabel 'frequency in Hz'" --max=0.1 --xmax=5000
f_fftw: --spectrum request for the norm of the complex values (we get the frequency but we loose the phasis information).
o_gnuplot:
* --label-max changes the scale on the abscissa to have the last value corresponding to the a frequency of 44100/2 because the acquisition samplerate is 44100
* --text send a pure request to gnuplot. Here we set the label text.
* --xmax request to not display data after 5KHz we consider it is not useful for speech
Apply a fft on a pure sinusoidal signal and graph it
----------------------------------------------------
i_oscillator --size=4096 --frequency=440 --refresh=92.88 --min=-1 | f_fftw --spectrum | o_gnuplot --label-max=22050 --text="xlabel 'frequency in Hz'" --xmax=5000
![image](http://blaar.org/images/examples/graph_440Hz.png)
Give the max of the frequency
-----------------------------
i_oscillator --size=4096 --frequency=440 --refresh=92.88 --min=-1 | f_fftw --spectrum | f_max --find_arg=10.77 --output=-
* --find_arg means we dont want the max but the index of the max. 10.77 means we scale the index by 44100/4096 to convert index in Hz.
* --output select where we want to put the output. - means it is not a channel but the terminal.
This return: 446.955017 on the terminal.
**ninja: error: opening build log: Permission denied** while you compile a project
This is a bug. For now a fix is to `rm -rf build/cmake_file_Realase` and reinstall
Install blaar on Mac OSX
========================
[Video tutorial](http://www.etis.ensea.fr/neurocyber/blaar/videos/blaar_osx_install.mp4)
You need Xcode or a C/C++ compilation (clang, g++, ..).
Copy past this line in a terminal
curl -sS https://framagit.org/blaar/blaar/raw/master/developer_tools/install_standard_osx_blaar.sh | bash
You can do [**step by step**](https://framagit.org/blaar/blaar/blob/master/developer_tools/install_standard_osx_blaar.sh) copying command line by command line. This may be useful to better understand and in case where the installer crash.
If you have a problem at compile time it may be due to a bad configuration of your compiler [**see how to install command line tools mac os x**](http://osxdaily.com/2014/02/12/install-command-line-tools-mac-os-x/)
**Optional modules**
#o_gnuplot : Draw as gnuplot graph, the values of blc_channels
brew install gnuplot --with-qt
git submodule add git submodule add https://framagit.org/blaar/o_gnuplot.git
#f_fftw : Apply fft on the signal. Need fftw
brew install fftw
git submodule add https://framagit.org/blaar/f_fftw.git
#sndfile : load any kind of sound file. Required libsndfile
brew install libsndfile
git submodule add https://framagit.org/blaar/i_load_sound.git
#f_view_channel : gtk interface to view blc_channels (need gtk3, blgtk basic library for gtk3, will be installed)
brew install gtk+3 gnome-icon-theme
git submodule add https://framagit.org/blaar/blgtk.git
git submodule add https://framagit.org/blaar/f_view_channel.git
./install blgtk
Install blaar on Ubuntu
=======================
Copy past this line in a terminal
wget -q -O/tmp/blaar_install.sh https://framagit.org/blaar/blaar/raw/master/developer_tools/clone_and_install_ubuntu_blaar.sh && bash /tmp/blaar_install.sh; rm /tmp/blaar_install.sh
You will be requested at some point to enter your admin password to make the installation.
You can do [**step by step**](https://framagit.org/blaar/blaar/blob/master/developer_tools/clone_and_install_ubuntu_blaar.sh) copying command line by command line. This may be useful to better understand and in case where the installer crash.
Optional modules
----------------
To install them, copy past the code in a terminal.
#o_gnuplot : Draw as gnuplot graphs, the values of blc_channels. Need gnuplot
sudo apt-get install gnuplot
git submodule add https://framagit.org/blaar/o_gnuplot.git
#fftw : Apply fft function on signal. Need fftw
sudo apt-get install fftw
git submodule add https://framagit.org/blaar/fftw.git
#sndfile : load and save any kind of sound file using libsndfile
sudo apt-get install libsndfile-dev
git submodule add https://framagit.org/blaar/sndfile.git
#asound : acquire and produce sound
sudo apt-get install libasound2
git submodule add https://framagit.org/blaar/asound.git
#f_view_channel : gtk interface to view blc_channels (need gtk3, blgtk basic library for gtk3, will be installed)
sudo apt-get install gtk+3
git submodule add https://framagit.org/blaar/blgtk.git
./install blgtk
git submodule add https://framagit.org/blaar/f_view_channel.git
......@@ -8,7 +8,7 @@ Basic Libraries for C/C++
-------------------------
- [blc_core](https://framagit.org/blibs/blc_core) : Generic helpers in C or C++ used by all other blaar projects
- [blc_channel](https://framagit.org/blibs/blc_channel) : Tools to use shared memory in synchrone ( in test) and asynchrone mode
- [blc_image](https://framagit.org/blibs/blc_image) : Manipulate bla_array as images. Can load and save them as png files
- [blc_image](https://framagit.org/blibs/blc_image) : Manipulate blc_array as images. Can load and save them as png files
- [blc_program](https://framagit.org/blibs/blc_program) : Parse arguments and interacts with user in commandline.
Applications for C/C++
......@@ -19,97 +19,44 @@ Applications for C/C++
Install
=======
Mac OSX
--------
* [Mac OSX](INSTALL_OSX.md)
* [Ubuntu](INSTALL_UBUNTU.md)
[Video tutorial](http://www.etis.ensea.fr/neurocyber/blaar/videos/blaar_osx_install.mp4)
Adding submodules
-----------------
You need Xcode or a C/C++ compilation (clang, g++, ..).
You will only have basic framework. You may add submodules as needed.
Copy past this line in a terminal
To add project use : `git submodule add <project repository>`
curl -sS https://framagit.org/blaar/blaar/raw/master/developer_tools/install_standard_osx_blaar.sh | bash
Once you have added a submodule, install it with `./install.sh <project>|all`
You can do [**step by step**](https://framagit.org/blaar/blaar/blob/master/developer_tools/install_standard_osx_blaar.sh) copying command line by command line. This may be useful to better understand and in case where the installer crash.
**all** install all your projects (submodules) at once.
If you have a problem at compile time it may be due to a bad configuration of your compiler [**see how to install command line tools mac os x**](http://osxdaily.com/2014/02/12/install-command-line-tools-mac-os-x/)
Update the installation
-----------------------
`update_and_install_all.sh`
**Optional modules**
#o_gnuplot : Draw as gnuplot graph, the values of blc_channels
brew install gnuplot --with-qt
git submodule add git submodule add https://framagit.org/blaar/o_gnuplot.git
#f_fftw : Apply fft on the signal. Need fftw
brew install fftw
git submodule add https://framagit.org/blaar/f_fftw.git
#sndfile : load any kind of sound file. Required libsndfile
brew install libsndfile
git submodule add https://framagit.org/blaar/i_load_sound.git
#f_view_channel : gtk interface to view blc_channels (need gtk3, blgtk basic library for gtk3, will be installed)
brew install gtk+3 gnome-icon-theme
git submodule add https://framagit.org/blaar/blgtk.git
git submodule add https://framagit.org/blaar/f_view_channel.git
./install blgtk
Ubuntu
------
Copy past this line in a terminal
wget -q -O/tmp/blaar_install.sh https://framagit.org/blaar/blaar/raw/master/developer_tools/clone_and_install_ubuntu_blaar.sh && bash /tmp/blaar_install.sh; rm /tmp/blaar_install.sh
You will be requested at some point to enter your admin password to make the installation.
You can do [**step by step**](https://framagit.org/blaar/blaar/blob/master/developer_tools/clone_and_install_ubuntu_blaar.sh) copying command line by command line. This may be useful to better understand and in case where the installer crash.
**Optional modules**
To install them, copy past the code in a terminal.
#o_gnuplot : Draw as gnuplot graphs, the values of blc_channels. Need gnuplot
sudo apt-get install gnuplot
git submodule add https://framagit.org/blaar/o_gnuplot.git
#fftw : Apply fft function on signal. Need fftw
sudo apt-get install fftw
git submodule add https://framagit.org/blaar/fftw.git
#sndfile : load and save any kind of sound file using libsndfile
sudo apt-get install libsndfile-dev
git submodule add https://framagit.org/blaar/sndfile.git
#asound : acquire and produce sound
sudo apt-get install libasound2
git submodule add https://framagit.org/blaar/asound.git
#f_view_channel : gtk interface to view blc_channels (need gtk3, blgtk basic library for gtk3, will be installed)
sudo apt-get install gtk+3
git submodule add https://framagit.org/blaar/blgtk.git
./install blgtk
git submodule add https://framagit.org/blaar/f_view_channel.git
Adding projects
===============
You will only have basic framework. You should add projects as needed
To add project use : `git submodule add <project repository>`
This will download the new code and install it for blaar and each submodule
Usage
=====
./run.sh <project directory> [--help] [others args ...]
bin/<executable> [--help] [others args ...]
This automatically compiles the project in release mode and executes it. You do not risk anymore to test a program you forget to recompile.
All the project has the **--help** which will show a small description of the program and the list of options with theirs descriptions.
You have equivalent commands for debugging or editing projects. These scripts are shortcuts and you can manually compile, debug etc. See [developement](development).
It is usefull to add to your `~/.bashrc` on Linux or to your `~/.bash_profile` on OSX:
You can see an [**example**](https://framagit.org/blaar/blc_core/wikis/home) of manipulating and displaying generic arrays with blc_core
export PATH=$PATH:~/blaar/bin
Assuming your blaar is in your home ~ .
This allows you to call any blaar executable from anywhere.
You can create you first project with this example of [image manipulation](https://framagit.org/blaar/blc_image/wikis/home)
When your are in development your are advised to see [developement](DEVELOPMENT.md).
You can see an [**example**](https://framagit.org/blibs/blc_core/wikis/home) of manipulating and displaying generic arrays with blc_core
You can create you first project with this example of [image manipulation](https://framagit.org/blibs/blc_image/wikis/home)
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment