Skip to content

Improve organization of developer guide. #832

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
May 28, 2025
Merged

Improve organization of developer guide. #832

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .vscode/launch.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -247,7 +247,7 @@
}
},
{
"name": "Attach to process",
"name": "Attach to pylith (mpinemesis)",
"type": "cppdbg",
"request": "attach",
"processId": "${command:pickProcess}",
Expand Down
115 changes: 67 additions & 48 deletions docs/Makefile.am
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -701,66 +701,85 @@ dist_noinst_DATA = \
user/meshing/cubit.md \
user/meshing/gmsh.md \
user/meshing/gmsh-utils.md \
developer/design/overview.md \
developer/design/code-layout.md \
developer/design/index.md \
developer/design/application-flow.md \
developer/contributing/documentation/install.md \
developer/contributing/documentation/index.md \
developer/contributing/documentation/quickref.md \
developer/contributing/examples.md \
developer/contributing/newmaterial.md \
developer/contributing/coding-style.md \
developer/contributing/figs/classdiagram_material.png \
developer/contributing/figs/classdiagram_material.pdf \
developer/contributing/figs/classdiagram_solution.png \
developer/contributing/figs/classdiagram_solution.pdf \
developer/contributing/figs/material_auxiliarylayout.pdf \
developer/contributing/figs/material_auxiliarylayout.png \
developer/contributing/workflow.md \
developer/contributing/codingstyle.md \
developer/contributing/rebuilding.md \
developer/contributing/petscfem.md \
developer/contributing/index.md \
developer/contributing/codelayout.md \
developer/contributing/git-quickref.md \
developer/contributing/new-example.md \
developer/contributing/new-material.md \
developer/git-workflow/overview.md \
developer/git-workflow/figs/gitworkflow_repositories.tex \
developer/git-workflow/figs/gitworkflow_branch.tex \
developer/git-workflow/figs/gitworkflow_branch.pdf \
developer/git-workflow/figs/gitworkflow_branch.png \
developer/git-workflow/figs/gitworkflow_repositories.png \
developer/git-workflow/figs/gitworkflow_repositories.pdf \
developer/git-workflow/tasks.md \
developer/git-workflow/index.md \
developer/git-workflow/git-quickref.md \
developer/debugging/ci-docker.md \
developer/debugging/fields.md \
developer/debugging/index.md \
developer/debugging/tools.md \
developer/testing/libtests.md \
developer/testing/run-cxxtests.md \
developer/testing/fullscale.md \
developer/testing/ci-docker.md \
developer/testing/pytests.md \
developer/testing/mmstests.md \
developer/testing/fields.md \
developer/testing/index.md \
developer/testing/debugging-tools.md \
developer/testing/performance-tools.md \
developer/ides/vs-code.md \
developer/ides/index.md \
developer/index.md \
developer/contributing/figs/classdiagram_bc.pdf \
developer/contributing/figs/classdiagram_bc.png \
developer/contributing/figs/classdiagram_bc.tex \
developer/contributing/figs/classdiagram_material.pdf \
developer/contributing/figs/classdiagram_material.png \
developer/contributing/figs/classdiagram_material.tex \
developer/contributing/figs/classdiagram_mesher.pdf \
developer/contributing/figs/classdiagram_mesher.svg \
developer/contributing/figs/classdiagram_mesher.tex \
developer/contributing/figs/classdiagram_output.pdf \
developer/contributing/figs/classdiagram_output.png \
developer/contributing/figs/classdiagram_output.tex \
developer/contributing/figs/classdiagram_physics_fem.pdf \
developer/contributing/figs/classdiagram_physics_fem.png \
developer/contributing/figs/classdiagram_physics_fem.tex \
developer/contributing/figs/classdiagram_problem.pdf \
developer/contributing/figs/classdiagram_problem.png \
developer/contributing/figs/classdiagram_problem.tex \
developer/contributing/figs/classdiagram_pylithapp.pdf \
developer/contributing/figs/classdiagram_pylithapp.png \
developer/contributing/figs/classdiagram_pylithapp.tex \
developer/contributing/figs/classdiagram_solution.pdf \
developer/contributing/figs/classdiagram_solution.png \
developer/contributing/figs/classdiagram_solution.tex \
developer/contributing/figs/gitworkflow_branch.pdf \
developer/contributing/figs/gitworkflow_branch.png \
developer/contributing/figs/gitworkflow_branch.tex \
developer/contributing/figs/gitworkflow_repositories.pdf \
developer/contributing/figs/gitworkflow_repositories.png \
developer/contributing/figs/gitworkflow_repositories.tex \
developer/contributing/figs/material_auxiliarylayout.pdf \
developer/contributing/figs/material_auxiliarylayout.png \
developer/contributing/figs/material_auxiliarylayout.tex \
developer/contributing/figs/meshtopology.pdf \
developer/contributing/figs/meshtopology.png \
developer/contributing/figs/meshtopology.tex \
developer/contributing/figs/umlstyle.tex
developer/implementation/figs/classdiagram_output.png \
developer/implementation/figs/classdiagram_material.tex \
developer/implementation/figs/classdiagram_output.pdf \
developer/implementation/figs/classdiagram_pylithapp.pdf \
developer/implementation/figs/classdiagram_mesher.tex \
developer/implementation/figs/classdiagram_physics_fem.png \
developer/implementation/figs/classdiagram_problem.tex \
developer/implementation/figs/classdiagram_mesher.svg \
developer/implementation/figs/classdiagram_physics_fem.pdf \
developer/implementation/figs/classdiagram_pylithapp.png \
developer/implementation/figs/classdiagram_problem.pdf \
developer/implementation/figs/classdiagram_physics_fem.tex \
developer/implementation/figs/classdiagram_mesher.pdf \
developer/implementation/figs/classdiagram_problem.png \
developer/implementation/figs/classdiagram_pylithapp.tex \
developer/implementation/figs/classdiagram_output.tex \
developer/implementation/figs/classdiagram_material.png \
developer/implementation/figs/classdiagram_material.pdf \
developer/implementation/figs/classdiagram_solution.png \
developer/implementation/figs/meshtopology.pdf \
developer/implementation/figs/classdiagram_bc.tex \
developer/implementation/figs/classdiagram_solution.pdf \
developer/implementation/figs/meshtopology.png \
developer/implementation/figs/material_auxiliarylayout.tex \
developer/implementation/figs/material_auxiliarylayout.pdf \
developer/implementation/figs/umlstyle.tex \
developer/implementation/figs/material_auxiliarylayout.png \
developer/implementation/figs/classdiagram_solution.tex \
developer/implementation/figs/classdiagram_bc.png \
developer/implementation/figs/classdiagram_bc.pdf \
developer/implementation/figs/meshtopology.tex \
developer/implementation/petsc-fem.md \
developer/implementation/index.md \
developer/implementation/object-organization.md \
developer/performance/index.md \
developer/performance/logging.md \
developer/performance/tools.md \
developer/building/index.md


# End of file
29 changes: 11 additions & 18 deletions docs/developer/contributing/rebuilding.md → docs/developer/building/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,23 +6,16 @@ For instructions on how to build PyLith from source, please see the [PyLith Inst

Updating and rebuilding PETSc is quite simple once it has been configured and built once before.

:::{warning}
Updating the PETSc `knepley/pylith` branch that PyLith uses almost always involves rebasing and forced pushes.
As a result, you cannot simply use `git pull` to update the `knepley/pylith` branch.
Instead, you need to delete the old `knepley/pylith` branch and then check it out again to get the current version.
:::

```{code-block} bash
# Change to PETSc source Directory
cd $PETSC_DIR

# Switch to the main branch and fetch the updates, pruning deleted branches.
git checkout main
# Fetch the updates, pruning deleted branches.
git fetch -p

# Remove your old knepley/pylith branch and then get the current knepley/pylith branch.
git branch -D knepley/pylith
# Ensure you are on the `knepley/pylith` branch and then pull updates.
git checkout knepley/pylith
git pull

# Reconfigure
arch-pylith-debug/lib/petsc/conf/reconfigure-arch-pylith-debug.py
Expand All @@ -47,8 +40,8 @@ Note that the `m4` directory is a Git submodule corresponding to the `geodynamic

### Updating your fork

It is a good idea to keep your `main` branch and any other branches you use from the `geodynamics/pylith` repository up to date.
See {ref}`sec-developer-merge-upstream` for how to merge updates from the upstream (`geodynamics/pylith`) repository.
As long as you setup your `main` branch to correspond to `upstream/main`, you should never have to use the `main` branch in your fork.
You only use your fork for your feature branches.

### Makefiles

Expand Down Expand Up @@ -92,11 +85,11 @@ caption: Rebuilding Pylith C++ library, SWIG modules, and Python modules
# Change to top-level PyLith build directory.
cd $PYLITH_BUILDDIR

# Reinstall everything using 8 threads to build library.
make install -j8
# Reinstall everything using 16 threads to build library.
make install -j16

# Rebuild and reinstall only the library using 8 threads.
make install -j8 -C libsrc
# Rebuild and reinstall only the library using 16 threads.
make install -j16 -C libsrc

# Rebuild and reinstall only the SWIG modules
make install -C modulesrc
Expand All @@ -114,8 +107,8 @@ caption: Rebuilding Pylith C++ library and rerunning the C++ unit tests
# Change to top-level PyLith build directory.
cd $PYLITH_BUILDDIR/build/pylith-debug

# Rebuild the library using 8 threads.
make -j8 -C libsrc
# Rebuild the library using 16 threads.
make -j16 -C libsrc

# Rerun the C++ unit tests.
make check -C tests/libtests
Expand Down
Loading