Fix typos
[babeltrace.git] / include / babeltrace2 / graph / component-class.h
1 /*
2 * SPDX-License-Identifier: MIT
3 *
4 * Copyright (C) 2010-2019 EfficiOS Inc. and Linux Foundation
5 */
6
7 #ifndef BABELTRACE2_GRAPH_COMPONENT_CLASS_H
8 #define BABELTRACE2_GRAPH_COMPONENT_CLASS_H
9
10 /* IWYU pragma: private, include <babeltrace2/babeltrace.h> */
11
12 #ifndef __BT_IN_BABELTRACE_H
13 # error "Please include <babeltrace2/babeltrace.h> instead."
14 #endif
15
16 #include <babeltrace2/types.h>
17
18 #ifdef __cplusplus
19 extern "C" {
20 #endif
21
22 /*!
23 @defgroup api-comp-cls Component classes
24 @ingroup api-graph
25
26 @brief
27 Source, filter, and sink component classes (non-development).
28
29 A <strong><em>component class</em></strong> is the class of a \bt_comp:
30
31 @image html component.png
32
33 @attention
34 This module (component class API) offers basic, read-only functions
35 to get component class properties. To \em create a component class,
36 see \ref api-comp-cls-dev or \ref api-plugin-dev.
37
38 You can instantiate a given component class many times, with different
39 initialization parameters, to create many components with the
40 <code>bt_graph_add_*_component*()</code> functions (see \ref api-graph).
41
42 There are two ways to obtain a component class:
43
44 - Create one programmatically: see \ref api-comp-cls-dev.
45
46 - Borrow one from a \bt_plugin.
47
48 Note that, as of \bt_name_version_min_maj, you cannot access a
49 component class's plugin, if any.
50
51 A component class is a \ref api-fund-shared-object "shared object": get
52 a new reference with bt_component_class_get_ref() and put an existing
53 reference with bt_component_class_put_ref().
54
55 The common C&nbsp;type of a component class is #bt_component_class.
56
57 There are three types of component classes:
58
59 <dl>
60 <dt>\anchor api-comp-cls-src Source component class</dt>
61 <dd>
62 A source component class instance (a \bt_src_comp) \bt_msg_iter
63 emits fresh \bt_p_msg.
64
65 A source component class's specific type is
66 #bt_component_class_source and its type enumerator is
67 #BT_COMPONENT_CLASS_TYPE_SOURCE.
68
69 \ref api-fund-c-typing "Upcast" the #bt_component_class_source type
70 to the #bt_component_class type with
71 bt_component_class_source_as_component_class_const().
72
73 Get a new source component class reference with Use
74 bt_component_class_source_get_ref() and put an existing one with
75 bt_component_class_source_put_ref().
76 </dd>
77
78 <dt>\anchor api-comp-cls-flt Filter component class</dt>
79 <dd>
80 A filter component class instance (a \bt_flt_comp) message iterator
81 emits fresh and transformed messages. It can also discard
82 existing messages.
83
84 A filter component class's specific type is
85 #bt_component_class_filter and its type enumerator is
86 #BT_COMPONENT_CLASS_TYPE_FILTER.
87
88 \ref api-fund-c-typing "Upcast" the #bt_component_class_filter type
89 to the #bt_component_class type with
90 bt_component_class_filter_as_component_class_const().
91
92 Get a new filter component class reference with
93 bt_component_class_filter_get_ref() and put an existing one with
94 bt_component_class_filter_put_ref().
95 </dd>
96
97 <dt>\anchor api-comp-cls-sink Sink component class</dt>
98 <dd>
99 A sink component class instance (a \bt_sink_comp) consumes messages
100 from a source or filter message iterator.
101
102 A filter component class's specific type is #bt_component_class_sink
103 and its type enumerator is #BT_COMPONENT_CLASS_TYPE_SINK.
104
105 \ref api-fund-c-typing "Upcast" the #bt_component_class_sink type to
106 the #bt_component_class type with
107 bt_component_class_sink_as_component_class_const().
108
109 Get a new sink component class reference with
110 bt_component_class_sink_get_ref() and put an existing one with
111 bt_component_class_sink_put_ref().
112 </dd>
113 </dl>
114
115 Get a component's class type enumerator with
116 bt_component_class_get_type(). You can also use the
117 bt_component_class_is_source(), bt_component_class_is_filter(), and
118 bt_component_class_is_sink() helper functions.
119
120 <h1>Properties</h1>
121
122 A component class has the following common properties:
123
124 <dl>
125 <dt>
126 \anchor api-comp-cls-prop-name
127 Name
128 </dt>
129 <dd>
130 Name of the component class.
131
132 Within a \bt_plugin, for a given component class type, each
133 component class has a unique name.
134
135 Get a component class's name with bt_component_class_get_name().
136 </dd>
137
138 <dt>
139 \anchor api-comp-cls-prop-descr
140 \bt_dt_opt Description
141 </dt>
142 <dd>
143 Textual description of the component class.
144
145 Get a component class's description with
146 bt_component_class_get_description().
147 </dd>
148
149 <dt>
150 \anchor api-comp-cls-prop-help
151 \bt_dt_opt Help text
152 </dt>
153 <dd>
154 Help text of the component class.
155
156 Get a component class's help text with
157 bt_component_class_get_help().
158 </dd>
159 </dl>
160 */
161
162 /*! @{ */
163
164 /*!
165 @name Types
166 @{
167
168 @typedef struct bt_component_class bt_component_class;
169
170 @brief
171 Component class.
172
173 @typedef struct bt_component_class_source bt_component_class_source;
174
175 @brief
176 \bt_c_src_comp_cls.
177
178 @typedef struct bt_component_class_filter bt_component_class_filter;
179
180 @brief
181 \bt_c_flt_comp_cls.
182
183 @typedef struct bt_component_class_sink bt_component_class_sink;
184
185 @brief
186 \bt_c_sink_comp_cls.
187
188 @}
189 */
190
191 /*!
192 @name Type query
193 @{
194 */
195
196 /*!
197 @brief
198 Component class type enumerators.
199 */
200 typedef enum bt_component_class_type {
201 /*!
202 @brief
203 \bt_c_src_comp_cls.
204 */
205 BT_COMPONENT_CLASS_TYPE_SOURCE = 1 << 0,
206
207 /*!
208 @brief
209 \bt_c_flt_comp_cls.
210 */
211 BT_COMPONENT_CLASS_TYPE_FILTER = 1 << 1,
212
213 /*!
214 @brief
215 \bt_c_sink_comp_cls.
216 */
217 BT_COMPONENT_CLASS_TYPE_SINK = 1 << 2,
218 } bt_component_class_type;
219
220 /*!
221 @brief
222 Returns the type enumerator of the component class
223 \bt_p{component_class}.
224
225 @param[in] component_class
226 Component class of which to get the type enumerator.
227
228 @returns
229 Type enumerator of \bt_p{component_class}.
230
231 @bt_pre_not_null{component_class}
232
233 @sa bt_component_class_is_source() &mdash;
234 Returns whether or not a component class is a \bt_src_comp_cls.
235 @sa bt_component_class_is_filter() &mdash;
236 Returns whether or not a component class is a \bt_flt_comp_cls.
237 @sa bt_component_class_is_sink() &mdash;
238 Returns whether or not a component class is a \bt_sink_comp_cls.
239 */
240 extern bt_component_class_type bt_component_class_get_type(
241 const bt_component_class *component_class) __BT_NOEXCEPT;
242
243 /*!
244 @brief
245 Returns whether or not the component class \bt_p{component_class}
246 is a \bt_src_comp_cls.
247
248 @param[in] component_class
249 Component class to check.
250
251 @returns
252 #BT_TRUE if \bt_p{component_class} is a source component class.
253
254 @bt_pre_not_null{component_class}
255
256 @sa bt_component_class_get_type() &mdash;
257 Returns the type enumerator of a component class.
258 */
259 static inline
260 bt_bool bt_component_class_is_source(
261 const bt_component_class *component_class) __BT_NOEXCEPT
262 {
263 return bt_component_class_get_type(component_class) ==
264 BT_COMPONENT_CLASS_TYPE_SOURCE;
265 }
266
267 /*!
268 @brief
269 Returns whether or not the component class \bt_p{component_class}
270 is a \bt_flt_comp_cls.
271
272 @param[in] component_class
273 Component class to check.
274
275 @returns
276 #BT_TRUE if \bt_p{component_class} is a filter component class.
277
278 @bt_pre_not_null{component_class}
279
280 @sa bt_component_class_get_type() &mdash;
281 Returns the type enumerator of a component class.
282 */
283 static inline
284 bt_bool bt_component_class_is_filter(
285 const bt_component_class *component_class) __BT_NOEXCEPT
286 {
287 return bt_component_class_get_type(component_class) ==
288 BT_COMPONENT_CLASS_TYPE_FILTER;
289 }
290
291 /*!
292 @brief
293 Returns whether or not the component class \bt_p{component_class}
294 is a \bt_sink_comp_cls.
295
296 @param[in] component_class
297 Component class to check.
298
299 @returns
300 #BT_TRUE if \bt_p{component_class} is a sink component class.
301
302 @bt_pre_not_null{component_class}
303
304 @sa bt_component_class_get_type() &mdash;
305 Returns the type enumerator of a component class.
306 */
307 static inline
308 bt_bool bt_component_class_is_sink(
309 const bt_component_class *component_class) __BT_NOEXCEPT
310 {
311 return bt_component_class_get_type(component_class) ==
312 BT_COMPONENT_CLASS_TYPE_SINK;
313 }
314
315 /*! @} */
316
317 /*!
318 @name Properties
319 @{
320 */
321
322 /*!
323 @brief
324 Returns the name of the component class \bt_p{component_class}.
325
326 See the \ref api-comp-cls-prop-name "name" property.
327
328 @param[in] component_class
329 Component class of which to get the name.
330
331 @returns
332 @parblock
333 Name of \bt_p{component_class}.
334
335 The returned pointer remains valid as long as \bt_p{component_class}
336 exists.
337 @endparblock
338
339 @bt_pre_not_null{component_class}
340 */
341 extern const char *bt_component_class_get_name(
342 const bt_component_class *component_class) __BT_NOEXCEPT;
343
344 /*!
345 @brief
346 Returns the description of the component class
347 \bt_p{component_class}.
348
349 See the \ref api-comp-cls-prop-descr "description" property.
350
351 @param[in] component_class
352 Component class of which to get the description.
353
354 @returns
355 @parblock
356 Description of \bt_p{component_class}, or \c NULL if none.
357
358 The returned pointer remains valid as long as \bt_p{component_class}
359 exists.
360 @endparblock
361
362 @bt_pre_not_null{component_class}
363 */
364 extern const char *bt_component_class_get_description(
365 const bt_component_class *component_class) __BT_NOEXCEPT;
366
367 /*!
368 @brief
369 Returns the help text of the component class \bt_p{component_class}.
370
371 See the \ref api-comp-cls-prop-help "help text" property.
372
373 @param[in] component_class
374 Component class of which to get the help text.
375
376 @returns
377 @parblock
378 Help text of \bt_p{component_class}, or \c NULL if none.
379
380 The returned pointer remains valid as long as \bt_p{component_class}
381 exists.
382 @endparblock
383
384 @bt_pre_not_null{component_class}
385 */
386 extern const char *bt_component_class_get_help(
387 const bt_component_class *component_class) __BT_NOEXCEPT;
388
389 /*! @} */
390
391 /*!
392 @name Common reference count
393 @{
394 */
395
396 /*!
397 @brief
398 Increments the \ref api-fund-shared-object "reference count" of
399 the component class \bt_p{component_class}.
400
401 @param[in] component_class
402 @parblock
403 Component class of which to increment the reference count.
404
405 Can be \c NULL.
406 @endparblock
407
408 @sa bt_component_put_ref() &mdash;
409 Decrements the reference count of a component class.
410 */
411 extern void bt_component_class_get_ref(
412 const bt_component_class *component_class) __BT_NOEXCEPT;
413
414 /*!
415 @brief
416 Decrements the \ref api-fund-shared-object "reference count" of
417 the component class \bt_p{component_class}.
418
419 @param[in] component_class
420 @parblock
421 Component class of which to decrement the reference count.
422
423 Can be \c NULL.
424 @endparblock
425
426 @sa bt_component_get_ref() &mdash;
427 Increments the reference count of a component class.
428 */
429 extern void bt_component_class_put_ref(
430 const bt_component_class *component_class) __BT_NOEXCEPT;
431
432 /*!
433 @brief
434 Decrements the reference count of the component class
435 \bt_p{_component_class}, and then sets \bt_p{_component_class}
436 to \c NULL.
437
438 @param _component_class
439 @parblock
440 Component class of which to decrement the reference count.
441
442 Can contain \c NULL.
443 @endparblock
444
445 @bt_pre_assign_expr{_component_class}
446 */
447 #define BT_COMPONENT_CLASS_PUT_REF_AND_RESET(_component_class) \
448 do { \
449 bt_component_class_put_ref(_component_class); \
450 (_component_class) = NULL; \
451 } while (0)
452
453 /*!
454 @brief
455 Decrements the reference count of the component class \bt_p{_dst},
456 sets \bt_p{_dst} to \bt_p{_src}, and then sets \bt_p{_src}
457 to \c NULL.
458
459 This macro effectively moves a component class reference from the
460 expression
461 \bt_p{_src} to the expression \bt_p{_dst}, putting the existing
462 \bt_p{_dst} reference.
463
464 @param _dst
465 @parblock
466 Destination expression.
467
468 Can contain \c NULL.
469 @endparblock
470 @param _src
471 @parblock
472 Source expression.
473
474 Can contain \c NULL.
475 @endparblock
476
477 @bt_pre_assign_expr{_dst}
478 @bt_pre_assign_expr{_src}
479 */
480 #define BT_COMPONENT_CLASS_MOVE_REF(_dst, _src) \
481 do { \
482 bt_component_class_put_ref(_dst); \
483 (_dst) = (_src); \
484 (_src) = NULL; \
485 } while (0)
486
487 /*! @} */
488
489 /*!
490 @name Source component class upcast
491 @{
492 */
493
494 /*!
495 @brief
496 \ref api-fund-c-typing "Upcasts" the \bt_src_comp_cls
497 \bt_p{component_class} to the common #bt_component_class type.
498
499 @param[in] component_class
500 @parblock
501 Source component class to upcast.
502
503 Can be \c NULL.
504 @endparblock
505
506 @returns
507 \bt_p{component_class} as a common component class.
508 */
509 static inline
510 const bt_component_class *
511 bt_component_class_source_as_component_class_const(
512 const bt_component_class_source *component_class) __BT_NOEXCEPT
513 {
514 return __BT_UPCAST_CONST(bt_component_class, component_class);
515 }
516
517 /*! @} */
518
519 /*!
520 @name Source component class reference count
521 @{
522 */
523
524 /*!
525 @brief
526 Increments the \ref api-fund-shared-object "reference count" of
527 the \bt_src_comp_cls \bt_p{component_class}.
528
529 @param[in] component_class
530 @parblock
531 Source component class of which to increment the reference count.
532
533 Can be \c NULL.
534 @endparblock
535
536 @sa bt_component_class_source_put_ref() &mdash;
537 Decrements the reference count of a source component class.
538 */
539 extern void bt_component_class_source_get_ref(
540 const bt_component_class_source *component_class) __BT_NOEXCEPT;
541
542 /*!
543 @brief
544 Decrements the \ref api-fund-shared-object "reference count" of
545 the \bt_src_comp_cls \bt_p{component_class}.
546
547 @param[in] component_class
548 @parblock
549 Source component class of which to decrement the reference count.
550
551 Can be \c NULL.
552 @endparblock
553
554 @sa bt_component_class_source_get_ref() &mdash;
555 Increments the reference count of a source component class.
556 */
557 extern void bt_component_class_source_put_ref(
558 const bt_component_class_source *component_class) __BT_NOEXCEPT;
559
560 /*!
561 @brief
562 Decrements the reference count of the \bt_src_comp_cls
563 \bt_p{_component_class}, and then sets \bt_p{_component_class} to
564 \c NULL.
565
566 @param _component_class
567 @parblock
568 Source component class of which to decrement the reference count.
569
570 Can contain \c NULL.
571 @endparblock
572
573 @bt_pre_assign_expr{_component_class}
574 */
575 #define BT_COMPONENT_CLASS_SOURCE_PUT_REF_AND_RESET(_component_class) \
576 do { \
577 bt_component_class_source_put_ref(_component_class); \
578 (_component_class) = NULL; \
579 } while (0)
580
581 /*!
582 @brief
583 Decrements the reference count of the \bt_src_comp_cls \bt_p{_dst},
584 sets \bt_p{_dst} to \bt_p{_src}, and then sets \bt_p{_src} to
585 \c NULL.
586
587 This macro effectively moves a source component class reference from the
588 expression \bt_p{_src} to the expression \bt_p{_dst}, putting the
589 existing \bt_p{_dst} reference.
590
591 @param _dst
592 @parblock
593 Destination expression.
594
595 Can contain \c NULL.
596 @endparblock
597 @param _src
598 @parblock
599 Source expression.
600
601 Can contain \c NULL.
602 @endparblock
603
604 @bt_pre_assign_expr{_dst}
605 @bt_pre_assign_expr{_src}
606 */
607 #define BT_COMPONENT_CLASS_SOURCE_MOVE_REF(_dst, _src) \
608 do { \
609 bt_component_class_source_put_ref(_dst); \
610 (_dst) = (_src); \
611 (_src) = NULL; \
612 } while (0)
613
614 /*! @} */
615
616 /*!
617 @name Filter component class upcast
618 @{
619 */
620
621 /*!
622 @brief
623 \ref api-fund-c-typing "Upcasts" the \bt_flt_comp_cls
624 \bt_p{component_class} to the common #bt_component_class type.
625
626 @param[in] component_class
627 @parblock
628 Filter component class to upcast.
629
630 Can be \c NULL.
631 @endparblock
632
633 @returns
634 \bt_p{component_class} as a common component class.
635 */
636 static inline
637 const bt_component_class *
638 bt_component_class_filter_as_component_class_const(
639 const bt_component_class_filter *component_class) __BT_NOEXCEPT
640 {
641 return __BT_UPCAST_CONST(bt_component_class, component_class);
642 }
643
644 /*! @} */
645
646 /*!
647 @name Filter component class reference count
648 @{
649 */
650
651 /*!
652 @brief
653 Increments the \ref api-fund-shared-object "reference count" of
654 the \bt_flt_comp_cls \bt_p{component_class}.
655
656 @param[in] component_class
657 @parblock
658 Filter component class of which to increment the reference count.
659
660 Can be \c NULL.
661 @endparblock
662
663 @sa bt_component_class_filter_put_ref() &mdash;
664 Decrements the reference count of a filter component class.
665 */
666 extern void bt_component_class_filter_get_ref(
667 const bt_component_class_filter *component_class) __BT_NOEXCEPT;
668
669 /*!
670 @brief
671 Decrements the \ref api-fund-shared-object "reference count" of
672 the \bt_flt_comp_cls \bt_p{component_class}.
673
674 @param[in] component_class
675 @parblock
676 Filter component class of which to decrement the reference count.
677
678 Can be \c NULL.
679 @endparblock
680
681 @sa bt_component_class_filter_get_ref() &mdash;
682 Increments the reference count of a filter component class.
683 */
684 extern void bt_component_class_filter_put_ref(
685 const bt_component_class_filter *component_class) __BT_NOEXCEPT;
686
687 /*!
688 @brief
689 Decrements the reference count of the \bt_flt_comp_cls
690 \bt_p{_component_class}, and then sets \bt_p{_component_class} to
691 \c NULL.
692
693 @param _component_class
694 @parblock
695 Filter component class of which to decrement the reference count.
696
697 Can contain \c NULL.
698 @endparblock
699
700 @bt_pre_assign_expr{_component_class}
701 */
702 #define BT_COMPONENT_CLASS_FILTER_PUT_REF_AND_RESET(_component_class) \
703 do { \
704 bt_component_class_filter_put_ref(_component_class); \
705 (_component_class) = NULL; \
706 } while (0)
707
708 /*!
709 @brief
710 Decrements the reference count of the \bt_flt_comp_cls \bt_p{_dst},
711 setsc \bt_p{_dst} to \bt_p{_src}, and then sets \bt_p{_src} to
712 \c NULL.
713
714 This macro effectively moves a filter component class reference from the
715 expression \bt_p{_src} to the expression \bt_p{_dst}, putting the
716 existing \bt_p{_dst} reference.
717
718 @param _dst
719 @parblock
720 Destination expression.
721
722 Can contain \c NULL.
723 @endparblock
724 @param _src
725 @parblock
726 Source expression.
727
728 Can contain \c NULL.
729 @endparblock
730
731 @bt_pre_assign_expr{_dst}
732 @bt_pre_assign_expr{_src}
733 */
734 #define BT_COMPONENT_CLASS_FILTER_MOVE_REF(_dst, _src) \
735 do { \
736 bt_component_class_filter_put_ref(_dst); \
737 (_dst) = (_src); \
738 (_src) = NULL; \
739 } while (0)
740
741 /*! @} */
742
743 /*!
744 @name Sink component class upcast
745 @{
746 */
747
748 /*!
749 @brief
750 \ref api-fund-c-typing "Upcasts" the \bt_sink_comp_cls
751 \bt_p{component_class} to the common #bt_component_class type.
752
753 @param[in] component_class
754 @parblock
755 Sink component class to upcast.
756
757 Can be \c NULL.
758 @endparblock
759
760 @returns
761 \bt_p{component_class} as a common component class.
762 */
763 static inline
764 const bt_component_class *
765 bt_component_class_sink_as_component_class_const(
766 const bt_component_class_sink *component_class) __BT_NOEXCEPT
767 {
768 return __BT_UPCAST_CONST(bt_component_class, component_class);
769 }
770
771 /*! @} */
772
773 /*!
774 @name Sink component class reference count
775 @{
776 */
777
778 /*!
779 @brief
780 Increments the \ref api-fund-shared-object "reference count" of
781 the \bt_sink_comp_cls \bt_p{component_class}.
782
783 @param[in] component_class
784 @parblock
785 Sink component class of which to increment the reference count.
786
787 Can be \c NULL.
788 @endparblock
789
790 @sa bt_component_class_sink_put_ref() &mdash;
791 Decrements the reference count of a sink component class.
792 */
793 extern void bt_component_class_sink_get_ref(
794 const bt_component_class_sink *component_class) __BT_NOEXCEPT;
795
796 /*!
797 @brief
798 Decrements the \ref api-fund-shared-object "reference count" of
799 the \bt_sink_comp_cls \bt_p{component_class}.
800
801 @param[in] component_class
802 @parblock
803 Sink component class of which to decrement the reference count.
804
805 Can be \c NULL.
806 @endparblock
807
808 @sa bt_component_class_sink_get_ref() &mdash;
809 Increments the reference count of a sink component class.
810 */
811 extern void bt_component_class_sink_put_ref(
812 const bt_component_class_sink *component_class) __BT_NOEXCEPT;
813
814 /*!
815 @brief
816 Decrements the reference count of the \bt_sink_comp_cls
817 \bt_p{_component_class}, and then sets \bt_p{_component_class} to
818 \c NULL.
819
820 @param _component_class
821 @parblock
822 Sink component class of which to decrement the reference count.
823
824 Can contain \c NULL.
825 @endparblock
826
827 @bt_pre_assign_expr{_component_class}
828 */
829 #define BT_COMPONENT_CLASS_SINK_PUT_REF_AND_RESET(_component_class) \
830 do { \
831 bt_component_class_sink_put_ref(_component_class); \
832 (_component_class) = NULL; \
833 } while (0)
834
835 /*!
836 @brief
837 Decrements the reference count of the \bt_sink_comp_cls \bt_p{_dst},
838 sets \bt_p{_dst} to \bt_p{_src}, and then sets \bt_p{_src} to
839 \c NULL.
840
841 This macro effectively moves a sink component class reference from the
842 expression \bt_p{_src} to the expression \bt_p{_dst}, putting the
843 existing \bt_p{_dst} reference.
844
845 @param _dst
846 @parblock
847 Destination expression.
848
849 Can contain \c NULL.
850 @endparblock
851 @param _src
852 @parblock
853 Source expression.
854
855 Can contain \c NULL.
856 @endparblock
857
858 @bt_pre_assign_expr{_dst}
859 @bt_pre_assign_expr{_src}
860 */
861 #define BT_COMPONENT_CLASS_SINK_MOVE_REF(_dst, _src) \
862 do { \
863 bt_component_class_sink_put_ref(_dst); \
864 (_dst) = (_src); \
865 (_src) = NULL; \
866 } while (0)
867
868 /*! @} */
869
870 /*! @} */
871
872 #ifdef __cplusplus
873 }
874 #endif
875
876 #endif /* BABELTRACE2_GRAPH_COMPONENT_CLASS_H */
This page took 0.048386 seconds and 4 git commands to generate.