Setup to run projects on macOS

Setup for macOS

Shows how to setup zpm for macOS by cloning a sample python app project and using zpm to run commands in it.

See:

User Guide for User Guide for full zpm documentation.
Quick Start for summary of zpm capabilities.

Notes:

"xplat" means "cross-platform"
Assumes Ubuntu 24.04 Desktop or Server, other versions may have slightly different procedures.
These instructions were confirmed for Ubuntu using a VM (see Setup Ubuntu Projects). But I have not been able to do that same double-check with macOS. Therefore it is possible that some repos will have problems when they are freshly installed on a new macOS. But both Ubuntu and macOS have similar scripting and other behaviors, so it is likely if it works okay on Ubuntu, then it will work okay on macOS.

do initial setup

update .bashrc

open terminal, add to favorites if necessary
add these to bashrc; vfox will be added later; .local/bin is used to hold zpm commands

export PATH=$HOME/.local/bin:$PATH
# must be the last line in .bashrc
eval "$(vfox activate bash)"

basic install and config

Run these basic commands

#  ssh is needed for bitbucket/git
#  openssh-client is preinstalled on macos
brew install git
#  curl is preinstalled
#  brltty is not used

# dialout group is not needed

# see proj-man-tester/proj-tester/sample-gitconfig
cp "sample-gitconfig" "${HOME}/.gitconfig"
# see proj-man-tester/proj-tester/sample-nanorc
cp "sample-nanorc" "${HOME}/.nanorc"

# update xcode
# sudo xcode-select --install
# or update it if already install
sudo softwareupdate -i -a

# fix homebrew permissions if needed
sudo chown -R $(whoami):admin /opt/homebrew
sudo chown -R $(whoami):admin ~/Library/Caches/Homebrew
brew doctor

# update brew
brew update
brew upgrade
brew autoremove
brew cleanup --prune=all

set up bitbucket

# === set up SSH key for Bitbucket
# do once: set up ssh key
# see https://support.atlassian.com/bitbucket-cloud/docs/set-up-personal-ssh-keys-on-linux/
ssh-keygen -t ed25519 -b 4096 -C "username@emaildomain.com" -f ~/.ssh/bitbucket
cat ~/.ssh/bitbucket.pub

chmod 600 ~/.ssh/bitbucket*
chmod 600 ~/.ssh/known_hosts

# for convenience, add this to your .ssh/config file:
nano .ssh/config
Host bitbucket.org
    HostName bitbucket.org
    User git
    Port 22
    AddKeysToAgent yes
    IdentityFile /home/your_userid/.ssh/bitbucket
    IdentitiesOnly yes

save to your bitbucket account
- Open Bitbucket
- go to settings (the cog icon)
- select "Person Bitbucket settings"
- select "SSH keys"
- click "Add key"
- dlgbox "Add SSH key"
  - enter a Label to remember which machine this is for
  - paste the content of bitbucket.pub into "Key"
- click "Add key"
test the connection

ssh -T git@bitbucket.org

Run a project the first time

Assumes the project will be created in the ~/projects directory.

See Dev Python Application Template page for a description.

Note that the python apps are all very similar to devpy-app-template. That holds for other templates as well:

python modules: Dev Python Module Template
ruby apps: Dev Ruby Application Template
ruby gems: Dev Ruby Gem Template
C/C++ apps: Dev C++ Application Template
C/C++ libraries: Dev C++ Library Template
arduino apps: Dev Arduino Application Template
arduino libraries: not available at this time

Note:

some repos are cross-technology e.g. pyalmake uses Python, C/C++, Arduino as well as SWIG.
some are "other" technologies e.g. test_flutter uses Dart/Flutter. These still use Python as a zpm tool, but have they have their own toolset for docs, compilation, etc.
Eventually, I would like to replace Python with a better cross-platform language e.g. golang. The effort is high but it should make this intial setup hopefully easier and faster.

set up destination folder for the repo

mkdir -p projects
# web-ver holds version info
mkdir -p projects/web-ver
cd ~/projects

clone the project

git clone git@bitbucket.org:arrizza-public/devpy-app-template.git
cd devpy-app-template

do initial zpm setup

Do an initial setup and install of zpm, cross-platform utilities and shared python venv. Note that tools/zpm will create ~/.local/bin and install zpm into it

tools/zpm xplat-install
# takes 3m or so

reset terminal

close terminal
open a new one
this updates the vfox PATHs and other environment variables
ensure you are in the repo: cd ~/projects/devpy-app-template

install anything else needed by the current repo

zpm install full
# takes 2m or so

install environment

Install the shared python environment or ruby gems or other modules provided by the specific language

zpm env-install full
# takes 1m or so

check it worked

Run basic zpm commands to check it worked okay

zpm check    # has some errors related to doxygen
# note: some other languages use their own doc generator, 
# so zpm check will have a warning that doxygen or dot is missing
zpm doc      # should be an out/doc directory with HTML
zpm check    # now should be no warnings/errors

zpm doc true # gen the PDF
open out/devpy-app-template.pdf

# for GUI based repos, you must run with the Ubuntu Desktop. They will not work from an SSH terminal

# for arduino repos, ensure the arduino is connected and powered on. 
# If you are using a VM select Devices | USB and ensure it is selected

# for cpp/arduino repos, do this additional step, otherwise zpm lint may have some warnings
zpm mk-gen

zpm lint     # run the appropriate linter
zpm ver      # run any verification tests if any; note resets the coverage info
zpm ut       # run the UTs if any; check coverage by opening out/coverage/index.html; should be around 91% coverage
zpm doit     # run the app or sample lib/module

# note: some repos e.g. pyalamake has a ./do_auto_test run that here, ensure rc is 0

(optional) additional checks

Check various settings, PATH is correctly set, various directories were created

# double-check the PATH
echo $PATH
echo $PATH | tr ':' '\n'  # to see it one line at a time
# check that at least these are in the path
#   $HOME/.vfox/sdks/python/bin
#   $HOME/.local/bin

# double-check vfox was installed and python is installed
ls -al ~/.vfox/sdks
# should be at least python:
lrwxrwxrwx 1 your-userid your-userid   55 May 31 21:27 python -> /your-home/.vfox/cache/python/v-3.12.3/python-3.12.3

# double-check xplat utilites and venv were created
ls ~/.local/share/xplat-common
# should be:
drwxrwxr-x  3 your-userid your-userid 4096 Mar  2 20:54 v2.0.0
drwxrwxr-x  7 your-userid your-userid 4096 May 31 18:39 venv

# check a softlink to xplat_utils is created locally
ll tools
lrwxrwxrwx 1 your-userid your-userid   58 Jul 15 17:53 xplat_utils -> /your-home/.local/share/xplat-common/v2.0.0/xplat_utils/

# should give a quick summary of required modules installed:
zpm env-install fast # or just "zpm env-install"
#     found  43 reqmts in venv
#     installing for python app