Initial scriptmodule guide #127
Conversation
There was a problem hiding this comment.
Thanks for this. I had a quick scan and noticed some issues.
It misses a lot out so I'm in two minds of how useful it is in it's current form for development. Eg. "if needed applyPatch" doesn't really say much. In other places only a few parts are explained. Maybe I'm misunderstanding who this is aimed at.
Would this be something you would also be willing to maintain if it was included?
|
|
||
| : Retrieves the sources which are needed to build the infini emulator. Typical | ||
| functions called from here are `gitPullOrClone` and, if needed `applyPatch`. The | ||
| sources will be put at `~/RetroPie-Setup/tmp/build/<infini-sourcetree>/`. |
There was a problem hiding this comment.
The sources will be put at ~/RetroPie-Setup/tmp/build/infini/. - adding sourcetree confuses it I think.
| ./retropie_packages.sh infini`. You may also call them isolated, e.g. `sudo | ||
| ./retropie_packages.sh infini configure`. Therefore it is important that each of | ||
| the functions is idempotent i.e, the result should always be identical | ||
| regardless if the function is called once or multiple times. |
There was a problem hiding this comment.
This isn't clear I think. Do you mean each function should be stand-alone?
| done | ||
| ``` | ||
| Output will be in `~/RetroPie-Setup/tmp/build/apidocs/html/`. | ||
|
|
There was a problem hiding this comment.
Would be easier to just link to https://retropie.org.uk/api/
| name itself, thus as in this example infini. Keep the ID short and use only | ||
| alphanumeric characters, plus dash (`-`) and underscore (`_`). The ID is | ||
| also used for calling the scriptmodule directly from `retropie_packages.sh` | ||
| script (see above). |
There was a problem hiding this comment.
We don't use underscores for module ids.
| can be run. Conditions may apply for the different hardwares, architectures | ||
| and capabilities of an architecture. For example: A flag `sdl2` requires | ||
| that on the target SDL2 must be available. If not the scriptmodule will not | ||
| run. You can also negate a flag by putting a bang (`!`) before, thus |
There was a problem hiding this comment.
SDL1 / SDL2 flag has no bearing on the requirements in regards to any dependencies or if the module will run. It's used by runcommand and the backends module.
| `$home` | ||
|
|
||
| : The home directory of the account which is used to run any emulator. | ||
| Default: `/home/pi/` |
There was a problem hiding this comment.
The default is the home directory of the user it's installed for.
|
|
||
| `$md_id` | ||
|
|
||
| : Same as `$repo_module_id` |
There was a problem hiding this comment.
there is no repo_module_id - there is a rp_module_id but it's not an available variable for use in a module so I think including it with $ is confusing.
| : The installation target folder for the emulator: | ||
| `/opt/retropie/emulators/$md_id/`. Or specific to this example: | ||
| `/opt/retropie/emulators/infini/` | ||
|
|
There was a problem hiding this comment.
the install location is generally /opt/retropie/$md_type/$md_id/
|
|
||
| `$user` | ||
|
|
||
| : The user account running your emulator. Default: `pi` |
There was a problem hiding this comment.
As above regarding defaults.
| #### Location of Launcher | ||
|
|
||
| Many emulators only require the absolute path to the ROM to launch. If the | ||
| emulator you are adressing with your scriptmodule requires different information |
| The `make` should usually not contain any extra flags like `-j`. This is handled | ||
| by the script RetroPie script | ||
| [`system.sh`](https://github.com/RetroPie/RetroPie-Setup/blob/master/scriptmodules/system.sh). | ||
| You can however, define `__makeflags`, `__cflags`, aso. for the build if |
There was a problem hiding this comment.
There is no need in general to adjust these globals. If this is about developing scriptmodules then these should be left alone. This is for overriding global cflags / cxxflags / makeflags when calling retropie_packages.
| fi | ||
| ``` | ||
| In the configuration function you | ||
| may also define the launcher file. |
There was a problem hiding this comment.
Not sure how useful this is? It's too vague to be of any real use.
|
@Gemba thank you for the page, but I think this should be written by a more experienced collaborator or a RetroPie team member. We spend too much time reviewing it to correct/improve it and some aspects about the innards of RetroPie-Setup's structure and process are not so obvious just from a simple scriptmodule. I hope you don't take this the wrong way, we really appreciate your contributions here and in the forums. |
|
Nvm. I only had a vague hope to hit the nail in the first run, so I am not disappointed. Better crash early. It was written from a "reverse-engineering" perspective and with the advise I got from you guys. I am clearly missing the design decisions and rationale you had in mind when setting the structure up. I never assumed this to be a one-time shot of mine, so I am still open restart and do iterations until it is a document that moves a intermediate skilled Linux/Bash user forward on developing a scriptmodule and saves you guys the time to explain the best-practices for scriptmodules again and again. Cheers |
As announced in the forum: https://retropie.org.uk/forum/topic/33969/adventuregamestudio-ags-scriptmodule-updates/11?_=1678549154338
Hopefully I got it right.
I added two markdown extensions in
mkdocs.yml. If strict commonmark should be used please let me know.