Làm cách nào để tạo phần nhân 9 trang mà tài liệu chức năng, cấu trúc dữ liệu và tiêu đề?

Các nguồn kernel chứa các hàm và cấu trúc dữ liệu được ghi lại, ví dụ như trong panic.c:

/**
 *  panic - halt the system
 *  @fmt: The text string to print
 *
 *  Display a message, then perform cleanups.
 *
 *  This function never returns.
 */
void panic(const char *fmt, ...)

Thay vì đi qua các nguồn mỗi lần, sẽ rất hữu ích khi xem các API đó dưới dạng trang và sử dụng khung tài liệu hiện có này.

Làm thế nào để bạn cài đặt / tạo phần nhân 9 trang ( /usr/share/man/man9) tài liệu về các chức năng và cấu trúc dữ liệu đã nói ở trên?

Nội dung được phân tích cú pháp trực tiếp (xem thêm phần này ) từ tệp .c nguồn ¹ :

Để cung cấp tài liệu nhúng, thân thiện, dễ bảo trì, nhưng nhất quán và có thể trích xuất được các chức năng và cấu trúc dữ liệu trong nhân Linux, nhân Linux đã áp dụng một kiểu nhất quán để ghi lại các chức năng và các tham số của chúng và các cấu trúc của chúng các thành viên.

Định dạng cho tài liệu này được gọi là định dạng kernel-doc. Nó được ghi lại trong tệp Tài liệu / kernel-doc-nano-HOWTO.txt này.

Kiểu này nhúng tài liệu trong các tệp nguồn, sử dụng một vài quy ước đơn giản. Tập lệnh perl script / kernel-doc, một số mẫu SGML trong Tài liệu / Tài liệu và các công cụ khác hiểu các quy ước này và được sử dụng để trích xuất tài liệu nhúng này vào các tài liệu khác nhau. [...]

Dấu bình luận mở "/ **" được dành riêng cho các bình luận kernel-doc. Chỉ các nhận xét được đánh dấu sẽ được xem xét bởi các tập lệnh kernel-doc và bất kỳ nhận xét nào được đánh dấu phải ở định dạng kernel-doc.

Điều đó có nghĩa là chỉ những bình luận được định dạng như vậy mới có thể được trích xuất theo cách này và bạn có thể tận dụng tập lệnh Perl được sử dụng bởi quy trình:kernel-doc make

kernel-doc [ -docbook | -html | -html5 | -text | -man | -list ]
  [ -no-doc-sections ]
  [ -function funcname [ -function funcname ...] ]
  c file(s)s > outputfile

và do đó bạn không bị giới hạn trong mục tiêu mandocs :

Sau khi cài đặt, "make psdocs", "make pdfdocs", "make htmldocs" hoặc "make mandocs" sẽ hiển thị tài liệu theo định dạng được yêu cầu.

Ngoài ra còn có các tệp văn bản cụ thể trình điều khiển trong kho / nguồn kernel. Tổng quát hơn, dự án trang man Linux của họ ( man1 đến man8 ) có sẵn để tải xuống. Trên một ghi chú cuối kernel.org cũng duy trì một số tài liệu đầu ra .

^{1. Hạt nhân không phải là trường hợp duy nhất sử dụng một kỹ thuật như vậy để tạo các trang. GNU coreutils là một trường hợp khác; hầu hết các trang của nó được tạo bằng cách sử dụng đầu ra của command --helpnội dung trong hàm sử dụng tệp nguồn tiện ích ( 1 2 ).}

Giả sử bạn đang sử dụng Ubuntu,

apt-get install linux-manual-3.2

hoặc tương tự (chọn phiên bản chính xác). Ngoài ra còn có một gói tài liệu khác

apt-get install linux-doc

nhưng đây là html.

Tải về mã nguồn kernel và trong thư mục nguồn thực thi

make mandocs

Sau khi các tài liệu người đàn ông đã được thực hiện, thực hiện

make installmandocs

Điều này sẽ cài đặt các trang hướng dẫn vào /usr/local/man/man9/. Bây giờ bạn có thể xem các trang man bằng cách nhập man <api-name>hoặc nếu bạn đang chỉnh sửa vimchỉ cần nhấn Kvào tên API.