http://docs.kde.org/
назадОприлюднення результатів вашої роботидалі

Структура пакунка з додатком

Щоб зовнішні додатки можна було встановити належним чином, так, щоб вони працювали, їхня ієрархічна файлова структура має відповідати певним правилам.

Ієрархія файлів

Погляньмо на взірцеву ієрархію файлів у добре спланованому архіві додатка. Вам не обов’язково включати усі ці каталоги і/або файли, щоб додаток міг працювати (прочитайте цей підручник далі, щоб дізнатися про те, які з них є абсолютно необхідними), вважайте це прикладом «найліпшого підходу»: 

назва_додатка/
                inst/
                        rkward/
                                plugins/
                                        назва додатка.xml
                                        назва_додатка.js
                                        назва_додатка.rkh
                                        ...
                                po/
                                        ll/
                                                LC_MESSAGES/
                                                        rkward__назва_додатка_rkward.mo
                                        rkward__назва_додатка_rkward.ll.po
                                        rkward__назва_додатка_rkward.pot
                                tests/
                                        назва_набору_тестів/
                                                RKTestStandards.назва_якогось_тесту.rkcommands.R
                                                RKTestStandards.назва_якогось_тесту.rkout
                                                ...
                                        набір_тестів.R
                                назва_додатка.pluginmap
                                ...
        ChangeLog
        README
        AUTHORS
        LICENSE
        DESCRIPTION

Примітка

У цьому прикладі усі записи назва_додатка, назва_набору_тестів та назва_якогось_тесту слід замінити відповідними назвами у вашому додатку. Крім того, записом ll позначено код мови (наприклад «de», «en» або «es»).

Підказка

Вам не обов’язково створювати усю цю ієрархію файлів вручну. Якщо ви скористаєтеся функцією rk.plugin.skeleton() з пакунка rkwarddev, програма сама автоматично створить для вас усі потрібні файли і каталоги, окрім каталогу po, який створюється і керується скриптом перекладу.

Базові компоненти додатка

Обов’язковим є включення трьох файлів: одного .pluginmap, одного файла опису .xml додатка і одного файла .js додатка. Іншими словами, навіть каталог «plugins» є необов’язковим. Він лише допомагає упорядковувати файли, особливо, якщо ви включаєте до архіву декілька додатків або діалогових вікон, що, звичайно ж, можна робити. Ви можете використовувати будь-яку бажану кількість каталогів для файлів додатків, достатньо лише, щоб вони відповідали .pluginmap. Ви навіть можете включити декілька файлів .pluginmap, якщо це відповідає вашим потребам, але тоді їх усі слід включити до файла «назва_додатка.pluginmap».

У кожному пакунку R має бути коректний файл DESCRIPTION, який є критично важливим для розпізнавання RKWard пакунка як пакунка, що містить додаток. Більша частина відомостей, що містяться у цьому файлі, також потрібна для метаданих пакунка і для визначення залежностей, але у іншому форматі (докладний опис файла DESCRIPTION можна знайти у документації до R).

Окрім звичного вмісту, файл DESCRIPTION має також містити рядок «Enhances: rkward». Додавання цього рядка підкаже RKWard, що слід автоматично шукати додатки у пакунку, якщо його встановлено. Приклад файла DESCRIPTION: 

Package: SquaretheCircle
        Type: Package
        Title: Square the circle
        Version: 0.1-3
        Date: 2011-09-19
        Author: E.A. Dölle <doelle@eternalwondermaths.example.org>
        Maintainer: A. Assistant <alterego@eternalwondermaths.example.org>
        Enhances: rkward
        Description: Squares the circle using Heisenberg compensation.
        License: GPL
        LazyLoad: yes
        URL: http://eternalwondermaths.example.org/23/stc.html
        Authors@R: c(person(given="E.A.", family="Dölle", role="aut",
                        email="doelle@eternalwondermaths.example.org"),
                        person(given="A.", family="Assistant", role=c("cre",
                        "ctb"), email="alterego@eternalwondermaths.example.org"))

Підказка

Вам не потрібно писати цей файл вручну. Якщо ви скористаєтеся функцією rk.plugin.skeleton() з пакунка rkwarddev і вкажете потрібні дані за допомогою параметра «about», придатний до використання файл DESCRIPTION буде створено автоматично.

Додаткові відомості (необов’язкові)

Призначення файлів ChangeLog, README, AUTHORS, LICENSE є очевидним з їхніх назв. Ці файли не є обов’язковими. Зокрема, вони не оброблятимуться RKWard, отже, там зберігатимуться додаткові дані, які можуть знадобитися, наприклад, супровідникам пакунків для дистрибутивів. Більшість вмісту цих файлів (подяки авторам, умови ліцензування тощо) за будь-яких умов буде включено у файли самого додатка (див. розділ щодо метаінформації). Зауважте, що усі ці файли також можна розмістити десь у каталозі «inst», якщо ви хочете, щоб вони були не лише у архіві з початковими кодами додатків, але і у встановленому пакунку.

Автоматичне тестування додатка (обов’язкове)

Ще одним необов’язковим каталогом є каталог «tests». У цьому каталозі можуть міститися файли, потрібні для автоматизованої системи тестування додатків. Такі тести корисні для пришвидшення визначення того, чи є ваші додатки працездатними у нових версіях R або RKWard. Якщо ви маєте намір включити до пакунка тести, вам слід жорстко дотримуватися наведеної у цьому підручнику схеми найменувань та ієрархії. Тобто, ваші тести мають зберігатися у каталозі із назвою tests, у якому має бути файл testsuite.R і тека із стандартами тестів, назва якої має збігатися із назвою відповідного комплексу тестів. Якщо ви не хочете збирати усі тести до одного файла testsuite.R, ви можете поділити їх так, щоб на кожен комплекс тестів припадав один файл, і створити один testsuite.R із викликами source() для кожного з файлів комплексу. За будь-яких умов, створіть окремі підкаталоги із стандартами тестування для кожного визначеного комплексу.

Перевагою дотримання такої структури є те, що тестування додатка можна запустити простим викликом з додатковими аргументами функції rktests.makplugintests() з пакунка rkwardtests. Докладніший опис можна знайти у документації щодо автоматичного тестування додатків.