Meta.pm: Metadaten über FHEM Module

Begonnen von Loredo, 19 Februar 2019, 11:43:50

Vorheriges Thema - Nächstes Thema

CoolTux

Danke Dir Rudi. Dann kann ich ja im laufe der Tage meine Packagenamen wieder entsprechend an passen.


Grüße
Du musst nicht wissen wie es geht! Du musst nur wissen wo es steht, wie es geht.
Support me to buy new test hardware for development: https://www.paypal.com/paypalme/MOldenburg
My FHEM Git: https://git.cooltux.net/FHEM/
Das TuxNet Wiki:
https://www.cooltux.net

Loredo

Vielen Dank für die Unterstützung, Rudi.

Ich habe nun den FHEM Package Support auch entsprechend eingebaut.
Damit ist die Auswertung aller vorhandenen Datenquellen nun wohl soweit vollständig denke ich.

Als Modulentwickler ist es interessant, wenn man im FHEM Installer ein "Get search .+" ausführt. Vorausgesetzt man hat auch Perl::PrereqScanner::NotQuiteLite installiert, kann man nun beispielsweise sehen, welche externen Perl Module von welchem FHEM Modul oder FHEM Package verwendet werden. Das dürfte vielleicht für die zukünftige Wahl, welchen XML Parser man beispielsweise nehmen möchte, helfen, damit man nicht noch einen anderen nimmt  8)  (siehe Screenshot "xml.png").

Man sieht aber natürlich auch, welche FHEM Packages von welchen FHEM Modulen verwendet werden.
Außerdem lassen sich FHEM Packages genauso dokumentieren, wie FHEM Module.

Hier einmal eine Liste aller Infos, die die Suche berücksichtigt:

- Device Namen
- Module Namen
- Package Namen
- Keywords und die Modules/Packages, welche dieses Keyword führen (inkl. einigen generierten Standard Keywords, bspw. aus der Forum Kategorie oder der Update Quelle, aber auch dem Module Type device/command/helper)
- Maintainer Namen und die von ihnen verwalteten FHEM Modules und FHEM Packages
- Perl Packages, die von FHEM Modulen und/oder FHEM Packages verwendet werden

Interessehalber: Das hier ist wahrscheinlich eine ziemlich vollständige Liste aller externen Perl Pakete für FHEM Core:


Authen::OATH
Authen::SASL
AutoLoader
B
base
bignum
bytes
Compress::Zlib
Config
constant
Convert::Base32
Crypt::CBC
Crypt::Cipher::AES
Crypt::ECB
Crypt::Mode::CBC
Crypt::Mode::CTR
Crypt::MySQL
Crypt::OpenSSL::AES
Crypt::OTR
Crypt::Random
Crypt::Rijndael
Crypt::Rijndael_PP
Crypt::URandom
Cwd
Data::Dumper
Data::UUID
Date::Parse
DateTime
DBI
DBI::Const::GetInfoType
Devel::Size
Device::SerialPort
Device::SMBus
Device::USB
Digest::CRC
Digest::MD5
Digest::SHA
Digest::SHA1
Encode
Encode::Guess
Exporter
Fcntl
feature
File::Basename
File::Copy
File::Find
File::Path
File::Spec
File::Spec::Functions
File::stat
File::Temp
GD
GD::Text::Align
GD::Text::Wrap
Getopt::Std
HiPi::Device::I2C
HTML::Entities
HTML::Parser
HTML::TreeBuilder::XPath
HTTP::Cookies
HTTP::Request
HTTP::Request::Common
Image::Info
Image::LibRSVG
Inline
Inline::Python
IO::Compress::Gzip
IO::File
IO::Handle
IO::Interface::Simple
IO::Select
IO::Socket
IO::Socket::INET
IO::Socket::INET6
IO::Socket::Multicast
IO::Socket::Multicast6
IO::Socket::SSL
IO::Socket::Timeout
IO::Socket::UNIX
IO::Uncompress::Gunzip
IO::Uncompress::Unzip
JSON
JSON::XS
lib
Linux::Inotify2
Lirc::Client
List::MoreUtils
List::Util
longer
LWP
LWP::Simple
LWP::UserAgent
Mail::GnuPG
Mail::IMAPClient
Math::Round
Math::Trig
MIME::Base64
MIME::Lite
MIME::Parser
Mojolicious
Net::Address::IP::Local
Net::Bonjour
Net::Domain
Net::FTP
Net::FTPSSL
Net::MQTT::Message
Net::OAuth
Net::Ping
Net::SIP::Packet
Net::SMTP
Net::SMTP::SSL
Net::SNMP
Net::SSLeay
Net::Telnet
Net::UPnP::AV::MediaRenderer
Net::UPnP::AV::MediaServer
Net::UPnP::ControlPoint
Net::UPnP::Device
Net::UPnP::Service
Net::XMPP::Namespaces
Nmap::Parser
OW
Path::Tiny
perl
Perl::PrereqScanner::NotQuiteLite
PerlIO::encoding
POSIX
RiveScript
RPC::XML::Client
RPC::XML::Server
Scalar::Util
SOAP::Lite
Socket
Socket6
Storable
strict
Switch
Symbol
Sys::Hostname
Sys::Statistics::Linux::DiskUsage
Sys::Statistics::Linux::LoadAVG
Text::Balanced
Text::Diff
Text::ParseWords
Thread::Queue
threads
threads::shared
Time::HiRes
Time::Local
Time::Piece
Try::Tiny
UPnP::ControlPoint
URI::Escape
utf8
vars
version
warnings
Win32::Console
Win32::Daemon
Win32::SerialPort
WWW::Jawbone::Up
XML::LibXML
XML::Simple
XML::XPath
XML::XPath::XMLParser
Hat meine Arbeit dir geholfen? ⟹ https://paypal.me/pools/c/8gDLrIWrG9

Maintainer:
FHEM-Docker Image, https://github.com/fhem, Astro(Co-Maintainer), ENIGMA2, GEOFANCY, GUEST, HP1000, Installer, LaMetric2, MSG, msgConfig, npmjs, PET, PHTV, Pushover, RESIDENTS, ROOMMATE, search, THINKINGCLEANER

DS_Starter

Hallo Julian,

Frage zum Wiki-Eintrag. Der Installer verweist meines Wissens immer zu einem Wiki-Eintrag der ganauso heißt wie das Modul.
Das trifft zumindest bei meinen Modulen nicht so zu. Die Wiki Seiten sind ergänzt.
Kann man als Autor einen x_ Eintrag in Meta.json auf die richtige Wiki-Seite hinterlegen ?

Grüße
Heiko
ESXi@NUC+Debian+MariaDB, PV: SMA, Victron MPII+Pylontech+CerboGX
Maintainer: SSCam, SSChatBot, SSCal, SSFile, DbLog/DbRep, Log2Syslog, SolarForecast,Watches, Dashboard, PylonLowVoltage
Kaffeekasse: https://www.paypal.me/HMaaz
Contrib: https://svn.fhem.de/trac/browser/trunk/fhem/contrib/DS_Starter

Loredo

Zitat von: DS_Starter am 23 März 2019, 17:14:44
Frage zum Wiki-Eintrag. Der Installer verweist meines Wissens immer zu einem Wiki-Eintrag der ganauso heißt wie das Modul.
Das trifft zumindest bei meinen Modulen nicht so zu. Die Wiki Seiten sind ergänzt.
Kann man als Autor einen x_ Eintrag in Meta.json auf die richtige Wiki-Seite hinterlegen ?


Ja, sobald du in deinem META.json selbst einen Wert setzt, wird dieser nicht mehr automatisch generiert oder überschrieben.
Wie du einen Eintrag setzt, siehst du am einfachsten, wenn du in $modules{TYPE}{META} bzw. im FHEM Installer mit "Get zzModuleMETA.json" nachschaust. Im konkreten Fall für das Wiki wäre der Eintrag wie folgt:



{
"resources": {
   "x_wiki": {
     "web": "https://wiki.fhem.de/wiki/MeineWikiSeite",
     "title": "Wenn ich noch einen besonderen Titel haben möchte"
   }
}
}



'title' ist optional und bekommt, wenn gesetzt, automatisch "FHEM Wiki:" als Präfix, wenn die URL wiki.fhem.de enthält.
Hat meine Arbeit dir geholfen? ⟹ https://paypal.me/pools/c/8gDLrIWrG9

Maintainer:
FHEM-Docker Image, https://github.com/fhem, Astro(Co-Maintainer), ENIGMA2, GEOFANCY, GUEST, HP1000, Installer, LaMetric2, MSG, msgConfig, npmjs, PET, PHTV, Pushover, RESIDENTS, ROOMMATE, search, THINKINGCLEANER

DS_Starter

Danke Julian, schau ich mir an.

LG,
Heiko
ESXi@NUC+Debian+MariaDB, PV: SMA, Victron MPII+Pylontech+CerboGX
Maintainer: SSCam, SSChatBot, SSCal, SSFile, DbLog/DbRep, Log2Syslog, SolarForecast,Watches, Dashboard, PylonLowVoltage
Kaffeekasse: https://www.paypal.me/HMaaz
Contrib: https://svn.fhem.de/trac/browser/trunk/fhem/contrib/DS_Starter

DS_Starter

#65
Hi Julian,

habe x_wiki für DbRep mal ausprobiert. So definiert:


  "resources": {
    "x_wiki": {
      "web": "https://wiki.fhem.de/wiki/DbRep_-_Reporting_und_Management_von_DbLog-Datenbankinhalten",
      "title": "DbRep - Reporting und Management von DbLog-Datenbankinhalten"
    }
  }

Der Link im Installer verweist aber auf die Seite:
https://wiki.fhem.de/wiki/DbRep_-_Reporting_und_Management_von_DbLog-Datenbankinhalten/

was nicht funktionert. Richtig wäre wie angegeben:
https://wiki.fhem.de/wiki/DbRep_-_Reporting_und_Management_von_DbLog-Datenbankinhalten

Also ohne "/" am Ende.

Grüße,
Heiko
ESXi@NUC+Debian+MariaDB, PV: SMA, Victron MPII+Pylontech+CerboGX
Maintainer: SSCam, SSChatBot, SSCal, SSFile, DbLog/DbRep, Log2Syslog, SolarForecast,Watches, Dashboard, PylonLowVoltage
Kaffeekasse: https://www.paypal.me/HMaaz
Contrib: https://svn.fhem.de/trac/browser/trunk/fhem/contrib/DS_Starter

Loredo

Den Fix dafür habe ich vorhin schon eingecheckt  ;D
Hat meine Arbeit dir geholfen? ⟹ https://paypal.me/pools/c/8gDLrIWrG9

Maintainer:
FHEM-Docker Image, https://github.com/fhem, Astro(Co-Maintainer), ENIGMA2, GEOFANCY, GUEST, HP1000, Installer, LaMetric2, MSG, msgConfig, npmjs, PET, PHTV, Pushover, RESIDENTS, ROOMMATE, search, THINKINGCLEANER

DS_Starter

Moin Julian,

habe gerade upgedated. Das Wiki-Verhalten ist aber immer noch so wie in #65 beschrieben.

Grüße
Heiko
ESXi@NUC+Debian+MariaDB, PV: SMA, Victron MPII+Pylontech+CerboGX
Maintainer: SSCam, SSChatBot, SSCal, SSFile, DbLog/DbRep, Log2Syslog, SolarForecast,Watches, Dashboard, PylonLowVoltage
Kaffeekasse: https://www.paypal.me/HMaaz
Contrib: https://svn.fhem.de/trac/browser/trunk/fhem/contrib/DS_Starter

Loredo

Ups, hab ich offenbar nicht eingecheckt  :-[
Ist beim jetzigen Update mit dabei.
Hat meine Arbeit dir geholfen? ⟹ https://paypal.me/pools/c/8gDLrIWrG9

Maintainer:
FHEM-Docker Image, https://github.com/fhem, Astro(Co-Maintainer), ENIGMA2, GEOFANCY, GUEST, HP1000, Installer, LaMetric2, MSG, msgConfig, npmjs, PET, PHTV, Pushover, RESIDENTS, ROOMMATE, search, THINKINGCLEANER

DS_Starter

Ja, jetzt sieht es gut aus ... gleich probiert  :D
ESXi@NUC+Debian+MariaDB, PV: SMA, Victron MPII+Pylontech+CerboGX
Maintainer: SSCam, SSChatBot, SSCal, SSFile, DbLog/DbRep, Log2Syslog, SolarForecast,Watches, Dashboard, PylonLowVoltage
Kaffeekasse: https://www.paypal.me/HMaaz
Contrib: https://svn.fhem.de/trac/browser/trunk/fhem/contrib/DS_Starter

Loredo

#70
Ich habe auf Anregung von André nun 2 META.json Beispieldateien unter contrib eingecheckt:

https://svn.fhem.de/trac/browser/trunk/fhem/contrib/META.json.txt
https://svn.fhem.de/trac/browser/trunk/fhem/contrib/META.json.full.txt






Die erste Datei soll einen einfachen Einstieg für die Definition des JSON Baums liefern.

Sie ist darauf ausgelegt, dass ein Modul im SVN liegt und mit zusätzlichen Daten ergänzt werden soll. Man muss aber auch davon nicht alles setzen, wirklich wichtig ist nur die Sektion "prereqs" - alles andere kann im Falle eines FHEM Core Moduls auch über SVN ermittelt werden. Beim befüllen von prereqs ist im Grunde nur darauf zu achten, dass es hierbei um sämtliche "use xyz" und "require xyz" Anweisungen geht, die man im Modul an irgendeiner Stelle verwendet. Der Vollständigkeit halber dürfen das auch explizit Dinge wie "use strict" sein. 98_Installer berücksichtigt das entsprechend bei Anzeige und Auswertung. Ein Querverweis auf andere FHEM Module sollte hier nur erfolgen, wenn dieses FHEM Modul tatsächlich mit "package FHEM::modulname" arbeitet und das eigene Modul eine Funktion aus dem anderen Package aufruft. Sprich, eine rein logische Beziehung zwischen zwei FHEM Modulen soll hier explizit _nicht_ hinein, dafür überlege ich mir noch eine separate Nomenklatur (und da gibt es ja auch durchaus mehr Fälle zu dokumentieren). FHEM Packages wie HttpUtils oder DevIO gehören hier selbstverständlich hinein, ganz gleich ob dieses FHEM Package auf "package main;" oder "package packagename;" oder "package FHEM::packagename;" setzt. Entscheidend ist dabei aber, dass wie gesagt der Eintrag so lautet, wie man das Package auch bei sich über use/require einbindet. Beispielsweise ist der Querverweis auf "FHEM::Meta" korrekt, nur "Meta" jedoch nicht (Bravo, Heiko!  8) ). Ich weiß, dass der Installer dabei noch einen Link ins leere setzt, das fixe ich demnächst noch. ;D

Die Einsortierung in "requires", "recommends" und "suggests" bleibt ganz dem Modulautor überlassen. Wenn etwas woanders als in "requires" einsortiert wird, sollte das FHEM Modul natürlich so geschrieben sein, dass es auch ohne diese Perl Module klarkommt. Nicht sinnvoll ist beispielsweise, dass ein Modul zwar eigentlich ein Perl Modul wie "XML::Simple" zwingend braucht, bei fehlender Installation jedoch ein eigenes Errorhandling hat wie beispielsweise der Textausgabe "please install XML::Simple first". In diesem Fall ist XML::Simple selbstverständlich unter "requires" einzutragen. Die automatische Erkennung in Meta.pm sortiert solche Abhängigkeiten in solchen Fällen in "suggests" ein, weil eben auch erkannt wird, dass das Modul ein Errorhandling macht und es aus dieser Sicht heraus ja eigentlich funktioniert.  ;)
Eigenes Errorhandling ist in diesem Fall also eher "schlimm", zumal fhem.pl ja schon seit geraumer Zeit nicht mehr abstürzt, sondern ebenfalls die (dann etwas kryptischere) Perl Fehlermeldung ausgibt. Außerdem ist langfristig mal vorgesehen, dass Meta.pm für den Modulautor die dort aufgelisteten Perl Module automatisch läd, so dass man sie auch nicht mehr doppelt und dreifach pflegen muss (aber natürlich kann). Das soll dann gekoppelt werden können damit, dass beim "define" eben auch geprüft wird, ob alle Abhängigkeiten vorhanden sind und falls nein, angeboten wird den Installer für die Installation zu starten.
Noch Zukunftsmusik, aber soviel zur Planung.

Wer der Übersicht etwas Gutes tun möchte, der definiert noch einige zusätzliche Keywords. Sie werden bei Benutzung der Suche im Installer (oder des FHEM Befehls "search") entsprechend mit durchsucht. So kann ein Modul beispielsweise den Hersteller als Schlüsselwort mit aufnehmen und es ist dann zusätzlich darüber auffindbar. Nicht sinnvoll ist hier einen String als Keyword zu wiederholen, der bereits im Modulnamen enthalten ist, da die Suche über den Modulnamen bereits zum gleichen Ergebnis führt. Auch nicht unbedingt notwendig ist, die mit "fhem-" automatisch von Meta.pm generierten Keywords zu wiederholen. Sie werden bei im SVN dem Core zugehörigen Modulen ohnehin automatisch ermittelt. Solange wir die "legacy POD" Definitionen unter "=item [helper|device|command]" noch haben, muss man nicht unbedingt doppelt pflegen (wer aber die Meinung teilt, dass das statische JSON im File auch schon möglichst aussagekräftig sein sollte, darf das natürlich trotzdem machen  ;) ).

Die Datei META.json.txt enthält nur reines JSON, um der Einfachkeit halber auch direkt JSON Validatoren direkt anwenden zu können.






Die zweite Datei META.json.full.txt soll eine Blaupause sämtlicher möglicher Angaben sein, die man so für ein FHEM Modul (oder FHEM Entwickler-Package, natürlich) machen kann. Deshalb ist dort der gesamte "=pod ... =cut" Abschnitt mit enthalten. Er zeigt auch, wie META.json.txt sich im Gesamtkonstrukt einbindet (z.B. welche POD Definition man innerhalb der Moduldatei braucht). Ich konnte bisher kein Template für die CommandRef finden und habe daher mal versucht selbst das HTML Grundgerüst dort hinein zu schreiben. Ich habe dabei bei Modulen von Rudi gespickt und wollte eigentlich ein Template haben, was dann auch ermöglicht, dass die Beschreibung von Attributen in FHEMWEB in der Detailübersicht mit angezeigt werden kann, wenn man das Attribut ausgewählt hat. Aber irgendwie gibt es da glaube ich einen Konflikt zwischen dem Ankerpunkt für die Seitennavigation (Name ist mit # am Anfang) und der Kennzeichnung, wo die Attribut Beschreibung beginnt (Name hat kein # am Anfang, beispielsweise in der CommandRef von FHEMWEB).

Wie man an der Gesamtübersicht aller META.json Attribute gut erkennen kann, sind viele vor allem darauf ausgelegt, dass ein Modul auch nicht zu FHEM Core gehört (also nicht im SVN liegt). Aber natürlich kann es auch für ein FHEM Core Modul sinnvoll sein z.B. einen Verweis auf einen Bugtracker zu hinterlegen, wenn der Maintainer seine Todo Liste irgendwo pflegt (z.B. Github Issues, aber natürlich auch sonstwo anders). Auch der Verweis auf ein zweites Repository für die Dev-Version kann man machen (theoretisch auch auf einen separaten/neuen Branch im FHEM SVN).

Der Repository Bereich ist derzeit noch etwas mit Vorsicht zu genießen, ich bin noch nicht ganz sicher, welche Rolle bspw. x_raw (Verweis auf die Moduldatei im reinen Textformat) mal für das Update eines extern gehosteten 3rd-party FHEM Moduls spielen kann (wäre dann aber auch ein komplett separater Update Mechanismus neben dem contrib_*.txt Format, welches dann eher auf META.json setzen würde). Auch hier: Zukunftsmusik.

Vielleicht auch momentan eher von theoretischer Natur ist der Verweis auf den Support-Status (x_support_status) und die Markierung/Verlinkung eines kommerziellen FHEM Moduls (x_support_commercial). Ich habe diese Möglichkeit einfach mal vorgesehen, auch vor dem Hintergrund, dass es im Forum ja inzwischen Sektionen für kommerzielle Produkte gibt. Ein Modul kann somit ebenfalls entsprechend gekennzeichnet werden.
Hat meine Arbeit dir geholfen? ⟹ https://paypal.me/pools/c/8gDLrIWrG9

Maintainer:
FHEM-Docker Image, https://github.com/fhem, Astro(Co-Maintainer), ENIGMA2, GEOFANCY, GUEST, HP1000, Installer, LaMetric2, MSG, msgConfig, npmjs, PET, PHTV, Pushover, RESIDENTS, ROOMMATE, search, THINKINGCLEANER

nils_

Zitat von: Loredo am 02 April 2019, 14:59:41
Ich konnte bisher kein Template für die CommandRef finden und habe daher mal versucht selbst das HTML Grundgerüst dort hinein zu schreiben.
vorab: ich hab mir deine dateien nicht angeschaut  ::)

aber meinst du mit template für die cref dieses hier:
https://svn.fhem.de/trac/browser/trunk/fhem/docs/commandref_frame.html
bzw. https://svn.fhem.de/trac/browser/trunk/fhem/docs/commandref_frame_DE.html
viele Wege in FHEM es gibt!

Loredo

Nee, das ist ja nur der Header.
Gemeint ist schon der Teil, der in den Moduldateien drin steht.
Hat meine Arbeit dir geholfen? ⟹ https://paypal.me/pools/c/8gDLrIWrG9

Maintainer:
FHEM-Docker Image, https://github.com/fhem, Astro(Co-Maintainer), ENIGMA2, GEOFANCY, GUEST, HP1000, Installer, LaMetric2, MSG, msgConfig, npmjs, PET, PHTV, Pushover, RESIDENTS, ROOMMATE, search, THINKINGCLEANER

DS_Starter

Hallo Julian,

im DbLog-Modul braucht man unterschiedliche, Datenbank spezifische Perl-Bibliotheken, je nach dem Typ der DB die man einsetzen möchte.
Nun überlege ich wie man die Requirements hinterlegen könnte um nur den jeweils benötigten Treiber bei Installer anzuzeigen. Momentan fällt mir nichts dazu ein. Hast du eine Idee ?
Sonst müsste ich alle angeben, was aber wiederum unschön ist weil der User dann u.U. etwas nachinstalliert was er nicht braucht. Naja, wäre jetzt auch nicht so dramatisch.

LG,
Heiko
ESXi@NUC+Debian+MariaDB, PV: SMA, Victron MPII+Pylontech+CerboGX
Maintainer: SSCam, SSChatBot, SSCal, SSFile, DbLog/DbRep, Log2Syslog, SolarForecast,Watches, Dashboard, PylonLowVoltage
Kaffeekasse: https://www.paypal.me/HMaaz
Contrib: https://svn.fhem.de/trac/browser/trunk/fhem/contrib/DS_Starter

Loredo

#74
Da man für das Modul mindestens einen Datenbanktyp braucht, würde ich den am häufigsten verwendeten Connector als "requires" definieren (z.B. SQLite). Vielleicht macht auch MySQL noch Sinn.
Die restlichen würde ich quasi gleichberechtigt als "recommends" hinterlegen.


Der Installer wird später ohnehin anbieten, requires + recommends zusammen zu installieren. So differenziert nach unterschiedlichen Datenbanktypen muss das IMHO wirklich nicht sein... Die 'suggests' Items wird der Installer dann wie "recommends" behandeln, wenn das Modul keine Metadaten geliefert hat und die Information über den Scanner kommt. Ansonsten wird 'suggests' nur nach explizitem User Wunsch installiert werden.
Das alles betrifft natürlich hauptsächlich die automatisierte/gescriptete Installation (z.B. im Docker Container später). Die interaktive Installation über den Browser soll flexibler sein.
Hat meine Arbeit dir geholfen? ⟹ https://paypal.me/pools/c/8gDLrIWrG9

Maintainer:
FHEM-Docker Image, https://github.com/fhem, Astro(Co-Maintainer), ENIGMA2, GEOFANCY, GUEST, HP1000, Installer, LaMetric2, MSG, msgConfig, npmjs, PET, PHTV, Pushover, RESIDENTS, ROOMMATE, search, THINKINGCLEANER