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

From Script | Spoken-Tutorial
Revision as of 16:42, 23 May 2020 by Rupakrokade (Talk | contribs)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

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

  1. Scilab6-Test-Toolbox-master.zip
  2. 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 a Linux OS, the external library has to be compiled into a shared object file
  • We call that shared object file as The focus is on slidesWhere is it located? hover over this file while explainingdot so file.
  • This The focus is on slidesWhere is it located? hover over this file while explainingdot 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 So this option isn't available on my OSOpen in new tabI prefered new window to show two things at onceOpen 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 * Yes. similarLikewise, this too.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.

Back to For Novice check, you will have to mention where you have the fileI dont know this folder name. It depends on where they save the filereplace the name of the folderxxxxxxxxxxxxx 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 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.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 example 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 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 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, for example, 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

Retrieved from "https://script.spoken-tutorial.org/index.php?title=Scilab/C4/Developing-Scilab-Toolbox-for-calling-external-C-libraries/English&oldid=52160"