Scilab/C4/Developing-Scilab-Toolbox-for-calling-external-C-libraries/English

Developing Scilab Toolbox for calling external C libraries

Author: Rupak Rokade

Keywords: scilab, C, external libraries, interfacing, toolbox

Visual Cue	Narration
Show Slide: Opening Slide	Welcome to the spoken tutorial on “Developing Scilab Toolbox for calling external C libraries”
Show Slide: Learning Objectives	In this tutorial, we will learn to- Add an external C library to a Scilab Toolbox. Build and load a Scilab Toolbox
Show Slide: Systems Requirements	To record this tutorial, I am using- Ubuntu Linux Operating System version 19.10 and Scilab version 6.0.2
Show Slide: Pre-requisites https://spoken-tutorial.org/	To practice this tutorial, you should know- Basics of Scilab Basics of C programming. If not, watch the prerequisite Scilab and C tutorials on this website.
Show Slide	This tutorial makes use of files given in the Code files link on this tutorial page. These include Scilab6-Test-Toolbox-master.zip external-library.zip Download these before continuing.
Show Slide	The Scilab6-Test-Toolbox-master file is a Scilab toolbox. The name of this toolbox is test underscore toolbox. The purpose of this toolbox is to demonstrate how to add an external C library.
Show Slide	This toolbox provides two functions: add and multiply. The multiply function is implemented as an external library.
Show Slide	The toolbox in itself is incomplete and is only the source code. What is missing is the compiled version of the external library Recall that in this case the multiply function is the external library
Show Slide	On Linux OS, the external library has to be compiled into a shared object file We call that shared object file as a dot so file. This dot so file has to be provided via a directory named thirdparty. The corresponding header file must also be provided. Let us see how this external library is generated.
Switch to the Downloads folder	Switch to the folder where you have downloaded the external-library.zip file.
Right-click on the zip file >> Extract here option	Right-click on the zip file and choose Extract here to extract its contents.
Right-click on external-library directory >> So this option isn't available on my OSI prefered new window to show two things at onceOpen in new tabOpen in new window.	Open the external-library directory in a new window. To do so, right-click on the external-library directory. Choose the option Open in new window.
gedit mul.c	Locate the mul.c file. And double click on it to open it in a text editor.
Point to mul function definition. Close the file.	You can see it contains a function definition. The name of this function is mul. Close this file.
Right-click inside external-library directory >> click on Open in Terminal.	We will build a shared object file out of the mul.c file. Right-click somewhere inside the external-library directory and click on Open in Terminal.
Press Ctrl+Alt+T keys Change directory to external-library	If you don’t get this option, open the terminal by pressing Ctrl+Alt+T keys together. However, you will have to manually change the current directory to external-library directory.
Type ./run.sh >> press Enter	Now type dot slash run dot sh and press Enter. Ignore the warnings about it cannot remove certain files. However, pay attention to any compilation failure related messages. Now, type ls and press Enter. You can see a file with name libmul dot so This is our compiled external library that we will be using in our Scilab toolbox.
Show slide	The run dot sh file is a shell script. It contains commands required to compile the external library mul.c file in to a dot so file. It also automatically copies the dot so file and header file into a directory named as thirdparty. This thirdparty directory is now ready to be used in the test_toolbox Before that, here are some important points about the library compilation process.
Show slide	The process of generating the library depends on the Operating System in use. It also depends on the targeted external software library. Most libraries will provide specific build instructions such as make, cmake etc.
Show Slide	You may also have to explore additional compiler and linker flags during the compilation process. These could be crucial in order to generate libraries in the correct form.
Switch to external-library directory >> Right-click on thirdparty directory >> click on Copy	Switch to the external-library directory. Right-click on the thirdparty directory and click on Copy option.
folder >> Right-click on the zip file >> choose Extract here	Come back to the folder where the Scilab6-Test-Toolbox-master.zip code file is saved. Right-click on that zip file and choose Extract here to extract its contents.
Open Scilab6-Test-Toolbox-master >> Right-click inside this folder >> click on Paste.	Open the folder Scilab6-Test-Toolbox-master. Right-click inside this folder and click on Paste.
	This will paste the thirdparty directory inside the Scilab6-Test-Toolbox-master directory.
Show Slide	Now let us learn more about the Scilab toolbox. The toolbox makes use of a Gateway Function to communicate with the library. Every new function added via an external library, requires a separate gateway function. These gateway functions are CPP files inside the sci gateway slash cpp directory.
Show slide	They make use of the Scilab C API for data processing and communication. Refer to this website to understand the Scilab C API.
Scilab6-Test-Toolbox-master directory >> open sci_gateway	Now come back to the Scilab6-Test-Toolbox-master directory. Open the folder sci underscore gateway.
Open cpp	Open the folder cpp.
Open sci_multiply.cpp	Now, open the file sci underscore multiply.cpp by double-clicking on it. This file is the corresponding gateway file for the multiply function.
Point to mul.h header	It includes the mul dot h header file.
Point to fname variable	The fname variable declares the name of this function. This function name will be made available in the Scilab workspace after the toolbox is loaded.
Point to the code >> call to mul function	The file also has some code which is followed by a call to the mul function.
	This mul function is defined inside the dot so file that we generated earlier.
Put text on screen for this part	Note that you need to understand the Scilab C API in order to fully understand this code.
Close this file.	Close this file.
Open builder_gateway_cpp.sce	Locate the file builder underscore gateway underscore cpp dot sce. Right-click on it and choose Open with text editor
Point to variable Function_Names.	See the variable Function underscore Names. It declares the function name, the gateway function name and a format.
Point to variable Files.	See the variable Files. It contains the names of the gateway files that have to be included in the toolbox. In our case it is sci underscore multiply.cpp
Point to variable Linker_Flag.	Next see the variable Linker underscore Flag. It contains a link to the dot so file for the external library via the hyphen lmul flag. Even though our compiled library name is libmul.so, on Linux it is referred to as lmul
Close this file.	Close this file.
Start Scilab >> Click on File menu >> Browse for new	Now, let’s start Scilab. Click on the File menu and click on the Browse for new option.
Browse to Scilab6-Test-Toolbox-master directory >> click on Ok button.	Browse to Scilab6-Test-Toolbox-master directory and click on the Ok button.
Scilab console >> type exec builder.sce >> press Enter	On the Scilab console, type e x e c space builder dot sce and press Enter.
Do as per narration	A pop up window will open. Click on the Create anyway button every time the pop up appears.
	This should build the toolbox without any difficulty. Pay attention to errors, if any.
Type exec loader.sce >> press Enter	Then type e x e c space loader dot sce and press Enter. This should load the toolbox without any difficulty. Pay attention to errors, if any.
Type help >> press Enter	Then type help and press Enter. The Scilab Help window will open.
Point to left side >> open test_toolbox Point to right side >> point to functions	On the left hand side, locate the test underscore toolbox and click on it to open it. On the right hand side you will see the list of functions available in this toolbox.
Click on link for multiply function >> scroll to Examples	Click on the link for multiply function. Scroll down to the Examples section.
Click on execute button	Click on the execute button on the top right corner of the Examples section. This will execute the example.
Scilab console	Switch to the Scilab console.
Point to multiply function	See that the multiply function has been called. It multiplies the numbers 3 and 5 and returns their multiplication as 15.
Put text on the screen for this part.	Now let us see how to write the help content for a function. Note that writing help is mandatory, if you wish to publish your toolbox over atoms website.
Scilab6-Test-Toolbox-master directory >> Open macros directory	Switch to the Scilab6-Test-Toolbox-master directory. Help content is usually written inside a dot sci file inside the macros directory. Open the macros directory.
Right-click on multiply.sci >> Open With Text Editor	Right-click on the file multiply.sci and choose Open With Text Editor.
Point to "multiply" function declaration Point to comments	Notice that this file has a function declaration named multiply. However, it has only comments inside. This is because we are making use of this function only to generate the help content.
Show slide	Comments made at the beginning of a function represent the help content. The comments have to strictly follow a particular format. Any variation from this format will fail the generation of help during the build process. See this webpage on how to write help content.
Show slide	A few tips. Do not make any spelling mistakes. This is because the help is generated using keywords.
Show slide	Do not leave any blank lines in between. If you want to leave a blank line, comment it out. If the edits are not getting reflected back in the help page, delete these files as shown.
Scilab6-Test-Toolbox-master directory >> Open it is not falling in the scope of this tutorialPlease explain about loader.sce file and also the remaining folders such as etc, jar, localesbuilder.sce	Switch to the Scilab6-Test-Toolbox-master directory. Locate the file builder dot sce. Right-click on it and choose Open With Text Editor.
Scroll to the end Point to tbx_builder_gateway command	Scroll to the end. This file controls the overall toolbox build process. The tbx_builder_gateway command is required to add an external library to the toolbox.
Show Slide: Summary	Let us summarise. In this tutorial, we learnt to: Add an external C library to a Scilab Toolbox. Build and load a Scilab Toolbox.
Show Slide: Forum to answer questions https://forums.spoken-tutorial.org/	Do you have questions in this Spoken Tutorial? Choose the minute and second where you have the question. Explain your question briefly. Someone from the FOSSEE team will answer them. Please visit this site.
Show Slide: FOSSEE Forum https://forums.fossee.in/	For any general or technical questions on Scilab, visit the FOSSEE forum and post your question.
Show Slide: Circuit Simulation https://scilab.in/Textbook_Companion_Project	The FOSSEE team coordinates the Textbook Companion project. We give Certificates and Honorarium to the contributors. For more details, please visit this site.
Show Slide: Lab Migration https://scilab.in/Lab_Migration_Project	The FOSSEE team coordinates the Lab Migration project. For more details, please visit this site.
Show Slide: Acknowledgment http://spoken-tutorial.org	Spoken Tutorial Project is funded by NMEICT, MHRD, Govt. of India. For more details, visit this site.
Thank you slide	This is Rupak Rokade from IIT Bombay signing off. Thank you

Contributors and Content Editors

Nancyvarkey, Rupakrokade