From c501a76878b17899da9e9f9871ac3f107c4b37ec Mon Sep 17 00:00:00 2001 From: psommerfeld Date: Sun, 13 Apr 2025 11:54:13 -0700 Subject: [PATCH] Re-order Pixi commands and update Mac instructions in index.md Pixi build commands were listed before the git clone commands which doesn't make sense. Put the commands in more proper sequence as they would be executed. Before, Pixi was described as a good way to compile, then later only CMake is mentioned. Broke up Build section to provide both Pixi and CMake build methods. Mentioned 'brew install pre-commit' as Mac method to install pre-commit --- gettingstarted/index.md | 66 ++++++++++++++++++++++------------------- 1 file changed, 36 insertions(+), 30 deletions(-) diff --git a/gettingstarted/index.md b/gettingstarted/index.md index 638f59f..d0a99c3 100644 --- a/gettingstarted/index.md +++ b/gettingstarted/index.md @@ -38,28 +38,6 @@ One of the easiest ways of creating a standalone FreeCAD build environment with - Windows (PowerShell): `iwr -useb https://pixi.sh/install.ps1 | iex` - Linux/macOS: `curl -fsSL https://pixi.sh/install.sh | bash` -2. Configure FreeCAD for your platform. There are additional steps necessary on Windows outlined in the next subsection. - - `pixi run configure` - -3. Build FreeCAD - - `pixi run build` - - If your computer has less ram than is necessary to run a compiler per processor core, then you can reduce the number of parallel compiler jobs. For example, if you wish to limit to 4 parallel compiler processes use the following command: - - `pixi run build -j 4` - -4. Run FreeCAD - - `pixi run freecad` - -In general, there will be no need to re-run the configure command as it will be automatically run by `pixi run build` if needed. However, there may be times in which a git submodule is added or updated. To integrate these changes, the command `pixi run initialize` will run the commands necessary. - -### Pixi on Windows - -Pixi uses the `conda-forge` packages, including the `compilers` metapackage to bring in the platform-specific compiler support. On Windows, it is expected that Microsoft Visual C++ has been installed and matches the version used by the `conda-forge` team, which is [Visual Studio Community 2019](https://visualstudio.microsoft.com/vs/older-downloads/#visual-studio-2019-and-other-products). - The Visual Studio Installer may be used to install Visual Studio Community 2019 alongside newer versions of Visual Studio. Ensure all of the necessary components are installed: 1. Open the Visual Studio Installer @@ -77,31 +55,59 @@ The Visual Studio Installer may be used to install Visual Studio Community 2019 2. Clone your fork: for example, on the command line you can use `git clone --recurse-submodules https://github.com/YourUsername/FreeCAD FreeCAD-src` 3. Set up `pre-commit` (our automatic code-formatter and checker): - - Install `pre-commit` (either using your system package manager or pip): - Debian/Ubuntu: `apt install pre-commit` - - Fedora: `dnf install pre-commit` (Fedora) + - Fedora: `dnf install pre-commit` - Arch Linux: `pacman -S pre-commit` + - Mac: `brew install pre-commit` - Other (pip in PATH): `pip install pre-commit` - Other (pip not in PATH): `python -m pip install pre-commit` - On a command line, change into your FreeCAD clone, e.g. `cd FreeCAD-src` - Run `pre-commit install` (or `python -m pre-commit install`, depending on your PATH) - - 4. We **strongly** recommend doing an out-of-source build, that is, build FreeCAD and put all generated files in a separate directory. Otherwise, the build files will be spread all over the source code and it will be much harder to sort out one from the other. A build directory can be created outside the FreeCAD source folder or inside: - `mkdir build` - `cd build` -5. Run CMake, either in via the CMake GUI or on the command line see the wiki compilation page for your operating system for a detailed list of options. -6. CMake will generate project files that can be read by your IDE of choice. See your IDE's documentation for details. In general: +If you are using Pixi, configure it. From the FreeCAD base directory: + + - `pixi run configure` + +### Pixi on Windows + +Pixi uses the `conda-forge` packages, including the `compilers` metapackage to bring in the platform-specific compiler support. On Windows, it is expected that Microsoft Visual C++ has been installed and matches the version used by the `conda-forge` team, which is [Visual Studio Community 2019](https://visualstudio.microsoft.com/vs/older-downloads/#visual-studio-2019-and-other-products). + +## Building + +### Building with Pixi + +From the FreeCAD base directory, if you have sufficient RAM, run: + + pixi run build + +If your computer has less ram than is necessary to run a compiler per processor core, then you can reduce the number of parallel compiler jobs. For example, if you wish to limit to 4 parallel compiler processes use the following command: + + pixi run build -j 4 + +5. Run FreeCAD + + pixi run freecad + +In general, there will be no need to re-run the configure command as it will be automatically run by `pixi run build` if needed. However, there may be times in which a git submodule is added or updated. To integrate these changes, the command `pixi run initialize` will run the commands necessary. + +### Building with CMake + +6. Run CMake, either in via the CMake GUI or on the command line see the wiki compilation page for your operating system for a detailed list of options. +7. CMake will generate project files that can be read by your IDE of choice. See your IDE's documentation for details. In general: - On Linux, compile with a command like `cmake --build /path/to/FreeCAD-src` run from your build directory ( or `cmake --build ..` if your build directory is inside FreeCAD-src). - On Windows with Visual Studio, build the "ALL_BUILD target" (you will have to change the path to the final executable the first time you try to run that target). - On Mac on the command line use `cmake --build /path/to/FreeCAD-src` from your build directory, or if using CLion be sure to "Build All" the first time you run. -7. If you plan on submitting a PR, create a branch: +## Making Changes + +8. If you plan on submitting a PR (pull request), create a branch: - `git branch fixTheThing` - `git checkout fixTheThing` (or both commands in one go: `git checkout -b fixTheThing`) @@ -111,7 +117,7 @@ The Visual Studio Installer may be used to install Visual Studio Community 2019 - [Visual Studio Code](./VSCode.md) - [CLion](./CLion.md) -## Submitting a PR +## Submitting a PR (Pull Request) The basic process is: