From 6cecbdf41ef2e109deabcd3e3620b6e8251157db Mon Sep 17 00:00:00 2001 From: Adarsh Date: Mon, 15 Apr 2024 10:02:34 +0530 Subject: [PATCH 1/4] [Docs] Non-Breaking change of "p4c" to "P4C" This Commit only focuses on the Documentation text, Without modifying any command or directory name. --- CONTRIBUTING.md | 4 +-- README.md | 78 ++++++++++++++++++++++++------------------------- 2 files changed, 41 insertions(+), 41 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 12a13da836..a066dbede6 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,6 +1,6 @@ -# Contributing to the P4 Compiler Project (p4c) +# Contributing to the P4 Compiler Project (P4C) -Thank you for considering contributing to the P4 Compiler Project (p4c)! Your contributions are valuable and help improve the project for everyone. Before getting started, please take a moment to review the following guidelines. +Thank you for considering contributing to the P4 Compiler Project (P4C)! Your contributions are valuable and help improve the project for everyone. Before getting started, please take a moment to review the following guidelines. ## Coding Standard Philosophy diff --git a/README.md b/README.md index e8ea66f365..5f1d9e4279 100644 --- a/README.md +++ b/README.md @@ -6,12 +6,12 @@ [![Docker Container](https://github.com/p4lang/p4c/actions/workflows/ci-container-image.yml/badge.svg)](https://github.com/p4lang/p4c/actions/workflows/ci-container-image.yml) -p4c +P4C ================= * [Getting started](#getting-started) - * [Installing packaged versions of p4c](#installing-packaged-versions-of-p4c) - * [Installing p4c from source](#installing-p4c-from-source) + * [Installing packaged versions of P4C](#installing-packaged-versions-of-p4c) + * [Installing P4C from source](#installing-p4c-from-source) * [Dependencies](#dependencies) * [Ubuntu dependencies](#ubuntu-dependencies) * [Fedora dependencies](#fedora-dependencies) @@ -31,16 +31,16 @@ p4c * [P4 Compiler Onboarding](#p4-compiler-onboarding) * [Contact](#contact) -p4c is a reference compiler for the P4 programming language. +P4C is a reference compiler for the P4 programming language. It supports both P4-14 and P4-16; you can find more information about P4 [here](http://p4.org) and the specifications for both versions of the language [here](https://p4.org/specs). -One fact attesting to the level of quality and completeness of p4c's -code is that its front-end code, mid-end code, and p4c-graphs back end +One fact attesting to the level of quality and completeness of P4C's +code is that its front-end code, mid-end code, and P4C-graphs back end are used as the basis for at least one commercially supported P4 compiler. -p4c is modular; it provides a standard frontend and midend which can be combined +P4C is modular; it provides a standard frontend and midend which can be combined with a target-specific backend to create a complete P4 compiler. The goal is to make adding new backends easy. @@ -76,7 +76,7 @@ p4c --target bmv2 --arch v1model --std p4-14 my-p4-14-prog.p4 ``` By adding the option `--p4runtime-files .txt` as shown in -the example commands below, p4c will also create a file +the example commands below, P4C will also create a file `.txt`. This is a text format "P4Info" file, containing a description of the tables and other objects in your P4 program that have an auto-generated control plane API. @@ -128,13 +128,13 @@ dot -Tpdf ParserImpl.dot > ParserImpl.pdf # Getting started -## Installing packaged versions of p4c +## Installing packaged versions of P4C -p4c has package support for several Ubuntu and Debian distributions. +P4C has package support for several Ubuntu and Debian distributions. ### Ubuntu -A p4c package is available in the following repositories for Ubuntu 20.04 and newer. +A P4C package is available in the following repositories for Ubuntu 20.04 and newer. ```bash source /etc/lsb-release @@ -155,20 +155,20 @@ sudo apt update sudo apt install p4lang-p4c ``` -If you cannot use a repository to install p4c, you can download the `.deb` file +If you cannot use a repository to install P4C, you can download the `.deb` file for your release and install it manually. You need to download a new file each -time you want to upgrade p4c. +time you want to upgrade P4C. -1. Go to [p4lang-p4c package page on OpenSUSE Build Service](https://build.opensuse.org/package/show/home:p4lang/p4lang-p4c), click on +1. Go to [p4lang-P4C package page on OpenSUSE Build Service](https://build.opensuse.org/package/show/home:p4lang/p4lang-p4c), click on "Download package" and choose your operating system version. -2. Install p4c, changing the path below to the path where you downloaded the package. +2. Install P4C, changing the path below to the path where you downloaded the package. ```bash sudo dpkg -i /path/to/package.deb ``` -## Installing p4c from source +## Installing P4C from source 1. Clone the repository. It includes submodules, so be sure to use `--recursive` to pull them in: ``` @@ -238,7 +238,7 @@ sudo dpkg -i /path/to/package.deb ``` sudo make install ``` - The compiler driver `p4c` and binaries for each of the backends are + The compiler driver `P4C` and binaries for each of the backends are installed in `/usr/local/bin` by default; the P4 headers are placed in `/usr/local/share/p4c`. @@ -248,12 +248,12 @@ sudo dpkg -i /path/to/package.deb p4c -b bmv2-ss-p4org program.p4 -o program.bmv2.json ``` -If you plan to contribute to p4c, you'll find more useful information +If you plan to contribute to P4C, you'll find more useful information [here](#development-tools). # Dependencies -Ubuntu 20.04 is the officially supported platform for p4c. There's also +Ubuntu 20.04 is the officially supported platform for P4C. There's also unofficial support for macOS 11. Other platforms are untested; you can try to use them, but YMMV. @@ -278,7 +278,7 @@ use them, but YMMV. (2.38.0 or higher). Backends may have additional dependencies. The dependencies for the backends -included with `p4c` are documented here: +included with `P4C` are documented here: * [BMv2](backends/bmv2/README.md) * [eBPF](backends/ebpf/README.md) * [graphs](backends/graphs/README.md) @@ -299,7 +299,7 @@ pip3 install --user -r requirements.txt For documentation building: `sudo apt-get install -y doxygen graphviz texlive-full` -`p4c` also depends on Google Protocol Buffers (Protobuf). `p4c` requires version +`P4C` also depends on Google Protocol Buffers (Protobuf). `P4C` requires version 3.0 or higher, so the packaged version provided in Ubuntu 20.04 **should** work. However, P4C typically installs its own version of Protobuf using CMake's `FetchContent` module (at the moment, 3.25.3). If you are experiencing issues with the Protobuf version shipped with your OS distribution, we recommend that to install Protobuf 3.25.3 from source. You can find instructions @@ -309,13 +309,13 @@ After cloning Protobuf and before you build, check-out version 3.25.3: `git checkout v3.25.3` Please note that while all Protobuf versions newer than 3.0 should work for -`p4c` itself, you may run into trouble with some extensions and other p4lang +`P4C` itself, you may run into trouble with some extensions and other p4lang projects unless you install version 3.25.3. -`p4c` also depends on Google Abseil library. This library is also a pre-requisite for Protobuf of any version newer than 3.21. Therefore the use of Protobuf of suitable version automatically fulfils Abseil dependency. P4C typically installs its own version of Abseil using CMake's `FetchContent` module (Abseil LTS 20240116.1 at the moment). +`P4C` also depends on Google Abseil library. This library is also a pre-requisite for Protobuf of any version newer than 3.21. Therefore the use of Protobuf of suitable version automatically fulfils Abseil dependency. P4C typically installs its own version of Abseil using CMake's `FetchContent` module (Abseil LTS 20240116.1 at the moment). ### CMake -p4c requires a CMake version of at least 3.16.3 or higher. On older systems, a newer version of CMake can be installed using `pip3 install --user cmake==3.16.3`. We have a CI test on Ubuntu 18.04 that uses this option, but there is no guarantee that this will lead to a successful build. +P4C requires a CMake version of at least 3.16.3 or higher. On older systems, a newer version of CMake can be installed using `pip3 install --user cmake==3.16.3`. We have a CI test on Ubuntu 18.04 that uses this option, but there is no guarantee that this will lead to a successful build. ## Fedora dependencies @@ -376,7 +376,7 @@ Installing on macOS: brew install doxygen graphviz ``` Homebrew offers a `protobuf` formula. It installs version 3.2, which should - work for p4c itself but may cause problems with some extensions. It's + work for P4C itself but may cause problems with some extensions. It's preferable to use the version of Protobuf which is supplied with CMake's fetchcontent (3.25.3). The `protobuf` formula requires the following CMake variables to be set, @@ -394,7 +394,7 @@ Installing on macOS: ## Garbage collector P4c relies on [BDW garbage collector](https://github.com/ivmai/bdwgc) -to manage its memory. By default, the p4c executables are linked with +to manage its memory. By default, the P4C executables are linked with the garbage collector library. When the GC causes problems, this can be disabled by setting `ENABLE_GC` cmake option to `OFF`. However, this will dramatically increase the memory usage by the compiler, and @@ -432,16 +432,16 @@ documentation. The HTML output is available in ## Git setup -Occasionally formatting commits are applied to p4c. These pollute the git history. To ignore these commits in git blame, run this command +Occasionally formatting commits are applied to P4C. These pollute the git history. To ignore these commits in git blame, run this command ```git config blame.ignoreRevsFile .git-blame-ignore-revs``` -The p4c code base is subject to a series of linter checks which are checked by CI. To avoid failing these checks and wasting unnecessary CI cycles and resources, you can install [git commit hooks](https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks) by running +The P4C code base is subject to a series of linter checks which are checked by CI. To avoid failing these checks and wasting unnecessary CI cycles and resources, you can install [git commit hooks](https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks) by running ```./tools/install_git_hooks.sh``` These commit hooks will run on every commit and check the files you are planning to commit with cpplint and clang-format. # Docker -A Dockerfile is included. You can generate an image which contains a copy of p4c +A Dockerfile is included. You can generate an image which contains a copy of P4C in `/p4c/build` by running: ``` @@ -450,7 +450,7 @@ docker build -t p4c . On some platforms Docker limits the memory usage of any container, even containers used during the `docker build` process. On macOS in particular the -default is 2GB, which is not enough to build p4c. Increase the memory limit to +default is 2GB, which is not enough to build P4C. Increase the memory limit to at least 4GB via Docker preferences or you are likely to see "internal compiler errors" from gcc which are caused by low memory. @@ -465,9 +465,9 @@ We run continuous integration to ensure this works with the latest version of Bazel. We also provide a [`p4_library` rule](bazel/p4_library.bzl) for invoking -p4c during the build process of 3rd party Bazel projects. +P4C during the build process of 3rd party Bazel projects. -See [bazel/example](bazel/example) for an example of how to use or extend p4c in +See [bazel/example](bazel/example) for an example of how to use or extend P4C in your own Bazel project. You may use it as a template to get you started. # Build system @@ -516,7 +516,7 @@ Python files should be added to the black and isort target using the following r add_black_files (${CMAKE_CURRENT_SOURCE_DIR} "${MY_SOURCES_AND_HEADERS}") ``` -The p4c CMakeLists.txt will use that name to figure the full path of the files to lint. +The P4C CMakeLists.txt will use that name to figure the full path of the files to lint. clang-format, black, and isort need to be installed before the linter can be used. They can be installed with the following command: ``` @@ -524,7 +524,7 @@ pip3 install --user "clang-format==18.1.0" "black==24.3.0" "isort==5.13.2" ``` clang-format can be checked using the `make clang-format` command. Complaints can be fixed by running `make clang-format-fix-errors`. black and isort can be checked using the `make black` or `make isort` command respectively. Complaints can be fixed by running `make black-fix-errors` or `make isort-fix-errors`. -cpplint, clang-format, and black/isort run as checks as port of p4c's continuous integration process. To make sure that these tests pass, we recommend installing the appropriate git hooks. This can be done by running +cpplint, clang-format, and black/isort run as checks as port of P4C's continuous integration process. To make sure that these tests pass, we recommend installing the appropriate git hooks. This can be done by running ``` ./tools/install_git_hooks.sh ``` @@ -582,14 +582,14 @@ See the documentation for [`p4c_add_tests`](cmake/P4CUtils.cmake) for more information on the arguments to these macros. -To pass custom arguments to p4c, you can set the environment variable `P4C_ARGS`: +To pass custom arguments to P4C, you can set the environment variable `P4C_ARGS`: ``` make check P4C_ARGS="-Xp4c=MY_CUSTOM_FLAG" ``` -When making changes to p4c, it is sometimes useful to be able to run +When making changes to P4C, it is sometimes useful to be able to run the tests while overwriting the expected output files that are saved -in this repository. One such situation is when your changes to p4c +in this repository. One such situation is when your changes to P4C cause the names of compiler-generated local variables to change. To force the expected output files to be rewritten while running the tests, assign a value to the shell environment variable @@ -603,7 +603,7 @@ P4TEST_REPLACE=1 make check Define rules to install your backend. Typically you need to install the binary, the additional architecture headers, and the configuration -file for the p4c driver. +file for the P4C driver. ``` install (TARGETS p4c-mybackend @@ -670,7 +670,7 @@ Educational material on P4: - Introduction to P4Runtime: [Next-Gen SDN Tutorial - Session 1: P4 and P4Runtime Basics](https://www.youtube.com/watch?v=KRx92qSLgo4) # Contact -We appreciate your contributions and look forward to working with you to improve the P4 Compiler Project (p4c)! +We appreciate your contributions and look forward to working with you to improve the P4 Compiler Project (P4C)! - For further assistance or questions regarding contributions, reach out to us in our [community chat](https://p4-lang.slack.com/). [Joining link](https://join.slack.com/t/p4-lang/shared_invite/zt-a9pe96br-Th73ueaBAwJw1ZbD_z1Rpg) . - For general P4-related questions, use the [P4 forum](https://forum.p4.org/). - For other communication channels click [here](https://p4.org/join/). From 691c7f7a3685db24fbf0b2334a05a239dd2f3929 Mon Sep 17 00:00:00 2001 From: Adarsh Date: Mon, 15 Apr 2024 10:25:36 +0530 Subject: [PATCH 2/4] [Docs] Non Breaking changes of "p4c" Acronym --- backends/graphs/README.md | 2 +- .../modules/testgen/targets/bmv2/test/README.md | 2 +- bazel/example/README.md | 6 +++--- docs/CodingStandardPhilosophy.md | 2 +- docs/Eclipse-readme.md | 2 +- docs/README.md | 14 +++++++------- 6 files changed, 14 insertions(+), 14 deletions(-) diff --git a/backends/graphs/README.md b/backends/graphs/README.md index 4c41055d7a..2658ac486a 100644 --- a/backends/graphs/README.md +++ b/backends/graphs/README.md @@ -12,7 +12,7 @@ file formats. ## Dependencies -In addition to other p4c dependencies, this backend requires the Boost graph +In addition to other P4C dependencies, this backend requires the Boost graph headers. On a Debian system, they can be installed with `sudo apt-get install libboost-graph-dev`. diff --git a/backends/p4tools/modules/testgen/targets/bmv2/test/README.md b/backends/p4tools/modules/testgen/targets/bmv2/test/README.md index 197093e9ed..1af60ccd56 100644 --- a/backends/p4tools/modules/testgen/targets/bmv2/test/README.md +++ b/backends/p4tools/modules/testgen/targets/bmv2/test/README.md @@ -6,7 +6,7 @@ CMake Files: How to Run tests: ===================== -1) All p4c submodule tests are tagged with 'testgen-p4c-bmv2' label +1) All P4C submodule tests are tagged with 'testgen-p4c-bmv2' label - cd build/testgen - ctest -R testgen-p4c-bmv2 diff --git a/bazel/example/README.md b/bazel/example/README.md index a724c01e97..55b2c0a9f5 100644 --- a/bazel/example/README.md +++ b/bazel/example/README.md @@ -1,11 +1,11 @@ # Bazel example ![bazel build](https://github.com/p4lang/p4c/workflows/bazel/badge.svg) -This folder contains a toy Bazel project depending on p4c. This is to +This folder contains a toy Bazel project depending on P4C. This is to demonstrate how to: -- set up a Bazel workspace that depends on p4c, +- set up a Bazel workspace that depends on P4C, -- use the `p4_library` rule to invoke p4c during the Bazel build process, and +- use the `p4_library` rule to invoke P4C during the Bazel build process, and - define custom IR extensions. diff --git a/docs/CodingStandardPhilosophy.md b/docs/CodingStandardPhilosophy.md index cc406aaf84..cb6075345b 100644 --- a/docs/CodingStandardPhilosophy.md +++ b/docs/CodingStandardPhilosophy.md @@ -106,7 +106,7 @@ aspects that are overlooked. Therefore, please take the time to think through the information you want to convey and write good, explicit error messages. -An additional goal of the p4c compiler is to provide as many error +An additional goal of the P4C compiler is to provide as many error messages as possible in one go. Therefore, while there is support for `FATAL_ERROR`s, it is desirable to try to continue execution and report all possible errors, using the `error` and `warning` diff --git a/docs/Eclipse-readme.md b/docs/Eclipse-readme.md index fe20450e33..954b951221 100644 --- a/docs/Eclipse-readme.md +++ b/docs/Eclipse-readme.md @@ -2,7 +2,7 @@ # Setting up Eclipse -Use the following installation steps to setup an Eclipse development environment for p4c. +Use the following installation steps to setup an Eclipse development environment for P4C. Note that the following assumes you have already performed the preliminary environment bootstrap, as described in [README](README.md). diff --git a/docs/README.md b/docs/README.md index fc1c8f1128..7b470364bf 100644 --- a/docs/README.md +++ b/docs/README.md @@ -38,7 +38,7 @@ p4c ├── tools -- external programs used in the build/test process │ ├── ci-ptf -- scripts to run PSA PTF tests │ ├── debian-build -- resources and scripts for creating Ubuntu (or Debian) packages -│ ├── driver -- p4c compiler driver: a script that invokes various compilers +│ ├── driver -- P4C compiler driver: a script that invokes various compilers │ ├── hooks -- useful git hooks for development | ├── ir-generator -- code to generate the P4C IR from .def files │ ├── iwyu_mappings -- mappings used by the Include What You Use (IWYU) tool for analyzing #include directives in C and C++ source files @@ -218,8 +218,8 @@ tests are run with a "recently built" version of `simple_switch` from the [p4lang/behavioral-model](https://github.com/p4lang/behavioral-model) repository, but it can be several hours old. If you are working on -p4c features that rely on newly committed changes to `simple_switch` -you can find out which `simple_switch` version these p4c automated +P4C features that rely on newly committed changes to `simple_switch` +you can find out which `simple_switch` version these P4C automated tests are using at the link below: + [https://hub.docker.com/r/p4lang/behavioral-model/builds](https://hub.docker.com/r/p4lang/behavioral-model/builds) @@ -292,7 +292,7 @@ To add a new input test with a sample P4 code file (under `testdata/p4_16_sample ## Compiler Driver -**p4c** is a compiler driver. The goal is to provide a consistent user interface +**P4C** is a compiler driver. The goal is to provide a consistent user interface across different p4 backends and work flows. The compiler driver is written in Python. It can be extended for custom backends. @@ -335,7 +335,7 @@ makefile variable. p4c_PYTHON += p4c.custom.cfg ``` -There is an global variable `config` in p4c compiler driver that stores the build steps +There is an global variable `config` in P4C compiler driver that stores the build steps for a particular target. By default, the bmv2 and ebpf backends are supported. Each backend is identified with a triplet: **target-arch-vendor**. For example, the default bmv2 backend is identified as `bmv2-ss-p4org`. Users may choose to implement different architectures running @@ -354,5 +354,5 @@ config.target.append("bmv2-newarch-p4org") After adding the new configuration file, rerun `bootstrap.sh` -For testing purpose, p4c will be installed in the build/ directory when executing `make`. -User can install `p4c` to other system path by running `make install` +For testing purpose, P4C will be installed in the build/ directory when executing `make`. +User can install `P4C` to other system path by running `make install` From a3860dfa930962ee5873777a0e3ed5bfe2a9adf3 Mon Sep 17 00:00:00 2001 From: Adarsh Rawat Date: Mon, 15 Apr 2024 22:42:11 +0530 Subject: [PATCH 3/4] [Docs] Implement Suggestions --- README.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 5f1d9e4279..be8d692aac 100644 --- a/README.md +++ b/README.md @@ -159,7 +159,7 @@ If you cannot use a repository to install P4C, you can download the `.deb` file for your release and install it manually. You need to download a new file each time you want to upgrade P4C. -1. Go to [p4lang-P4C package page on OpenSUSE Build Service](https://build.opensuse.org/package/show/home:p4lang/p4lang-p4c), click on +1. Go to [p4lang-p4c package page on OpenSUSE Build Service](https://build.opensuse.org/package/show/home:p4lang/p4lang-p4c), click on "Download package" and choose your operating system version. 2. Install P4C, changing the path below to the path where you downloaded the package. @@ -238,7 +238,7 @@ sudo dpkg -i /path/to/package.deb ``` sudo make install ``` - The compiler driver `P4C` and binaries for each of the backends are + The compiler driver `p4c` and binaries for each of the backends are installed in `/usr/local/bin` by default; the P4 headers are placed in `/usr/local/share/p4c`. @@ -309,10 +309,10 @@ After cloning Protobuf and before you build, check-out version 3.25.3: `git checkout v3.25.3` Please note that while all Protobuf versions newer than 3.0 should work for -`P4C` itself, you may run into trouble with some extensions and other p4lang +P4C itself, you may run into trouble with some extensions and other p4lang projects unless you install version 3.25.3. -`P4C` also depends on Google Abseil library. This library is also a pre-requisite for Protobuf of any version newer than 3.21. Therefore the use of Protobuf of suitable version automatically fulfils Abseil dependency. P4C typically installs its own version of Abseil using CMake's `FetchContent` module (Abseil LTS 20240116.1 at the moment). +P4C also depends on Google Abseil library. This library is also a pre-requisite for Protobuf of any version newer than 3.21. Therefore the use of Protobuf of suitable version automatically fulfils Abseil dependency. P4C typically installs its own version of Abseil using CMake's `FetchContent` module (Abseil LTS 20240116.1 at the moment). ### CMake P4C requires a CMake version of at least 3.16.3 or higher. On older systems, a newer version of CMake can be installed using `pip3 install --user cmake==3.16.3`. We have a CI test on Ubuntu 18.04 that uses this option, but there is no guarantee that this will lead to a successful build. From f58ec34a62b65268df52c0f19114bd4dcb2729d7 Mon Sep 17 00:00:00 2001 From: Adarsh Rawat Date: Mon, 15 Apr 2024 22:45:16 +0530 Subject: [PATCH 4/4] [docs] Revert breaking Changes of "p4c" Acronym --- docs/README.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/README.md b/docs/README.md index 7b470364bf..cc6fbfdc71 100644 --- a/docs/README.md +++ b/docs/README.md @@ -292,7 +292,7 @@ To add a new input test with a sample P4 code file (under `testdata/p4_16_sample ## Compiler Driver -**P4C** is a compiler driver. The goal is to provide a consistent user interface +**p4c** is a compiler driver. The goal is to provide a consistent user interface across different p4 backends and work flows. The compiler driver is written in Python. It can be extended for custom backends. @@ -335,7 +335,7 @@ makefile variable. p4c_PYTHON += p4c.custom.cfg ``` -There is an global variable `config` in P4C compiler driver that stores the build steps +There is an global variable `config` in the `p4c` compiler driver that stores the build steps for a particular target. By default, the bmv2 and ebpf backends are supported. Each backend is identified with a triplet: **target-arch-vendor**. For example, the default bmv2 backend is identified as `bmv2-ss-p4org`. Users may choose to implement different architectures running @@ -354,5 +354,5 @@ config.target.append("bmv2-newarch-p4org") After adding the new configuration file, rerun `bootstrap.sh` -For testing purpose, P4C will be installed in the build/ directory when executing `make`. -User can install `P4C` to other system path by running `make install` +For testing purposes, `p4c` will be installed in the build/ directory when executing `make`. +Users can install `p4c` to other system path by running `make install`