#language ar
== ما هي مكونات حزمة catkin؟ ==
كي تعتبر حزمة ما حزمة catkin يجب أن تحقق المتطلبات التالية:

 * يجب أن تحتوي الحزمة على ملف توصيف [[catkin/package.xml|catkin compliant package.xml]].
  * يجب أن يحتوي ملف التوصيف package.xml على معلومات أولية عن الحزمة.
 * يجب أن تحتوي الحزمة ملف بناء [[catkin/CMakeLists.txt|CMakeLists.txt which uses catkin]].
  * إن كانت الحزمة وسيطية [[catkin/package.xml#Metapackages|catkin metapackage]] فيجب أن تحتوي ملف بناء CMakeLists.txt مناسب.
 * كل حزمة يجب أن تحتوى في مجلد خاص بها.
  * أي لا يسمح باشتراك الحزم في مجلد واحد، ولا يسمح بوجود حزمة داخل حزمة.

أبسط شكل للحزمة يبدو على الشكل التالي:

{{{{{#!wiki code
<<Include(ar/ROS/Tutorials/catkin/CreatingPackage/code1)>>
}}}}}

== الحُزَم في فضاء عمل catkin ==
الطريقة المفضلة للتعامل مع حزم catkin هي استخدام [[catkin/workspaces| فضاء عمل catkin]]، لكن يمكن بناء حزم catkin بشكل مستقل. فضاء العمل في أبسط أشكاله يبدو كما يلي:

{{{{{#!wiki code
<<Include(ar/ROS/Tutorials/catkin/CreatingPackage/code2)>>
}}}}}

قبل متابعة هذا الدرس، أنشأ مجلداً فارغاً (كما في الدرس السابق [[ar/catkin/Tutorials/create_a_workspace| إنشاء فضل عمل catkin]]).

== إنشاء حزمة catkin ==
تبين الفقرات التالية كيفية استخدام الملف
[[catkin/commands/catkin_create_pkg|catkin_create_pkg]]
لإنشاء حزمة جديدة، وماذا يمكن أن تفعل بالحزمة بعد ذلك.

أولاً غير مسار موجه الأوامر إلى مجلد الرمازا المصدري (src) الذي أنشأته في الدرس السابق
[[catkin/Tutorials/create_a_workspace|إنشاء فضاء عمل catkin]]

{{{#!wiki left/blue
&lrm;# You should have created this in the Creating a Workspace Tutorial

&lrm;$ cd ~/catkin_ws/src
}}}

الآن استخدم التعليمة `catkin_create_pkg` لإنشاء حزمة اسمها 'beginner_tutorials' تعتمد على المكتبات std_msg، roscpp، rospy:

{{{#!wiki left/blue
&lrm;$ catkin_create_pkg beginner_tutorials std_msgs rospy roscpp
}}}

تنشئ هذه التعليمة مجلداً `beginner_tutorials` يحتوي على ملفي التوصيف
[[catkin/package.xml|package.xml]]
والبناء
[[catkin/CMakeLists.txt|CMakeLists.txt]].
واللذان تم ملؤهما بمعلومات مناسبة لاسم الحزمة والمكتبات المعتمدة عليها، وتعليمات مناسبة للبناء، وأخرى عن صاحب الحزمة.

تتطلب التعلمية `catkin_create_pkg` اسم الحزمة `package_name` واختيارياً أسماء المكتبات التي تعتمد الحزمة عليها، أي لها القالب التالي (لا تحاول تنفيذه):

{{{#!wiki left/blue
&lrm;# This is an example, do not try to run this
# catkin_create_pkg <package_name> [depend1] [depend2] [depend3]
}}}

تؤمن `catkin_create_pkg` وظائف متقدمة أكثر، موصفة في الرابط
[[catkin/commands/catkin_create_pkg]].

== بناء فضاء عمل catkin، والتصريح عن ملف الإعداد ==

ابنِ الحزم في فضاء عمل catkin باستخدام التعليمة:

{{{#!wiki left/blue
&lrm;$ cd ~/catkin_ws

&lrm;$ catkin_make
}}}

عندما تنتهي عملية البناء، نكون قد حصلنا على مجلد بناء `build` ومجلد تطوير `devel` داخل مجلد فضاء العمل (شبيه بمجلد التطوير في المسار `/opt/ros/$ROSDISTRO_NAME`).

لإضافة فضاء العمل إلى بيئة ROS يجب التصريح عن ملف الإعداد المنشأ تلقائياً في مجلد التطوير:

{{{#!wiki left/blue
&lrm;$ . ~/catkin_ws/devel/setup.bash
}}}

== مُعتَمَدات الحزمة ==

=== معتمدات المرتبة الأولى ==

عند استخدام  [[catkin/commands/catkin_create_pkg|catkin_create_pkg]]، تُؤمَّن بشكل تلقائي عدة مكتبات. تعتبر هذه المكتبات كمعتمدات من المرتبة الأولى. يمكن عرضها باستخدام أدوات {{{rospack}}}.

{{{#!wiki left/blue
&lrm;$ rospack depends1 beginner_tutorials 
}}}
 {{{
roscpp
rospy
std_msgs
}}}

كما ترى فإن القائمة المعروضة تحتوي العمتمدات نفسها التي ذكرناها عند إنشاء الحزمة باستخدام {{{catkin_create_pkg}}}.
هذه المعتمدات مخزنة داخل ملف التوصيف '''package.xml''':

{{{#!wiki left/blue
&lrm;$ roscd beginner_tutorials
$ cat package.xml
}}}
 {{{
<package format="2">
...
  <buildtool_depend>catkin</buildtool_depend>
  <build_depend>roscpp</build_depend>
  <build_depend>rospy</build_depend>
  <build_depend>std_msgs</build_depend>
...
</package>
}}}

=== المُعتمَدات غير المُباشَرة ===
في كثير من الأحيان يكون للمكتبة المعتمد عليها مكتبات أخرى تعتمد هي عليها. مثلاً rospy لها معتمداتها:

{{{#!wiki left/blue
&lrm;$ rospack depends1 rospy
}}}
 {{{
genpy
roscpp
rosgraph
rosgraph_msgs
roslib
std_msgs
}}}

كما يمكن للحزمة أن تمتلك معتمدات غير مباشرة. تسمح {{{rospack}}} وبشكل عودي recursively بتحديد المكتبات المعتمد عليها بشكلٍ متتالٍ nested.

{{{#!wiki left/blue
&lrm;$ rospack depends beginner_tutorials

cpp_common
rostime
roscpp_traits
roscpp_serialization
catkin
genmsg
genpy
message_runtime
gencpp
geneus
gennodejs
genlisp
message_generation
rosbuild
rosconsole
std_msgs
rosgraph_msgs
xmlrpcpp
roscpp
rosgraph
ros_environment
rospack
roslib
rospy
}}}

== تخصيص حزمتك ==
هذا الجزء من الدرس سينظر إلى الملفات المولدة باستخدام [[catkin/commands/catkin_create_pkg|catkin_create_pkg]] وتوصيفها سطراً بسطر، وكل مكون من هذه الملفات وكيفية تخصيصه.

=== تخصيص ملف التوصيف package.xml ===
ملف التوصيف المولد [[catkin/package.xml|package.xml]] يجب أن يكون في داخل مجلد الحزمة. لنبحث في داخل هذا الملف ومكوناته.

=== علامة التوصيف ===

أولاً حدث علامة التوصيف description tag:

<<GetTaggedCode(https://raw.github.com/ros/catkin_tutorials/master/create_package_generated/catkin_ws/src/beginner_tutorials/package.xml,xml,DESC,no_tag_newlines,global_lines)>>

غير التوصيف لأي شيء تريده، بجملة مختزلة، يفضل أن تكون قصيرة ومعبرة عن وظيفة الحزمة. في حال استحالة ذلك يمكن تقسيم الجملة إلى عدة جمل.

=== علامات المشرفين ===

ثم تأتي علامة المشرف maintainer tag:

<<GetTaggedCode(https://raw.github.com/ros/catkin_tutorials/master/create_package_generated/catkin_ws/src/beginner_tutorials/package.xml,xml,MAINTAINER,no_tag_newlines,global_lines)>>

تعتبر هذه العلامة ضرورية ومهمة للحزمة [[catkin/package.xml|package.xml]] لأنها تخبر المستخدمين الآخرين عن كيفية التواصل مع صاحب الحزمة. يجب إضافة مشرف واحد على الأقل، ويمكن إضافة أكثر من مشرف. اسم المشرف يكتب في عرض العلامة، أما بريده الإلكتروني فله علامة خاصة.

<<GetTaggedCode(https://raw.github.com/ros/catkin_tutorials/master/create_package_modified/catkin_ws/src/beginner_tutorials/package.xml,xml,MAINTAINER,no_tag_newlines,global_lines)>>

==== علامات الترخيص ====

تعتبر علامة الترخيص license مهمة

<<GetTaggedCode(https://raw.github.com/ros/catkin_tutorials/master/create_package_generated/catkin_ws/src/beginner_tutorials/package.xml,xml,LICENSE,no_tag_newlines,global_lines)>>

يسمح الترخيص بمعرفة ماذا يمكن أن يفعل المطور الآخر بهذه الحزمة، مثلاً يمكن أن يستخدمها لأغراض تطويرية وليس تجارية ، أو كليهما أو غير ذلك. من أشهر التراخيص المستخدمة:
 BSD, MIT, Boost Software License, GPLv2, GPLv3, LGPLv2.1, and LGPLv3.
يمكنك قراءة تفاصيل هذه التراخيص  في الرابط:
[[http://opensource.org/licenses/alphabetical|Open Source Initiative]].
في هذه الدروس سنستخدم ترخيص BSD لأن مكونات ROS الأخرى تستخدمه.

<<GetTaggedCode(https://raw.github.com/ros/catkin_tutorials/master/create_package_modified/catkin_ws/src/beginner_tutorials/package.xml,xml,LICENSE,no_tag_newlines,global_lines)>>

==== علامات المعتمدات ====

تقسم إلى عدة علامات:
`build_depend`، `buildtool_depend`، `exec_depend`، `test_depend`.
لمعرفة المزيد عنها انظر الرابط [[catkin/package.xml#Build.2C_Run.2C_and_Test_Dependencies|Catkin Dependencies]].
باعتبار أننا أضفنا المكتبات
`std_msgs`، `roscpp`، `rospy`
كقيم لتعليمة
[[catkin/commands/catkin_create_pkg|catkin_create_pkg]]،
ستبدو علامات المعتمدات كما يلي::

<<GetTaggedCode(https://raw.github.com/ros/catkin_tutorials/master/create_package_generated/catkin_ws/src/beginner_tutorials/package.xml,xml,DEPS,no_tag_newlines,global_lines)>>

كل المعتمدات قد أضيفت إلى علامة البناء `build_depend`، وإلى علامة أداء البناء `buildtool_depend` الخاصة بأداة catkin.
ولأننا نحتاج أن تكون كل مكتباتنا متوافرة لمحلتي البناء والتشغيل، فقد أضيفت ايضاً إلىعلامة التشغيل `exec_depend`:

<<GetTaggedCode(https://raw.github.com/ros/catkin_tutorials/master/create_package_modified/catkin_ws/src/beginner_tutorials/package.xml,xml,DEPS,no_tag_newlines,global_lines)>>

==== إنهاء package.xml ====

أخيراً يبدو ملف التوصيف
[[catkin/package.xml|package.xml]]
بدون أي تعليقات كما يلي:

<<GetTaggedCode(https://raw.github.com/ros/catkin_tutorials/master/create_package_modified/catkin_ws/src/beginner_tutorials/package.xml,xml,FULLTEXT,no_tag_newlines,global_lines)>>

=== تخصيص ملف البناء CMakeLists.txt ===
بعد الانتهاء من تخصيص ملف التوصيف [[catkin/package.xml|package.xml]] الذي يحوي معلومات وسيطة، يمكنك الانتقال إلى تخصيص ملف البناء.
إن الملف [[catkin/CMakeLists.txt|CMakeLists.txt]]
الذي أنشأ باستخدام التعليمة
[[catkin/commands/catkin_create_pkg|catkin_create_pkg]]
سيناقش في دروس لاحقة.