From patchwork Thu Dec 5 22:22:35 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Pierrick Bouvier X-Patchwork-Id: 847589 Delivered-To: patch@linaro.org Received: by 2002:a5d:50c2:0:b0:385:e875:8a9e with SMTP id f2csp476533wrt; Thu, 5 Dec 2024 14:25:12 -0800 (PST) X-Forwarded-Encrypted: i=2; AJvYcCX8YBwx4Mn1fWFNfbFBFFpE9mC0IHFqsiO9fI51JU8uWhLCe6Nx/bCjPF1NRaqyvMRLVkjXnw==@linaro.org X-Google-Smtp-Source: AGHT+IFhFhg2szOnmzPC0iHtlht6NzFioHD3TrSTGl4f7eOvkhUeVlGBaiXEHmgTAZ23QT+MLuck X-Received: by 2002:a05:6214:2506:b0:6d8:88fc:c0f4 with SMTP id 6a1803df08f44-6d8e73c0d71mr9517626d6.33.1733437512122; Thu, 05 Dec 2024 14:25:12 -0800 (PST) ARC-Seal: i=1; a=rsa-sha256; t=1733437512; cv=none; d=google.com; s=arc-20240605; b=Z52GJhFv7skwPmanPCbldf9VcdLMLG1oKWfK+R0a9le99kML5Jaxxho57bnTuiLlJ7 YjWLrBYlmezNI+RoemIEuQJzN+sGCxqA+BgF+iRKWhG05BAGQ6qq1OURqViO8+yVSEDE PZeBoJ6pvMdQApYampSdh0wncDyKEZ1t/knDpuThBHmKRo1JyhJqMhyFPdoC5WRJ7bga Xp3unmhPCUiU/fgXIf3IOyctV+jI3/owSNCZCZrF4J1vwHkqujzsVJ8AsR64kHgsBfzt AtQx22P4RNKNGWVafSVV8aS0A9Z7TCFxeu6XA5TOM5NEpb+HI2WijMyR9S0SOu4k2gt4 LMKA== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20240605; h=sender:errors-to:list-subscribe:list-help:list-post:list-archive :list-unsubscribe:list-id:precedence:content-transfer-encoding :mime-version:message-id:date:subject:cc:to:from:dkim-signature; bh=fIZCLlFZjn+KeB33XmENBZ2FZNb5x3KZq8MhJwQPh+Y=; fh=O7N/1oB1M3FN7UbF/q0R+4lMttX3umDHGGieH0SYQPs=; b=lax/FlIR5k5AMfUbtah6mmd9sL6h7BfGxJmJh52vDeFXULoEuvL5K2LwqTsuNxAfJd c22Lih/doqCijlFqpLKFqLhq6YWOAMBCuiZGHY2tPA2cQlM4aqbdWJsihqgdZ+wIPEnk Tx86YA4bRBUJFjXRn+6ZnrnV7DtBf39K4oUyt1KhNx8FiEp7kZgp1WZgao6kAYxQSB9l t969BQQI5zIzrM8y9oHmLUU/bX2uRGUjpI9/ZAAV/8/Pv5nDJNakFSUV1nFhhTGVJ15x rpnyvF5anHvTxlVf9RGeAheEtA6+0HVpkJhF7O+elxhqRyODjZpqjr+84SeGNr95iCBR /DLg==; dara=google.com ARC-Authentication-Results: i=1; mx.google.com; dkim=pass header.i=@linaro.org header.s=google header.b=mdCVpx9I; spf=pass (google.com: domain of qemu-devel-bounces+patch=linaro.org@nongnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom="qemu-devel-bounces+patch=linaro.org@nongnu.org"; dmarc=pass (p=NONE sp=NONE dis=NONE) header.from=linaro.org; dara=neutral header.i=@linaro.org Return-Path: Received: from lists.gnu.org (lists.gnu.org. [209.51.188.17]) by mx.google.com with ESMTPS id 6a1803df08f44-6d8e6936317si6032666d6.281.2024.12.05.14.25.11 for (version=TLS1_2 cipher=ECDHE-ECDSA-CHACHA20-POLY1305 bits=256/256); Thu, 05 Dec 2024 14:25:12 -0800 (PST) Received-SPF: pass (google.com: domain of qemu-devel-bounces+patch=linaro.org@nongnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; Authentication-Results: mx.google.com; dkim=pass header.i=@linaro.org header.s=google header.b=mdCVpx9I; spf=pass (google.com: domain of qemu-devel-bounces+patch=linaro.org@nongnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom="qemu-devel-bounces+patch=linaro.org@nongnu.org"; dmarc=pass (p=NONE sp=NONE dis=NONE) header.from=linaro.org; dara=neutral header.i=@linaro.org Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1tJKFL-0004WD-4T; Thu, 05 Dec 2024 17:22:55 -0500 Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1tJKFJ-0004VU-QA for qemu-devel@nongnu.org; Thu, 05 Dec 2024 17:22:53 -0500 Received: from mail-pl1-x633.google.com ([2607:f8b0:4864:20::633]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1tJKFH-0007zs-SY for qemu-devel@nongnu.org; Thu, 05 Dec 2024 17:22:53 -0500 Received: by mail-pl1-x633.google.com with SMTP id d9443c01a7336-215b45a40d8so12867155ad.1 for ; Thu, 05 Dec 2024 14:22:49 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; t=1733437369; x=1734042169; darn=nongnu.org; h=content-transfer-encoding:mime-version:message-id:date:subject:cc :to:from:from:to:cc:subject:date:message-id:reply-to; bh=fIZCLlFZjn+KeB33XmENBZ2FZNb5x3KZq8MhJwQPh+Y=; b=mdCVpx9IGU7V+IamsU2piwcfQNBzDiyW5SFCkSDULvzXFn86NPvs8Dy0RhbNayD9ZK lVCS2JqtKsZc+cY7yaRoKv0trnw7tCOZHVvQBVyfsFeWEedjQjVLb+fBmlspV6Lfec1q l9jqYHfkM46PlTwO4KdfR2/PqLMJTXGP6+I8DK9Y9Gpg7T2/LLZKpHxEyu7C1LX2DM38 PXBm3fzl3C8EzqOf98xxKdL3V67gFB98ivKz0UGhVxMN07mlFSXzcKvW/corlTWKna27 msrymIwAKVwTXsWO7RlQALqM9pjqFRfsiwfhNVwbdX3e69vGQRkRZtgOKyCCCCo+F1TW nRFA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1733437369; x=1734042169; h=content-transfer-encoding:mime-version:message-id:date:subject:cc :to:from:x-gm-message-state:from:to:cc:subject:date:message-id :reply-to; bh=fIZCLlFZjn+KeB33XmENBZ2FZNb5x3KZq8MhJwQPh+Y=; b=pbhWouB7r4d/PBWyw819ZxNAMmikX3/SNldSaEuWddYXplNcprTCSZlKJlkCBQqYw/ 9ntid3m+Q/y9tWzZR88qNpV6j7fE/1rgmFGJjAsH5fC6Z0e2j+VzlVyYaZ0T+txsCR8H JspITnNqpGWiaL1BXbfcMkRIaWy891PjNgTtvJbs7+xvUnKSS0suA1udEHCALfAeG0+b go1G1/z6zOzcyhDEiIA6YeJlnV+Acpz24hnNo8m1yiyOaoffC/vqE9BPpCU5ZaFWak4s zZJ1DwJhgeOeyhNfUBN2Y8mBSmGfiQMiz+M6YOXp3y8SYFKDDK2L0S5dmlG6im938xa7 Dj8A== X-Gm-Message-State: AOJu0Yyh65aFOGhyYeP/ocK9hfNDOj/oiBEIqMW0oldE8fsBJbCCd32u e34sRZF+xnbTgfhaIXvZvS2wCTkqgv1QYuY3nwRcfaXjq+VqkcghL9l+nmejy8Dq3fthaHjGA4B dTEI= X-Gm-Gg: ASbGncv40eICFXBcr1dPC11GORgNyS7CpcfmtU2ulPFRG5bL7GedC8EfBH0DxWDX0iH 1pm1wnd1O00odZdyX8PZff9mn0q/puydRz9ZazskKm2iGTGbzfW26eW8VfdixYGHpe3CVEyrlRB /Pfm67Kov/Vur4T/XBw9HAmqBux7Ak4PmMpW0ZJ7Is2UbM+tOheZNOmoC7i8wENPUPdPTLVEw0M 5tBoD9CpBuvdHAC206Z02RtW4LJyEMSSM1/9LFa+nNFG2aj/ULQI+58Nxfg2x/pTqaqjh0bL8xq muw66iNH X-Received: by 2002:a17:902:c405:b0:212:40e0:9562 with SMTP id d9443c01a7336-21614d54187mr6696405ad.25.1733437368685; Thu, 05 Dec 2024 14:22:48 -0800 (PST) Received: from pc.. (216-180-64-156.dyn.novuscom.net. [216.180.64.156]) by smtp.gmail.com with ESMTPSA id d9443c01a7336-215f8f0b571sm17310435ad.183.2024.12.05.14.22.47 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 05 Dec 2024 14:22:48 -0800 (PST) From: Pierrick Bouvier To: qemu-devel@nongnu.org Cc: Fabiano Rosas , Kevin Wolf , Richard Henderson , Vladimir Sementsov-Ogievskiy , gustavo.romero@linaro.org, Andrew Melnychenko , Peter Maydell , qemu-arm@nongnu.org, alex.bennee@linaro.org, Konstantin Kostiuk , Eric Blake , =?utf-8?q?Philippe_Mathieu-Daud=C3=A9?= , Peter Xu , Markus Armbruster , =?utf-8?q?Daniel_P=2E_Berrang=C3=A9?= , Yuri Benditovich , Jason Wang , Michael Roth , Paolo Bonzini , Thomas Huth , manos.pitsidianakis@linaro.org, qemu-block@nongnu.org, Pierrick Bouvier Subject: [PATCH v2 0/6] Enhance documentation for new developers Date: Thu, 5 Dec 2024 14:22:35 -0800 Message-Id: <20241205222241.3789437-1-pierrick.bouvier@linaro.org> X-Mailer: git-send-email 2.39.5 MIME-Version: 1.0 Received-SPF: pass client-ip=2607:f8b0:4864:20::633; envelope-from=pierrick.bouvier@linaro.org; helo=mail-pl1-x633.google.com X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: qemu-devel-bounces+patch=linaro.org@nongnu.org Sender: qemu-devel-bounces+patch=linaro.org@nongnu.org This series extends our documentation with new pages to help developers onboarding on QEMU. It focuses on providing a big picture of QEMU (to a modest extend). As such, it was written to be simple, short, easy to understand, and pointing to more details. It provides another way to dive into details instead of simply hitting the "search" box. The first patches enhance the existing developer section. They provide information about b4 and git-publish, two important tools that I learnt from my coworkers, and were not presented anywhere, and were really missing IMHO. Then, we introduce a new Codebase page, presenting (succintly) the various parts of QEMU, and what every folder of the codebase contains. We then add a glossary with the most recurrent acronyms we hear in our daily conversations on the mailing list. Finally, we add an "How-to" page which present how to build and test qemu, and how to contribute a patch. It's definitely a repetition of existing information, but the goal was to have a self contained page with all the commands I run daily personally, and that someone would be interested to have. When reviewing, please keep in mind this is targeting someone who discovers QEMU, and not someone who contributed to the project for several years. What is obvious for you will not be obvious for a random young developer. That said, please free to point if something is "false", or "really incomplete". It can be hard to summarize in one or two sentences complex parts, but that's the intent here. Your feedback on content or organization is very welcome! Thanks, Pierrick v2: - removed how-to section - integrated all suggestions from Daniel and Peter (thanks for all your comments) - Note: build environment keeps mentioning windows-arm64 because we solved the issue with gcc_struct attribute. The related series will be merged before this documentation. Pierrick Bouvier (6): docs/devel: remove dead video link for sourcehut submit process docs/devel: add git-publish for patch submitting docs/devel: add b4 for patch retrieval docs/devel: add information on how to setup build environments docs: add a codebase section docs: add a glossary docs/about/build-platforms.rst | 4 +- docs/about/emulation.rst | 2 + docs/devel/build-environment.rst | 118 +++++++++++ docs/devel/codebase.rst | 218 +++++++++++++++++++ docs/devel/control-flow-integrity.rst | 2 + docs/devel/decodetree.rst | 2 + docs/devel/ebpf_rss.rst | 2 + docs/devel/index-build.rst | 1 + docs/devel/index-internals.rst | 2 + docs/devel/index.rst | 1 + docs/devel/migration/main.rst | 2 + docs/devel/multi-thread-tcg.rst | 2 + docs/devel/qapi-code-gen.rst | 1 + docs/devel/submitting-a-patch.rst | 34 ++- docs/devel/testing/main.rst | 9 +- docs/devel/testing/qtest.rst | 2 + docs/glossary.rst | 280 +++++++++++++++++++++++++ docs/index.rst | 3 + docs/interop/qemu-ga.rst | 2 + docs/system/arm/virt.rst | 2 + docs/system/images.rst | 2 + docs/system/qemu-block-drivers.rst.inc | 2 + docs/tools/qemu-nbd.rst | 2 + docs/tools/qemu-storage-daemon.rst | 2 + docs/user/main.rst | 6 + 25 files changed, 697 insertions(+), 6 deletions(-) create mode 100644 docs/devel/build-environment.rst create mode 100644 docs/devel/codebase.rst create mode 100644 docs/glossary.rst