From d6bf8033475ef68321b39eaeacce848517f4befd Mon Sep 17 00:00:00 2001 From: Tom Henderson Date: Thu, 29 Dec 2022 23:42:46 -0300 Subject: [PATCH] docs: document clean commands for the tutorial --- doc/tutorial/source/getting-started.rst | 38 +++++++++++++++++++++++++ 1 file changed, 38 insertions(+) diff --git a/doc/tutorial/source/getting-started.rst b/doc/tutorial/source/getting-started.rst index a034ea757..2bbb46ba1 100644 --- a/doc/tutorial/source/getting-started.rst +++ b/doc/tutorial/source/getting-started.rst @@ -933,6 +933,44 @@ current libraries from the ``build`` directory, but some users may find it useful if their use case involves working with programs outside of the |ns3| directory. +Clean +===== + +Cleaning refers to the removal of artifacts (e.g. files) generated or edited +by the build process. There are different levels of cleaning possible: + ++----------+-------------------+--------------------------------------------------------------------------------+ +| Scope | Command | Description | ++==========+===================+================================================================================+ +| clean | `./ns3 clean` | Remove artifacts generated by the CMake configuration and the build | ++----------+-------------------+--------------------------------------------------------------------------------+ +| distclean| `./ns3 distclean` | Remove artifacts from the configuration, build, documentation, test and Python | ++----------+-------------------+--------------------------------------------------------------------------------+ +| ccache | `ccache -C` | Remove all compiled artifacts from the ccache | ++----------+-------------------+--------------------------------------------------------------------------------+ + +`clean` can be used if the focus is on reconfiguring the way that ns-3 is +presently being compiled. `distclean` can be used if the focus is +on restoring the ns-3 directory to an original state. + +The ccache lies outside of the ns-3 directory (typically in a hidden +directory at `~/.cache/ccache`) and is shared across projects. +Users should be aware that cleaning the ccache will cause cache misses +on other build directories outside of the current working directory. +Cleaning this cache periodically may be helpful to reclaim disk space. +Cleaning the ccache is completely separate from cleaning any files +within the ns-3 directory. + +Because clean operations involve removing files, the option conservatively +refuses to remove files if one of the deleted files or directories lies +outside of the current working directory. Users may wish to precede the +actual clean with a `--dry-run`, when in doubt about what the clean +command will do, because a dry run will print the warning if one exists. +For example:: + + ./ns3 clean --dry-run + ./ns3 clean + One ns3 =======