Différences

Cette page vous donne les différences entre la révision choisie et la version actuelle de la page.

Lien vers cette vue

openmusic:dev-resources:userlib [2011/01/30 22:23]
jean-admin
— (Version actuelle)
Ligne 1: Ligne 1:
-======Writing User Libraries====== 
  
- 
-We show in this page the way to write user libraries for OM. Section [[.:codeforOM|Writing code for OM]] may be necessary to understand this text. Libraries are specialized set of classes and methods written in Common-Lisp and loaded dynamically in OM. 
- 
- 
-Here you can download a template user-defined library (by M. Malt) : {{:openmusic:dev-resources:ma-lib.zip|}} 
- 
-Unzip this file if you want to try to load it in OM and/or to use it as a template for writing a new library. 
- 
- 
-=====Loading Libraries in OM===== 
- 
-{{ :openmusic:dev-resources:lib-packages.jpg?220}} 
-All the registered OM user libraries are acessible from the //Library// window (OM 6) or from the "package" workspace folder (OM 4, OM 5). 
- 
-Load one libray by double-clicking the bottom part of the corresponding lib icon, or by right-clicking (or control-clicking)  
- 
-on it and choosing //Open/Load Library// in the contextual menu. 
- 
-The library classes and functions will then be available in the same window, or from the general patch menus "classes" and "Functions" under "User Libraries". 
- 
- 
-There are three ways of loading an extra user library in OM. 
- 
-  * Put the library folder in the external user lib directory (specified in OM preferences). The library will be automatically loaded in the OM packages (OM 6.0.3 and higher). 
-  * Let it anywhere on your computer and load it dynamically after starting OM using the menu //File/New Remote Library...// of the library window (OM 5.1 and higher). 
-  * Put the library folder in // OM/UserLibrary/ // **before to start OM**. The library will be automatically added in the OM packages. 
- 
- \\ \\ \\ 
- 
- 
-===== The Library Folder ===== 
- 
-A user library is directory that contains source code and resources needed to build a library in OM. 
-This directory must respect some constraints : 
- 
-{{ :openmusic:dev-resources:libfolder.jpg}} 
- 
-  * The library's name is defined by the sub-string until the first space in the name of the folder.\\ For exemple a folder named //myLib 1.5// defines the library //"myLib"//.\\ If you have 3 folders named //"myLib"//, //"myLib 1.0"// and //"myLib xxx y zzz"// in the user library folder, for OM, you have 3 versions of a same library called //"mylib"//. 
- 
-  * A library is generally organized as follows : 
-    * **MyLib.lisp** is the file loaded when you load the library. 
-    * **resources** is the folder that contains the resources of the library. Principally, it contains a subfolder called "icon" in which the icons of the library are stored. 
-    * **sources** a folder that contains the source code of the library. 
-    * **online** a folder that contains tutorial patches for the objects of the library. 
-    * **examples** is a folder containing example/tutorial patches dynamically loadable in OM. 
- 
-  * **MyLib.lisp** is the only necessary element. The other ones are optionals.\\ Note that the file is called //MyLib.lisp// and not //MyLib 1.0.lisp// 
- 
- 
-===== Loading the Code ===== 
- 
-When you load a library from OM, the file **MyLib.lisp** is loaded. It should contain the instructions for loading the rest of the library source code. 
- 
-Here is an example of how to proceed with a sample library:  
- 
-<code lisp> 
-(defvar *MyLib-files* nil) 
- 
-(setf *MyLib-files*  
-  (list 
-    (make-pathname :directory (append (pathname-directory *load-pathname*) (list "sources")) :name "src-file1")  
-    (make-pathname :directory (append (pathname-directory *load-pathname*) (list "sources")) :name "src-file2")  
-    (make-pathname :directory (append (pathname-directory *load-pathname*) (list "sources")) :name "src-file3")  
-)) 
- 
-(mapc #'compile&load *MyLib-files*) 
-</code> 
- 
- 
-***load-pathname*** is a global variable that records the path of the file being loaded. In our case, this is the path to our **MyLib.lisp** file, hence to our library folder. 
- 
-We use this path in order to build the other pathnames to be loaded (in this case //[...]/MyLib/sources/src-file1.lisp//, etc.) 
- 
-**compile&load** compiles the corresponding Lisp files if needed and load the .cfsl (or .fasl) compiled files. 
- 
- 
-===== SubPackages ===== 
- 
-The classes and functions defined in the library can then be organized in sub-packages of this library. 
- 
- 
-When a library is loaded, the variable ''*current-lib*'' is set to this library. 
- 
- 
-You can use functions **omng-make-new-package**, **AddPackage2Pack**, **AddClass2Pack**, **AddLispFun2Pack**, **AddGenFun2Pack** (detailed in [[.:codeforOM|Writing code for OM]]) for setting your library package architecture. 
- 
- 
-There exists a function **fill-library** that creates and fill the subpackages from a list of the form //(sub-pack-name subpack-lists class-list function-list class-alias-list)// 
- 
-For example: 
- 
-<code lisp> 
-(om::fill-library '( 
- ("SubPackage1" nil nil (Addition) nil) 
-        ("SubPackage2" nil nil (Multiplication) nil) 
-)) 
-</code> 
- 
-... creates 2 sub-packages and and place the functions addition and multiplication in it. 
- 
-{{ :openmusic:dev-resources:packages.gif }} 
- 
- 
- 
-===== Icons ===== 
- 
-Icons are bitmap files (currently supported formats: tif, bmp, png, jpg...) to be put in the //MyLib/resources/icon/// directory. The file name must be a number which will correspond to the icon identifier in OM. 
- 
-Icon identifiers in a library can be used only for the library. 
- 
-For example, if a file called //176.tif// representing this icon : {{:openmusic:dev-resources:cucarron.gif}} is in //MyLib/resources/icon///, then  when you define the function "multiplication": 
- 
-<code lisp> 
-(defmethod! Multiplication ((self number) (arg number)) 
- :initvals '( 10 10 ) 
- :indoc '("First operand" "Second operand") 
- :icon 176 
- :doc "Multiply 2 things. Things can be numbers, lists, chords." 
- (* self arg) ) 
-</code> 
- 
- 
-... the icon is {{:openmusic:dev-resources:cucarron.gif|}} and not {{:openmusic:dev-resources:pepas.gif}} that is the correponding icon for 176 in OM. 
- 
-If you want to use an icon defined in the OM resources use a list with the iconID, for example: 
- 
- 
- 
-<code lisp> 
-(defmethod! Addition ((self number) (arg number)) 
- :initvals '( 10 10 ) 
- :indoc '("First operand" "Second operand") 
- :icon '(176) 
- :doc "Adds 2 things. Things can be numbers, lists, chords." 
- (+ self arg) ) 
-</code> 
- 
- 
-===== Dependencies ===== 
- 
-If your library needs to load other libraries use the function **require-library**. 
- 
- 
- 
-<code lisp> 
-(require-library "OMAlea") 
-</code> 
- 
- 
-===== Example patches and in line tutorials ===== 
- 
- 
-Your library may contain some example patches or in line tutorials for the objects (functions, classes) it contains.  
- 
-Example patches can be loaded from OM using the //Help/Import Tutorials// menu. 
-Just put patches in a directory called "examples" in the library folder. 
- 
-In line tutorial patches are opened by selecting an object in a patch and pressing 'T' key. 
-Create a patch with the same name as your function or class and put it in in a directory called "inline" in the library folder. 
- 
-\\