From a644a0db396832100256a7139fb4eb5bdde091d1 Mon Sep 17 00:00:00 2001 From: Georgios Kafanas Date: Wed, 7 Feb 2024 18:12:21 +0100 Subject: [PATCH 1/2] [REFACTORING] Remove vestigial submodules The submodules are removed because: - The submodules are not used in the generation of the website. - The use of links in the submodule ignore files breaks the new interface of Git. --- .gitmodules | 4 ---- .submodules/Makefiles | 1 - 2 files changed, 5 deletions(-) delete mode 160000 .submodules/Makefiles diff --git a/.gitmodules b/.gitmodules index 708c8e74..e69de29b 100644 --- a/.gitmodules +++ b/.gitmodules @@ -1,4 +0,0 @@ -[submodule ".submodules/Makefiles"] - path = .submodules/Makefiles - url = https://github.com/Falkor/Makefiles.git - branch = devel diff --git a/.submodules/Makefiles b/.submodules/Makefiles deleted file mode 160000 index 83928159..00000000 --- a/.submodules/Makefiles +++ /dev/null @@ -1 +0,0 @@ -Subproject commit 839281599ddf3645a06ab4111a08a5d4f59004de From 87628042ed4ef4f91d0253b0b1810fc64ca34ce8 Mon Sep 17 00:00:00 2001 From: Georgios Kafanas Date: Sun, 11 Feb 2024 18:13:15 +0100 Subject: [PATCH 2/2] [REFACTORING] Simplify installation instructions using Conda and venv - Remove the Makefile. - Add instructions to install the required packages using - Conda to install the required Python version, and - installing the required packages either in a Conda environment, or in a venv that used the Python installed in the Conda environment. --- Makefile | 478 ------------------------------------------------------ README.md | 105 +++--------- 2 files changed, 23 insertions(+), 560 deletions(-) delete mode 100644 Makefile diff --git a/Makefile b/Makefile deleted file mode 100644 index 9c13714c..00000000 --- a/Makefile +++ /dev/null @@ -1,478 +0,0 @@ -#################################################################################### -# Makefile (configuration file for GNU make - see http://www.gnu.org/software/make/) -# Time-stamp: -# __ __ _ __ _ _ -# | \/ | __ _| | _____ / _(_) | ___ -# | |\/| |/ _` | |/ / _ \ |_| | |/ _ \ -# | | | | (_| | < __/ _| | | __/ -# |_| |_|\__,_|_|\_\___|_| |_|_|\___| -# -# Copyright (c) 2012 Sebastien Varrette -# . http://varrette.gforge.uni.lu -# -#################################################################################### -# -############################## Variables Declarations ############################## -SHELL = /bin/bash - -UNAME = $(shell uname) - -# Some directories -SUPER_DIR = $(shell basename `pwd`) - -XDG_CACHE_HOME ?= $(HOME)/.cache -XDG_CONFIG_HOME ?= $(HOME)/.config -XDG_DATA_HOME ?= $(HOME)/.local/share - -# Git stuff management -HAS_GITFLOW = $(shell git flow version 2>/dev/null || [ $$? -eq 0 ]) -LAST_TAG_COMMIT = $(shell git rev-list --tags --max-count=1) -LAST_TAG = $(shell git describe --tags $(LAST_TAG_COMMIT) ) -TAG_PREFIX = "v" -# GITFLOW_BR_MASTER = $(shell git config --get gitflow.branch.master) -# GITFLOW_BR_DEVELOP = $(shell git config --get gitflow.branch.develop) -GITFLOW_BR_MASTER=production -GITFLOW_BR_DEVELOP=master - -CURRENT_BRANCH = $(shell git rev-parse --abbrev-ref HEAD) -GIT_BRANCHES = $(shell git for-each-ref --format='%(refname:short)' refs/heads/ | xargs echo) -GIT_REMOTES = $(shell git remote | xargs echo ) -GIT_ROOTDIR = $(shell git rev-parse --show-toplevel) -GIT_HOOKSDIR = .git/hooks -SRC_HOOKSDIR = config/hooks -#SRC_HOOKSDIR_TO_ROOTDIR = $(shell git -C "$(GIT_ROOTDIR)/$(SRC_HOOKSDIR)" rev-parse --show-cdup) -SRC_PRECOMMIT_HOOK = $(wildcard $(SRC_HOOKSDIR)/pre-commit*.sh) - -GIT_DIRTY = $(shell git diff --shortstat 2> /dev/null | tail -n1 ) -# Git subtrees repositories -# Format: '[|]' - don't forget the quotes. if branch is ignored, 'master' is used -#GIT_SUBTREE_REPOS = 'https://github.com/ULHPC/easybuild-framework.git|develop' \ - 'https://github.com/hpcugent/easybuild-wiki.git' -GITSTATS = ./.submodules/gitstats/gitstats -GITSTATS_DIR = gitstats -# Below variable is used to sanitize stats by defining the (lowercase) strings to be -# substituted to aggregate stats from the same author (eventually using different mails) -# Ex: GITSTATS_SUBSTITUTE_PATTERN_CMD="sed -e 's///' -e 's//'" -GITSTATS_SUBSTITUTE_PATTERN_CMD=sed -e '\#' - -# Branches to update on 'make up' -GIT_BRANCHES_TO_UPDATE = $(GITFLOW_BR_DEVELOP) $(GITFLOW_BR_MASTER) - -ifeq (,$(wildcard .bumpversion.cfg)) -VERSION = $(shell [ -f VERSION ] && head VERSION || echo '0.0.1') -else -VERSION = $(shell bumpversion --dry-run --allow-dirty --list minor | grep current_version | cut -d '=' -f 2) -endif - -# OR try to guess directly from the last git tag -#VERSION = $(shell git describe --tags $(LAST_TAG_COMMIT) | sed "s/^$(TAG_PREFIX)//") -MAJOR = $(shell echo $(VERSION) | sed "s/^\([0-9]*\).*/\1/") -MINOR = $(shell echo $(VERSION) | sed "s/[0-9]*\.\([0-9]*\).*/\1/") -PATCH = $(shell echo $(VERSION) | sed "s/[0-9]*\.[0-9]*\.\([0-9]*\).*/\1/") -# total number of commits -BUILD = $(shell git log --oneline | wc -l | sed -e "s/[ \t]*//g") -#REVISION = $(shell git rev-list $(LAST_TAG).. --count) -ifeq (,$(wildcard .bumpversion.cfg)) -NEXT_MAJOR_VERSION = $(shell expr $(MAJOR) + 1).0.0-b$(BUILD) -NEXT_MINOR_VERSION = $(MAJOR).$(shell expr $(MINOR) + 1).0-b$(BUILD) -NEXT_PATCH_VERSION = $(MAJOR).$(MINOR).$(shell expr $(PATCH) + 1)-b$(BUILD) -else -NEXT_MAJOR_VERSION = $(shell expr $(MAJOR) + 1).0.0 -NEXT_MINOR_VERSION = $(MAJOR).$(shell expr $(MINOR) + 1).0 -NEXT_PATCH_VERSION = $(MAJOR).$(MINOR).$(shell expr $(PATCH) + 1) -endif - -# Python stuff -# See https://pip.pypa.io/en/stable/user_guide/#requirements-files -PIP_REQUIREMENTS_FILE = requirements.txt - -##################### Main targets ##################### -# Default targets - append your own with TARGETS += -TARGETS = -# Default targets for 'make [dist]clean' - append your own with [DIST]CLEAN_TARGETS += [dist]clean- -CLEAN_TARGETS = clean-gitstats -DISTCLEAN_TARGETS = -# Default targets for 'make setup' - append your own with SETUP_TARGETS += setup- -SETUP_TARGETS = setup-git setup-gitflow setup-submodules setup-subtrees setup-githooks -# Default targets for 'make git-clone'. To append your own: -# Define -GIT_CLONE_TARGETS = - - -################### Custom Makefile ################### -# Local configuration - Kept for compatibity reason -LOCAL_MAKEFILE = .Makefile.local - -# Makefile custom hooks -MAKEFILE_CUSTOM = .Makefile.custom -MAKEFILE_BEFORE = .Makefile.before -MAKEFILE_AFTER = .Makefile.after - -### Main variables -.PHONY: all info archive clean help release start_bump_major start_bump_minor start_bump_patch subtree_setup subtree_up subtree_diff upgrade versioninfo doc - -############################### Now starting rules ################################ -# Load local settings, if existing (to override variable eventually) -ifneq (,$(wildcard $(LOCAL_MAKEFILE))) -include $(LOCAL_MAKEFILE) -endif -ifneq (,$(wildcard $(MAKEFILE_BEFORE))) -include $(MAKEFILE_BEFORE) -endif -ifneq (,$(wildcard $(MAKEFILE_CUSTOM))) -include $(MAKEFILE_CUSTOM) -endif - -### Below default could be set in .Makefile.{local,before} -# Default python virtualenv - by default under venv/$(basename ) -PYTHON_VENV_DIR ?= venv -PYTHON_VENV ?= $(SUPER_DIR) -# Default Git clone parameters (url, target path for the working directory) -PYENV_GIT_REPO_URL ?= https://github.com/pyenv/pyenv.git -PYENV_GIT_REPO ?= $(XDG_DATA_HOME)/pyenv -PYENV_VIRTUALENV_GIT_REPO_URL ?= https://github.com/pyenv/pyenv-virtualenv.git -PYENV_VIRTUALENV_GIT_REPO ?= $(XDG_DATA_HOME)/pyenv/plugins/pyenv-virtualenv - -# Required rule : what's to be done each time -all: $(TARGETS) - -# Test values of variables - for debug purposes -info: - @echo "--- Compilation commands --- " - @echo "HAS_GITFLOW -> '$(HAS_GITFLOW)'" - @echo "--- Directories --- " - @echo "SUPER_DIR -> '$(SUPER_DIR)'" - @echo "XDG_CONFIG_HOME -> '$(XDG_CONFIG_HOME)'" - @echo "XDG_CACHE_HOME -> '$(XDG_CACHE_HOME)'" - @echo "XDG_DATA_HOME -> '$(XDG_DATA_HOME)'" - @echo "--- Git stuff ---" - @echo "GIT_ROOTDIR -> '$(GIT_ROOTDIR)'" - @echo "GITFLOW -> '$(GITFLOW)'" - @echo "GITFLOW_BR_MASTER -> '$(GITFLOW_BR_MASTER)'" - @echo "GITFLOW_BR_DEVELOP -> '$(GITFLOW_BR_DEVELOP)'" - @echo "CURRENT_BRANCH -> '$(CURRENT_BRANCH)'" - @echo "GIT_BRANCHES -> '$(GIT_BRANCHES)'" - @echo "GIT_REMOTES -> '$(GIT_REMOTES)'" - @echo "GIT_DIRTY -> '$(GIT_DIRTY)'" - @echo "GIT_SUBTREE_REPOS -> '$(GIT_SUBTREE_REPOS)'" - @echo "GIT_BRANCHES_TO_UPDATE -> '$(GIT_BRANCHES_TO_UPDATE)'" - @echo "GIT_HOOKSDIR -> '$(GIT_HOOKSDIR)'" - @echo "SRC_HOOKSDIR -> '$(SRC_HOOKSDIR)'" - @echo "SRC_HOOKSDIR_TO_ROOTDIR-> '$(SRC_HOOKSDIR_TO_ROOTDIR)'" - @echo "SRC_PRECOMMIT_HOOK -> '$(SRC_PRECOMMIT_HOOK)'" - @echo "--- Python stuff ---" - @echo "PYTHON_VENV_DIR -> '${PYTHON_VENV_DIR}'" - @echo "PYTHON_VENV -> '${PYTHON_VENV}'" - @echo "PYENV_GIT_REPO_URL -> '${PYENV_GIT_REPO_URL}'" - @echo "PYENV_GIT_REPO -> '${PYENV_GIT_REPO}'" - @echo "PYENV_VIRTUALENV_GIT_REPO_URL -> '${PYENV_VIRTUALENV_GIT_REPO_URL}'" - @echo "PYENV_VIRTUALENV_GIT_REPO -> '${PYENV_VIRTUALENV_GIT_REPO}'" - @echo "" - @echo "Consider running 'make versioninfo' to get info on git versionning variables" - -############################### Archiving ################################ -archive: clean - tar -C ../ -cvzf ../$(SUPER_DIR)-$(VERSION).tar.gz --exclude ".svn" --exclude ".git" --exclude "*~" --exclude ".DS_Store" $(SUPER_DIR)/ - -############################### Git Bootstrapping rules ################################ -.PHONY: setup setup-git setup-gitflow setup-xdg setup-git-lfs -setup: $(SETUP_TARGETS) - @if [ -d "$(GIT_ROOTDIR)/$(SRC_HOOKSDIR)" ]; then \ - echo "=> setup local git hooks"; \ - $(MAKE) setup_git_hooks; \ - fi - @if [ -f .gitattributes ] && [ -n "$(shell grep '=lfs' .gitattributes)" ]; then \ - echo "=> setup git-lfs"; \ - $(MAKE) setup-git-lfs; \ - fi - @if [ -f .envrc ]; then \ - $(MAKE) setup-direnv; \ - fi - -setup-git: - -git fetch origin - -git branch --track $(GITFLOW_BR_MASTER) origin/$(GITFLOW_BR_MASTER) - -setup-gitflow: - git config gitflow.branch.master $(GITFLOW_BR_MASTER) - git config gitflow.branch.develop $(GITFLOW_BR_DEVELOP) - git config gitflow.prefix.feature feature/ - git config gitflow.prefix.release release/ - git config gitflow.prefix.hotfix hotfix/ - git config gitflow.prefix.support support/ - git config gitflow.prefix.versiontag $(TAG_PREFIX) - -setup-submodules: - -$(MAKE) update - -setup-subtrees: - $(if $(GIT_SUBTREE_REPOS), $(MAKE) subtree_setup) - -setup-githooks: - @if [ -d "$(GIT_ROOTDIR)/$(SRC_HOOKSDIR)" ]; then \ - echo "=> setup local git hooks"; \ - $(MAKE) _setup_git_hooks; \ - fi - -_setup_git_hooks: - @if [ -n "$(SRC_PRECOMMIT_HOOK)" ]; then \ - if [ -f "$(GIT_ROOTDIR)/$(SRC_PRECOMMIT_HOOK)" ] && [ ! -f "$(GIT_ROOTDIR)/$(GIT_HOOKSDIR)/pre-commit" ]; then \ - echo "=> setup Git pre-commit hook"; \ - ln -s ../../$(SRC_PRECOMMIT_HOOK) $(GIT_ROOTDIR)/$(GIT_HOOKSDIR)/pre-commit; \ - fi ; \ - fi - -ifneq (,$(shell which git-lfs 2>/dev/null)) -setup-git-lfs: - git-lfs pull -else -setup-git-lfs: - @echo "*** ERROR *** git-lfs extension not found on your system" - @echo " install it (see https://git-lfs.github.com/) and run " - @echo " make $@" -endif - -setup-xdg: - @echo "=> setup XDG Base Directories" - mkdir -p $(XDG_CONFIG_HOME) - mkdir -p $(XDG_DATA_HOME) - mkdir -p $(XDG_CACHE_HOME) - -define __SHELL_PROFILE_SOURCE_IF_PRESENT - -# Add the following to your favorite shell config (~/.bashrc or ~/.zshrc etc.) -if [ -f "$1" ]; then - . $1 -fi - -endef -.PHONY: setup-shell-direnv setup-shell-pyenv -setup-shell-direnv: - $(info $(call __SHELL_PROFILE_SOURCE_IF_PRESENT,$(XDG_CONFIG_HOME)/direnv/init.sh)) -setup-shell-pyenv: - $(info $(call __SHELL_PROFILE_SOURCE_IF_PRESENT,$(XDG_CONFIG_HOME)/pyenv/init.sh)) - - -# --- Direnv -.PHONY: setup-direnv setup-pyenv setup-venv setup-python -setup-direnv: setup-xdg - @echo "=> setup direnv -- see https://varrette.gforge.uni.lu/tutorials/pyenv.html" - mkdir -p $(XDG_CONFIG_HOME)/direnv - @if [ ! -f "$(XDG_CONFIG_HOME)/direnv/init.sh" ]; then \ - echo " - creating $(XDG_CONFIG_HOME)/direnv/init.sh"; \ - curl -o $(XDG_CONFIG_HOME)/direnv/init.sh https://raw.githubusercontent.com/Falkor/dotfiles/master/shell/available/direnv.sh; \ - fi - @echo " - sample override of direnv-stdlib in $(XDG_CONFIG_HOME)/direnv/direnvrc" - @if [ ! -f "$(XDG_CONFIG_HOME)/direnv/direnvrc" ]; then \ - curl -o $(XDG_CONFIG_HOME)/direnv/direnvrc https://raw.githubusercontent.com/Falkor/dotfiles/master/direnv/direnvrc; \ - fi - @echo " - sample '.envrc' for your projects in $(XDG_CONFIG_HOME)/direnv/envrc" - @if [ ! -f "$(XDG_CONFIG_HOME)/direnv/envrc" ]; then \ - curl -o $(XDG_CONFIG_HOME)/direnv/envrc https://raw.githubusercontent.com/Falkor/dotfiles/master/direnv/envrc; \ - fi - @$(MAKE) setup-shell-direnv - -# --- pyenv -setup-pyenv: setup-xdg git-clone-pyenv git-clone-pyenv-virtualenv - @echo "=> setup pyenv -- see https://varrette.gforge.uni.lu/tutorials/pyenv.html" - mkdir -p $(XDG_CONFIG_HOME)/pyenv - @if [ ! -f "$(XDG_CONFIG_HOME)/pyenv/init.sh" ]; then \ - echo " - creating $(XDG_CONFIG_HOME)/pyenv/init.sh"; \ - curl -o $(XDG_CONFIG_HOME)/pyenv/init.sh https://raw.githubusercontent.com/Falkor/dotfiles/master/shell/available/pyenv.sh; \ - fi - @$(MAKE) setup-shell-pyenv - -# --- venv -setup-venv: - python3 -m venv $(PYTHON_VENV_DIR)/$(PYTHON_VENV) - -# --- python -ifneq (,$(wildcard ./$(PIP_REQUIREMENTS_FILE))) -setup-python: - @echo "=> updating pip version" - pip install --upgrade pip - @echo "=> installing Python dependencies from Requirements files '$(PIP_REQUIREMENTS_FILE)'" - pip install -r $(PIP_REQUIREMENTS_FILE) -else -setup-python: - @echo "=> updating pip version" - pip install --upgrade pip -endif - - - -### Git clone -####### -# Usage: $(eval $(call __GIT_CLONE,,,)) -## -define __GIT_CLONE -.PHONY: git-clone-$1 -git-clone-$1: - @if [ ! -d "$2" ]; then \ - mkdir -p $(shell dirname $2); \ - echo "=> cloning '$3' into $2"; \ - git clone $3 $2; \ - else \ - echo "... existing directory '$2', thus exiting"; \ - fi -GIT_CLONE_TARGETS += git-clone-$1 -endef -$(eval $(call __GIT_CLONE,pyenv,$(PYENV_GIT_REPO),$(PYENV_GIT_REPO_URL))) -$(eval $(call __GIT_CLONE,pyenv-virtualenv,$(PYENV_VIRTUALENV_GIT_REPO),$(PYENV_VIRTUALENV_GIT_REPO_URL))) - -fetch: - git fetch --all -v - -versioninfo: - @echo "Current version: $(VERSION)" - @echo "Last tag: $(LAST_TAG)" - @echo "$(shell git rev-list $(LAST_TAG).. --count) commit(s) since last tag" - @echo "Build: $(BUILD) (total number of commits)" - @echo "next major version: $(NEXT_MAJOR_VERSION)" - @echo "next minor version: $(NEXT_MINOR_VERSION)" - @echo "next patch version: $(NEXT_PATCH_VERSION)" - -### Git flow management -ifeq ($(HAS_GITFLOW),) -start_bump_patch start_bump_minor start_bump_major release: - @echo "Unable to find git-flow on your system. " - @echo "See https://github.com/nvie/gitflow for installation details" -else - -define __VERSION_BUMP -start_bump_$1: - $$(if $$(GIT_DIRTY), $$(error "Unable to bump version: Dirty Git repository")) - @echo "Start the '$1' release of the repository from $$(VERSION) to $2" - git pull origin - git flow release start $2 - @sleep 1 - @if [ -f VERSION ]; then \ - echo $2 > VERSION; \ - git commit -s -m "$1 bump to version $2" VERSION; \ - fi - @if [ -f .bumpversion.cfg ]; then \ - echo "=> using 'bumpversion [...] $1'"; \ - bumpversion --commit --no-tag $1; \ - fi - @echo "=> run 'make release' once you finished the bump" -endef - -$(eval $(call __VERSION_BUMP,patch,$(NEXT_PATCH_VERSION))) -$(eval $(call __VERSION_BUMP,minor,$(NEXT_MINOR_VERSION))) -$(eval $(call __VERSION_BUMP,major,$(NEXT_MAJOR_VERSION))) - -release: clean - @if [ -f .bumpversion.cfg ]; then \ - echo "=> release using 'bumpversion [...] release'"; \ - bumpversion --commit --no-tag release; \ - fi - git flow release finish -s $(VERSION:%rc=%) - git checkout $(GITFLOW_BR_MASTER) - git push origin - git checkout $(GITFLOW_BR_DEVELOP) - git push origin - git push origin --tags -endif - -### Git (submodule|branch) management: pull and upgrade to the latest version -up update: - $(if $(GIT_DIRTY), $(error "Unable to pull latest commits: Dirty Git repository")) - @for br in $(GIT_BRANCHES_TO_UPDATE); do \ - echo -e "\n=> Pulling and updating the local branch '$$br'\n"; \ - git checkout $$br; \ - git pull origin $$br; \ - done - git checkout $(CURRENT_BRANCH) - @echo "=> updating (NOT upgrading) git submodule" - git submodule init - git submodule update - -### Git submodule upgrade -upgrade: update - git submodule foreach 'git fetch origin; git checkout $$(git rev-parse --abbrev-ref HEAD); git reset --hard origin/$$(git rev-parse --abbrev-ref HEAD); git submodule update --recursive; git clean -dfx' - -@for submoddir in $(shell git submodule status | awk '{ print $$2 }' | xargs echo); do \ - git commit -s -m "Upgrading Git submodule '$$submoddir' to the latest version" $$submoddir || true;\ - done - - -### Git subtree management -ifeq ($(GIT_SUBTREE_REPOS),) -subtree_setup subtree_diff subtree_up: - @echo "no repository configured in GIT_SUBTREE_REPOS..." -else -subtree_setup: - @for elem in $(GIT_SUBTREE_REPOS); do \ - url=`echo $$elem | cut -d '|' -f 1`; \ - repo=`basename $$url .git`; \ - if [[ ! "$(GIT_REMOTES)" =~ "$$repo" ]]; then \ - echo "=> initializing Git remote '$$repo'"; \ - git remote add -f $$repo $$url; \ - fi \ - done - -subtree_diff: - @for elem in $(GIT_SUBTREE_REPOS); do \ - url=`echo $$elem | cut -d '|' -f 1`; \ - repo=`basename $$url .git`; \ - path=`echo $$repo | tr '-' '/'`; \ - br=`echo $$elem | cut -d '|' -f 2`; \ - [ "$$br" == "$$url" ] && br='master'; \ - echo -e "\n============ diff on subtree '$$path' with remote '$$repo/$$br' ===========\n"; \ - git diff $${repo}/$$br $(CURRENT_BRANCH):$$path; \ - done - -subtree_up: - $(if $(GIT_DIRTY), $(error "Unable to pull subtree(s): Dirty Git repository")) - @for elem in $(GIT_SUBTREE_REPOS); do \ - url=`echo $$elem | cut -d '|' -f 1`; \ - repo=`basename $$url .git`; \ - path=`echo $$repo | tr '-' '/'`; \ - br=`echo $$elem | cut -d '|' -f 2`; \ - [ "$$br" == "$$url" ] && br='master'; \ - echo -e "\n===> pulling changes into subtree '$$path' using remote '$$repo/$$br'"; \ - echo -e " \__ fetching remote '$$repo'"; \ - git fetch $$repo; \ - echo -e " \__ pulling changes"; \ - git subtree pull --prefix $$path --squash $${repo} $${br}; \ - done -endif - - -### [Dist]Clean option -clean: $(CLEAN_TARGETS) -distclean: $(DISTCLEAN_TARGETS) - -clean-gitstats: - @if [ -d "$(GITSTATS_DIR)" ]; then \ - echo "==> removing '$(GITSTATS_DIR)' directory"; \ - rm -rf $(GITSTATS_DIR); \ - fi - -# Perform various git statistics -stats: - @if [ ! -d $(GITSTATS_DIR) ]; then mkdir -p $(GITSTATS_DIR); fi - @if [ -x "$(GITSTATS)" ]; then $(GITSTATS) . $(GITSTATS_DIR)/; fi - @echo "=> Git commits (based on 'git log --pretty=\"%al\")" - @git log --pretty="%al" | tr '[A-Z]' '[a-z]' | $(GITSTATS_SUBSTITUTE_PATTERN_CMD) | tr '.' ' ' | awk '{print toupper(substr($$0,1,1))substr($$1,2),toupper(substr($$2,1,1))substr($$2,2)}' | sort | uniq -c | sort -r -# left part mail force lowercase replace . capitalize $1 $1 (doubling $) -doc: - @if [ -n "`which mkdocs`" ]; then \ - mkdocs serve; \ - fi - - -# print help message -help : - @echo '+----------------------------------------------------------------------+' - @echo '| Available Commands |' - @echo '+----------------------------------------------------------------------+' - @echo '| make setup: Initiate git-flow for your local copy of the repository|' - @echo '| make start_bump_{major,minor,patch}: start a new version release with|' - @echo '| git-flow at a given level (major, minor or patch bump) |' - @echo '| make release: Finalize the release using git-flow |' - @echo '+----------------------------------------------------------------------+' - - -ifneq (,$(wildcard $(MAKEFILE_AFTER))) -include $(MAKEFILE_AFTER) -endif diff --git a/README.md b/README.md index 6e79e082..eb426b92 100644 --- a/README.md +++ b/README.md @@ -19,99 +19,40 @@ Inspired by the _excellent_ [NERSC Technical documentation](https://docs.nersc.g This repository is hosted on [Github](https://github.com/ULHPC/ulhpc-docs). To clone it, proceed as follows (adapt accordingly): ```bash -mkdir -p ~/git/github.com/ULHPC/ -cd ~/git/github.com/ULHPC git clone https://github.com/ULHPC/ulhpc-docs.git # or for SSH interactions: git clone git@github.com:ULHPC/ulhpc-docs.git ``` -**`/!\ IMPORTANT`**: Once cloned, initiate your local copy of the repository by running: - -```bash -$> cd ulhpc-docs -$> make setup +To use the repository, you need to install some Python packages along with a compatible version of Python. If your system Python is compatible, simply install the packages in `requirements.txt`, ideally in a `venv`. For instance: ``` - -This will initiate the [Git submodules of this repository](.gitmodules) and setup the [git flow](https://www.atlassian.com/git/tutorials/comparing-workflows/gitflow-workflow) layout for this repository. It will also ensure python components ([direnv](https://direnv.net/), [pyenv](https://github.com/pyenv/pyenv) and [`pyenv-virtualenv`](https://github.com/pyenv/pyenv-virtualenv)) are installed. - -Later on, you can update your local branches by running: - - make up - -If upon pulling the repository, you end in a state where another collaborator have upgraded the Git submodules for this repository, you'll end in a dirty state (as reported by modifications within the `.submodules/` directory). In that case, just after the pull, you **have to run** `make up` to ensure consistency with regards the Git submodules: - -Finally, you can upgrade the [Git submodules](.gitmodules) to the latest version by running: - - make upgrade - - -## Python Virtualenv / Pyenv and Direnv - -You will have to ensure you have installed [direnv](https://direnv.net/), configured by [`.envrc`](.envrc)), [pyenv](https://github.com/pyenv/pyenv) and [`pyenv-virtualenv`](https://github.com/pyenv/pyenv-virtualenv). This assumes also the presence of `~/.config/direnv/direnvrc` from [this page](https://github.com/Falkor/dotfiles/blob/master/direnv/direnvrc) - for more details, see [this blog post](https://varrette.gforge.uni.lu/blog/2019/09/10/using-pyenv-virtualenv-direnv/). - -```bash -### TL;DR; installation -# Mac OS -brew install direnv pyenv pyenv-virtualenv -# Linux/WSL -sudo { apt-get | yum | ... } install direnv -curl -L https://raw.githubusercontent.com/pyenv/pyenv-installer/master/bin/pyenv-installer | bash -export PATH="$HOME/.pyenv/bin:$PATH" -pyenv root # Should return $HOME/.pyenv +$ python3 -m venv "${HOME}/environments/ulhpc-docs" +$ source ~/environments/ulhpc-docs/bin/activate +$ pip install --upgrade pip +$ pip install --requirement requirements.txt ``` -**Assuming** you have configured the [XDG Base Directories](https://specifications.freedesktop.org/basedir-spec/latest/) in your favorite shell configuration (`~/.bashrc`, `~/.zshrc` or `~/.profile`), you can enable direnv and pyenv as follows +If your system Python is not compatible the with require packages, we suggest that you install Python in a Conda environment using the [Micromamba](https://mamba.readthedocs.io/en/latest/user_guide/micromamba.html) package manager for Conda. -```bash -# XDG Base Directory Specification -# See https://specifications.freedesktop.org/basedir-spec/latest/ -export XDG_CONFIG_HOME=$HOME/.config -export XDG_CACHE_HOME=$HOME/.cache -export XDG_DATA_HOME=$HOME/.local/share -# [...] -# Direnv - see https://direnv.net/ -if [ -f "$HOME/.config/direnv/init.sh" ]; then - . $HOME/.config/direnv/init.sh -fi -# - pyenv: https://github.com/pyenv/pyenv -# - pyenv-virtualenv: https://github.com/pyenv/pyenv-virtualenv -export PYENV_ROOT=$HOME/.pyenv -export PATH="${PYENV_ROOT}/bin:${PYENV_ROOT}/plugins/pyenv-virtualenv/bin:$PATH" -if [ -n "$(which pyenv)" ]; then - eval "$(pyenv init -)" - eval "$(pyenv virtualenv-init -)" - export PYENV_VIRTUALENV_DISABLE_PROMPT=1 -fi +- Begin by [installing the Micromamba package manager](https://mamba.readthedocs.io/en/latest/installation/micromamba-installation.html). +- Install Python 3.8 in a new environment. ``` - -Source your shell configuration file. -You can now run the following command to setup your local machine in a compliant way (this was normally done as part of the `make setup` step) : - -```bash -# Global Direnv Setup (to be done only once) -make setup-direnv -make setup-pyenv +$ micromamba env create --name ulhpc-docs-python +$ micromamba install python=3.8 --channel conda-forge --name ulhpc-docs-python ``` - - -Running `direnv allow` (this will have to be done only once), you should automatically enable the virtualenv `ulhpc-docs` based on the python version specified in [`.python-version`](.python-version). You'll eventually need to install the appropriate Python version with `pyenv`: - -```bash -pyenv versions # Plural: show all versions -pyenv install $(head .python-version) -# Activate the virtualenv by reentering into the directory -direnv allow . -pyenv version # check current pyenv[-virtualenv] version. MUST return the vurtualenv 'ulhpc-docs' +- You now have 2 options. First options is to install the required python packages directly in the Conda environment. ``` - -From that point, you should install the required packages using: - -``` bash -make setup-python - -# OR (manually) -pip install --upgrade pip -pip install -r requirements.txt +$ micromamba activate ulhpc-docs-python +$ pip install --upgrade pip +$ pip install --requirement requirements.txt ``` +- Alternatively, you can create a `venv` environment in which you install the packages. +``` +$ micromamba run --name ulhpc-docs-python python -m venv "${HOME}/environments/ulhpc-docs" +$ source ~/environments/ulhpc-docs/bin/activate +$ pip install --upgrade pip +$ pip install --requirement requirements.txt +``` + +The `ulhpc-docs` `venv` environment will automatically use the Python installed in the Conda environment `ulhpc-docs-python`. In the later case you will no longer need to interact with the Conda environment, except perhaps for updating the Python executable. # Documentation