Improving / simplifying module making : Discussions
PAA: Pierre-Aimé AGNEL
SG : Samuel GOUGEON
OK: Creating from scratch the files structure of a new toolbox may be seen as its first configuration step. Therefore, this operation may be usefully supported through the same tbx_config() function that will be used to set and update the toolbox parameters afterwards.
Alternately, creating a specific tbx_init() to do this step does not look useful. If after implementing and using tbx_config("init") we see that splitting this in a dedicated public function would be better, we will do it. Most of/all these toolboxes operations are done by hand in a console-oriented way. So BC issues are not really a concern.
Proposal (about the presentation): Switch the order parts
- Requirement 1: providing the conventional layout
- Requirement 2: setting/getting the toolbox parameters
- name and format of the config file
- Local GUI and ATOMS server
- Supported parameters
- Set and Get features
OK: I switch the requirements number and position, and add the subsections
About the proposal:
tbx_config("init") // creates a default layout with macros/, help/ and tests/ folder and a license.txt tbx_config("init", "default") // same as above tbx_config("init", "code") // adds the src/ includes/ and sci_gateway/ directories tbx_config("init", "xcos") // adds the default mandatory xcos directories tbx_config("init", "all") // all possible directories as taken from the skeleton
Path to the toolbox root: All these syntaxes (and next proposed ones for other config operations) assume that the current working directory is the toolbox root. They do not allow any other behavior. I think that it is a bit risky. As for tbx_make(), i would propose to expect the tbx_path as first mandatory input parameter. Providing "" or "." or  for it considers pwd(). For the discussion here, tbx_path is always skipped.
- Proposed flags:
(none): then help and macros are minimal default created dirs: OK
The explicit default flag does not look really required. In which situation could it be useful? The less verbosity the better.
"code": I would prefer "external" (or similar). Macros are some code as well.
"all": really useful? The user won't have in mind what it means. Again, IMO, the less the better: We should not encourage empty directories.
sections flags must have the same names as tbx_make() ones.
tbx_config("init", sections): shall accept a vector of sections to create if not yet existing.
It shall as well be used even after the very first creation, to add additional sections.
- When a section already exists, nothing is done (some checking operations about the tbx architecture could be implemented later if required)
Path to the toolbox root: Agreed, same as tbx_make
- Proposed flags:
The explicit default flag does not look really required => OK I remove it
"code": I suggest explicit "src" "src/c" "src/fortran" "sci_gateway" (will create the default layout and add respectively src/c, src/c, src/fortran, sci_gateway/c
"all": I remove it.
Other proposed flags: "demos", "tests", I would strongly advise test to be in the default layout: tests are currently our only rapid/automated access to functional code of a toolbox, we use them to test toolbox before publication on the ATOMS servers.
tbx_config("init", sections): shall accept a vector of sections to create if not yet existing => Agreed
sections flags must have the same names as tbx_make() ones => so there would be two kind of flags, very specific (adds only one subdirectory) and proper layouts (various subdirectories)?
When a section already exists, nothing is done (some checking operations about the tbx architecture could be implemented later if required) => Agreed
About initial files:
Default ~/config.ini file: At toolbox creation, and as long as the toolbox did not get its actual id from the ATOMS server, this file is created. Its default content could be discussed below.
~/license.txt: why not.
- The question is: which default license?
- IMO, the licence's name must be directly visible. It shall be part of the license filename. Examples: license_GPL_2.txt, license_Cecill_2.txt
tbx_config("license", licenceName) shall be proposed to switch the license. A set of predefined license files shall be available in SCI/toolbox_manager/etc/licenses/*. A license_custom.txt generic almost empty file shall be proposed in the set.
- The license and its file shall be as well set and changed from the config GUI, as the current ATOMS setting page proposes selecting it (however without adding the corresponding license file to the toolobox).
I agree with a management of licenses. It is my strong opinion that the ATOMS server should only manage open source code and Scilab Enterprises should manage a separate channel/service for nonfree code. For the function though a selection of licenses should be proposed.
Name and format of the config file
As long as the toolbox is anonymous and unpublished (no id/shortname on ATOMS), the filename is config.ini
- As soon as the tbx is registered on ATOMS,
its id(shortname) and version shall build the basename of the config file. Example mytbx_2_3.ini.
- Actually, imo this is the simplest way to set these major informations directly visible in the files tree of the toolbox, at its root. IMO, this is a major requirement.
- Agreed, having a basic information visible is sound enough.
- This means that
if the version is changed through tbx_config(), this one shall change the config .ini filemane accordingly.
This file must be the only one with the .ini extension, at the tbx root.
Making *.ini a binary non-editable file would prevent easily editing it by hand. It could be the binary record of a Scilab structure registering all configuration parameters names and values. The most straightforward -- and likely convenient -- would be to keep the current DESCRIPTION structure set for every toolbox_version.
If we keep the ~/etc directory, storing the .ini in it would a bit more logical. But will it be worthwhile keeping ~/etc/? For custom .start, .quit, preferences.xml,.. and may be .ini: likely yes. Unless these files are moved on the toolbox root. Actually, they are not so numerous.
PAA: etc/ should really be extra configuration for user specific purposes, I tend to agree with you on removing the requirements (and files) from etc
Local GUI and ATOMS server
I think that building a Scilab GUI should definitely have priority over building a set of public tbx_config(tbx_path, field, values) functions "à la ATOMS".
- [By the way, such a GUI would be as well welcome for all settings of the ATOMS system. It would allow to more easily oversee all parameters, as a dedicated tab in the Preferences could do it as well.]
- The submitted tbx_name would have to be approved by the ATOMS server. Once done, some hidden fields (not editable and not displayed, but recorded) could be set to say: OK, this is ATOMS approved. Then the tbx_name field would be locked, as it is currently on the ATOMS setting online page.
PAA: * My suggestion here is to open a web browser page and have the ATOMS portal manage the GUI for the settings. This will avoid code duplication inside scilab. The server will have a scilab that will create the config.ini file and send it back to the user. This has many advantages: 1) the server can check immediately if other toolboxes with the same name exists 2) the server can give the list of versions for a toolbox 3) the edition possibilities of a web based application is greater and more easily maintained than those of a local GUI 4) the management of mandatory fields will be easier on the web page * The validation on the web page will lead to an upload of the config.ini file. * Local GUI: Alternately, the GUI could be entirely Scilab based but this will imply more maintenance and should not be preferred, but alleviate the need for an internet connection or a private ATOMS server
SG: I have no sharp opinion there. May be i would rather prefer editing all parameters locally, recording them in the config file. Then, through the tbx_publish(),
- the config file would be uploaded
- ATOMS will send its feedback about the uploaded proposal
- According to its feedback, the approved/updated config file would be downloaded back to the local drive.
Anyway, i really think that a local GUI would be more handy than tbx_config(path, field, values) sequences. I mean: All what you propose to set with such sequences should be editable through a GUI
My real concern here is duplicating the GUI. There exists a configuration page already, it's the ATOMS server web page. It does already all the necessary verifications (unicity, versions, dependencies). The only improvement it could have is creating the config file (instead of a text description) ready for upload, which would remove the need for the atomsDESCRIPTIONread() function (that takes most of the processing time in ATOMS btw just to recreate a structure that could be computed once on server side and loaded directly in scilab).
- It would as well allow displaying infos that are not necessarily editable. All infos from the .ini contents in the same "viewbox".
tbx_config(tbx_path, "gui"): agreed
tbx_config() should already support remote connections with the ATOMS server, for the whole tbx parameters part. IMO this part should not be transferred to tbx_publish(), that would be dedicated "only" to the execution, packaging, implicit or explicit flag-setting, and uploading of zipped files. The current ATOMS setting page already quite clearly separates both subsets of actions: DESCRIPTION / FILES. I think that this organization is relevant and should be kept.
The tbx_config could very well be the opening of the ATOMS webpage for DESCRIPTION, once filed sends back the config.ini file. tbx_publish should be a button/action in the filebrowser really ( => publish in atoms, => publish in fileexchange )
The list may be discussed later.
Remarks and questions:
PAA: There should be a possibility to specify the generation of each language independently.
- SG: agreed
- PAA: tbx_make() should zip all those functions in one, I suggest deprecating all the aforementioned tbx_build* functions and render them private to tbx_make():
- This reduces the documentation
This avoids code duplication of functions only executing build scripts...
SG: Agreed! We are on the right way. But because things are quite complicated and that BC is a major concern to not kill all existing Scilab 5 resources, we should go step by step in reforging the toolbox_manager. AFAIU, the visibility of secondary macros in .sci is no longer the same and is decreased in Scilab 6 wrt Scilab 5. Some users may have used some of these low-level macros directly, since they were documented in Scilab 5.
BC is really an issue here, tbx_make should keep building former toolboxes, but slowly deprecating the numerous helper functions is the right direction (eventually there would only be a tbx_config, tbx_make and tbx_publish high level functions.
- PAA: The unloader should not do anything by default (execpt for calling a .quit file if it exists).
- SG: Why? As proposed in the commit, by default it may
- unregister the library
- remove the help chapter
- .. remove demos
PAA: you are right