Текущая версия от 17:43, 4 декабря 2017

Отладка модулей alterator

Уровни отладки

alteratord

Начиная с alterator-4.0-alt1 (сентябрь 2008), существует сервис alteratord, отвечающий за взаимодействие с бэкендами; для более удобной отладки с возможностью наблюдения stderr бэкендов следует выполнить:

service alteratord stop
alteratord -l -d

ahttpd

Для отладки веб-интерфейса запустите ahttpd локально:

service alteratord stop
service ahttpd stop
ahttpd -l

Бэкенды

Для отладки вызова бэкендов используйте alterator-cmdline локально:

killall -15 alteratord
alterator-cmdline -l <модуль> action <название действия>...
cat /var/run/alteratord/alteratord.log

alterator-browser-qt

alterator-standalone -l <имя модуля>

Запуск без параметров выведет список всех доступных модулей.

Распространённые ошибки при работе с внешними бэкендами

Внешние бэкенды альтератора (backend3) общаются с ядром через stdin/stdout. С одной стороны — это очень хорошо, с другой — частенько порождает сложно понимаемые ошибки.

Список перечисленных ниже известных проблем является одновременно и пожеланием к будущим внешним бэкендам (backend4).

Паразитный вывод от утилит — некоторые утилиты могут неожиданно для автора бэкенда произвести печать чего-нибудь на stdout. В результате альтератор воспримет это как ответ. В результате может быть выдано сообщение об неподдерживаемой команде («unknown action for backend») или, что ещё хуже, alterator просто зависнет. Последнее может происходить в случае, когда утилита выдала на stdout кавычку, двойную кавычку или скобку, и alterator начинает ожидать завершения строки.
Отсутствие ответа — можно ошибиться и какая-нибудь из утилит (например grep), будет висеть и в месте с ней будет висеть и весь alterator.
Два ответа вместо одного — alterator не сбрасывает буфер чтения перед началом чтения очередного ответа от бэкенда, поэтому если бэкенд ответил два раза, ядро и бэкенд начинают работать в «противофазе» выдавая неожиданные ответы в неожиданных местах. Внешне всё выглядит как будто модуль то работает, а то не работает.
Неверный формат вывода списка — давным давно alterator стал использовать для вывода списков странную систему, в которой в отличие от остальных случаев первым идёт строка с именем. Пользователи не читают документацию, поэтому часто вместо '("a" param "pam-pam") выводят '(name "a" param "pam-pam") … в результате бэкенд не работает.
Неверный тип данных в ответе — бэкенд принимает всё как строки, а вот отдаёт уже данные типизированные в формате scheme. Если вы выдадите не тот тип, то может рухнуть не очень аккуратно написанный код где-нибудь в ядре (по этому поводу надо сразу же повесить сообщение об ошибке). А если забудете о квотировании строк, то всё может просто-напросто повиснуть, ожидая окончание строки.
Несоответствие бэкенда правилам workflow — в HTML интерфейсе автоматические workflow (такие как form и card-index) требуют определённого подхода к размещению параметров в «дереве» бэкенда. В GUI вся динамика пока пишется вручную, поэтому там это не так критично.

Вставка отладочных сообщений

Из бэкендов

Во внешних бэкендах остаётся свободным stderr, поэтому можно выводить отладочные сообщения именно туда. В нативных бэкендах и во всём остальном alterator свободны и stdout и stderr.

echo "$(set|grep -a "in_")" >&2

Из Scheme

Для вывода в коде scheme рекомендуется использовать функцию format. Например:

(format #t "debug-message:obj1=~S,obj2=~S~%" obj1 obj2) ; вывод на stdout
(format (current-error-port) "debug-message~%") ; вывод в stderr

Очень полезно отладить бэкенд сначала в интерфейсе командной строки, а потом уже проверять как он работает в других более сложных интерфейсах — так будет проще найти виноватого.

Внимание! Вывод stderr не выводится на экран, а записывается в файл /var/run/alteratord/alteratord.log

Интерпретация некоторых загадочных сообщений

Если по какой-то причине вы получаете нечто подобное в fbi:

key=wrong-type-arg,args=("string-append" "Wrong type argument (expecting ~A): ~S" ("STRINGP" adduser) #f)

Это означает, что ваш backend спросили, а он вернул просто слово, а не строку. Для того чтобы понять, что же спрашивают, следует использовать в backend’е следующую конструкцию:

on_message()
echo "имя_вашего_модуля= $(date +%H/%M/%S): action=$in_action and objects=$in__objects" >> /tmp/alterator-debug.txt 2>&1

Теперь, если заглянуть в файл /tmp/alterator-debug.txt, то можно видеть, каков был последний запрос; например:

имя_модуля= 00/33/22: action=read and objects=/someobject

Далее стоит произвести следующую диагностику:

alterator-cmdline /имя_модуля/someobject action read
/usr/share/guile/1.6/alterator/exit-handler.scm:19:7: In procedure string-append in expression (apply throw args):
/usr/share/guile/1.6/alterator/exit-handler.scm:19:7: Wrong type argument (expecting STRINGP): что-то тут

На самом деле ответ должен выглядеть как-нибудь так (полностью зависит от вашей реализации модуля, это мой пример):

(("/имя_модуля/someobject" name "что-то тут"))

Обратите особое внимание на "что-то тут" — если писать на shell, то обычно кавычки забывают передать; следует использовать не "string", а "\"string\"" или ближе к практике — printf '(param "%s")' "$param"

@@ Строка 1: / Строка 1: @@
-[[Category:Sisyphus]]
+[[Категория:Sisyphus]]
-{{MovedFromFreesourceInfo|AltLinux/Sisyphus/Alterator/debug}}
+[[category:alterator|debug]]
-== Отладка модулей alterator ==
+= Отладка модулей alterator =
 __TOC__
+== Уровни отладки ==
-==== Распространённые ошибки при работе с внешними бэкендами. ====
+=== alteratord ===
+Начиная с alterator-4.0-alt1 (сентябрь 2008), существует сервис {{cmd|alteratord}}, отвечающий за взаимодействие с бэкендами; для более удобной отладки с возможностью наблюдения stderr бэкендов следует выполнить:
+ service alteratord stop
+ alteratord -l -d
-Внешние бэкенды альтератора (backend3) общаются с ядром через stdin/stdout. С одной стороны - это очень хорошо, с другой - частенько порождает сложно понимаемые ошибки. <div style="display: inline; color: red;">Список перечисленных ниже известных проблем является одновременно и пожеланием к будущим внешним бэкендам (backend4).</div>
+=== ahttpd ===
+Для отладки веб-интерфейса запустите {{cmd|ahttpd}} локально:
+ service alteratord stop
+ service ahttpd stop
+ ahttpd -l
-. '''Паразитный вывод от утилит''' - некоторые утилиты могут неожиданно для автора бэкенда произвести печать чего-нибудь на stdout. В результате альтератор воспримет это как ответ. В результате может быть выдано сообщение об неподдерживаемой команде ("<tt>unknown action for backend</tt>") или, что ещё хуже, alterator просто зависнет. Последнее может происходить в случае, когда утилита выдала на stdout кавычку, двойную кавычку или скобку, и alterator начинает ожидать завершения строки.
+=== Бэкенды ===
+Для отладки вызова бэкендов используйте {{cmd|alterator-cmdline}} локально:
+ killall -15 alteratord
+ alterator-cmdline -l <модуль> action <название действия>...
+ cat /var/run/alteratord/alteratord.log
-. '''Отсутствие ответа''' - можно ошибиться и какая-нибудь из утилит (например grep), будет висеть и в месте с ней будет висеть и весь alterator.
+=== alterator-browser-qt ===
+ alterator-standalone -l <имя модуля>
-. '''Два ответа вместо одного''' - alterator не сбрасывает буфер чтения перед началом чтения очередного ответа от бэкенда, поэтому если бэкенд ответил два раза, ядро и бэкенд начинают работать в "противофазе" выдавая неожиданные ответы в неожиданных местах. Внешне всё выглядит как будто модуль то работает, а то не работает.
+Запуск без параметров выведет список всех доступных модулей.
-. '''Неверный формат вывода списка''' - давным давно alterator стал использовать для вывода списков странную систему, в которой в отличие от остальных случаев первым идёт строка с именем. Пользователи не читают документацию, поэтому часто вместо '("a" param "pam-pam") выводят '(name "a" param "pam-pam") ... в результате бэкенд не работает.
+== Распространённые ошибки при работе с внешними бэкендами ==
-. '''Неверный тип данных в ответе''' - бэкенд принимает всё как строки, а вот отдаёт уже данные типизированные в формате scheme. Если вы выдадите не тот тип, то может рухнуть не очень аккуратно написанный код где-нибудь в ядре (<div style="display: inline; color: red;">по этому поводу надо сразу же повесить сообщение об ошибке</div>). А если забудете о квотировании строк, то всё может просто-напросто повиснуть, ожидая окончание строки.
+Внешние бэкенды альтератора (backend3) общаются с ядром через stdin/stdout. С одной стороны — это очень хорошо, с другой — частенько порождает сложно понимаемые ошибки.
-. '''Несоответствие бэкенда правилам workflow''' - в HTML интерфейсе автоматические workflow (такие как form и card-index) требуют определённого подхода к размещению параметров в "дереве" бэкенда. В GUI вся динамика пока пишется вручную, поэтому там это не так критично.
-==== Вставка отладочных сообщений ====
+Список перечисленных ниже известных проблем является одновременно и пожеланием к будущим внешним бэкендам (backend4).
-Во внешних бэкендах остаётся свободным stderr, поэтому можно выводить отладочные сообщения именно туда. В нативных бэкендах и во всём остальном alterator свободны и stdout и stderr. Для вывода в коде scheme рекомендуется использовать функцию format. Например:
-<pre>(format #t "debug-message:obj1=~S,obj2=~S~%" obj1 obj2) ; вывод на stdout
-(format (current-error-port) "debug-message~%") ; вывод в stderr</pre>
-Очень полезно отладить бэкенд сначала в интерфейсе командной строки, а потом уже проверять как он работает в других более сложных интерфейсах - так будет проще найти виноватого.
-==== Интерпретация некоторых загадочных сообщений ====
+# '''Паразитный вывод от утилит''' — некоторые утилиты могут неожиданно для автора бэкенда произвести печать чего-нибудь на stdout. В результате альтератор воспримет это как ответ. В результате может быть выдано сообщение об неподдерживаемой команде («{{term|unknown action for backend}}») или, что ещё хуже, alterator просто зависнет. Последнее может происходить в случае, когда утилита выдала на stdout кавычку, двойную кавычку или скобку, и alterator начинает ожидать завершения строки.
-* Если по какой-то причине вы получаете, нечто подобное в fbi
+# '''Отсутствие ответа''' — можно ошибиться и какая-нибудь из утилит (например grep), будет висеть и в месте с ней будет висеть и весь alterator.
+# '''Два ответа вместо одного''' — alterator не сбрасывает буфер чтения перед началом чтения очередного ответа от бэкенда, поэтому если бэкенд ответил два раза, ядро и бэкенд начинают работать в «противофазе» выдавая неожиданные ответы в неожиданных местах. Внешне всё выглядит как будто модуль то работает, а то не работает.
+# '''Неверный формат вывода списка''' — давным давно alterator стал использовать для вывода списков странную систему, в которой в отличие от остальных случаев первым идёт строка с именем. Пользователи не читают документацию, поэтому часто вместо {{term|'("a" param "pam-pam")}} выводят {{term|'(name "a" param "pam-pam")}} … в результате бэкенд не работает.
+# '''Неверный тип данных в ответе''' — бэкенд принимает всё как строки, а вот отдаёт уже данные типизированные в формате scheme. Если вы выдадите не тот тип, то может рухнуть не очень аккуратно написанный код где-нибудь в ядре (''по этому поводу надо сразу же повесить сообщение об ошибке''). А если забудете о квотировании строк, то всё может просто-напросто повиснуть, ожидая окончание строки.
+# '''Несоответствие бэкенда правилам workflow''' — в HTML интерфейсе автоматические workflow (такие как {{term|form}} и {{term|card-index}}) требуют определённого подхода к размещению параметров в «дереве» бэкенда. В GUI вся динамика пока пишется вручную, поэтому там это не так критично.
+== Вставка отладочных сообщений ==
+=== Из бэкендов ===
+Во внешних бэкендах остаётся свободным stderr, поэтому можно выводить отладочные сообщения именно туда. В нативных бэкендах и во всём остальном alterator свободны и stdout и stderr.
+<source lang="Bash">echo "$(set|grep -a "in_")" >&2</source>
+=== Из Scheme ===
+Для вывода в коде scheme рекомендуется использовать функцию format. Например:
+<source lang="Lisp">(format #t "debug-message:obj1=~S,obj2=~S~%" obj1 obj2) ; вывод на stdout
+(format (current-error-port) "debug-message~%") ; вывод в stderr</source>
+Очень полезно отладить бэкенд сначала в интерфейсе командной строки, а потом уже проверять как он работает в других более сложных интерфейсах — так будет проще найти виноватого.
+{{Attention|Вывод stderr не выводится на экран, а записывается в файл {{path|/var/run/alteratord/alteratord.log}}}}
+== Интерпретация некоторых загадочных сообщений ==
+* Если по какой-то причине вы получаете нечто подобное в fbi:
 <pre>key=wrong-type-arg,args=("string-append" "Wrong type argument (expecting ~A): ~S" ("STRINGP" adduser) #f)</pre>
-:Это означает, что ваш backend спросили, а он вернул просто слово, а не строку. Для того чтобы понять, что вас спросили,
+Это означает, что ваш backend спросили, а он вернул просто слово, а не строку. Для того чтобы понять, что же спрашивают, следует использовать в backend’е следующую конструкцию:
-:лучше всего использовать в вашем backend'е следующую конструкцию
 <pre>on_message()
 echo "имя_вашего_модуля= $(date +%H/%M/%S): action=$in_action and objects=$in__objects" >> /tmp/alterator-debug.txt 2>&1</pre>
-:Теперь, если заглянуть в файл '''/tmp/alterator-debug.txt''' то можно видеть, какой последним был запрос, допустим это было
+Теперь, если заглянуть в файл {{path|/tmp/alterator-debug.txt}}, то можно видеть, каков был последний запрос; например:
 <pre>имя_модуля= 00/33/22: action=read and objects=/someobject</pre>
-:Стоит произвести следующую диагностику
+Далее стоит произвести следующую диагностику:
 <pre>alterator-cmdline /имя_модуля/someobject action read
 /usr/share/guile/1.6/alterator/exit-handler.scm:19:7: In procedure string-append in expression (apply throw args):
 /usr/share/guile/1.6/alterator/exit-handler.scm:19:7: Wrong type argument (expecting STRINGP): что-то тут</pre>
-:На самом деле ответ должен выглядеть как-нибудь так (полностью зависит от вашей реализации модуля у меня это мой пример)
+На самом деле ответ должен выглядеть как-нибудь так (полностью зависит от вашей реализации модуля, это мой пример):
 <pre>(("/имя_модуля/someobject" name "что-то тут"))</pre>
-:Особое внимание на '''"что-то тут"''' -- кавычки, если писать на shell, то обычно кавычки забывают передать, используют конструкцию '''"string"''', а не '''"\"string\""'''
+Обратите особое внимание на {{term|"что-то тут"}} — если писать на {{prg|shell}}, то обычно кавычки забывают передать; следует использовать не {{cmd|"string"}}, а {{cmd|"\"string\""}} или ближе к практике — {{cmd|printf '(param "%s")' "$param"}}

Alterator/debug: различия между версиями