С чего начать?
-- здесь я сохраняю старую инструкцию МосХаб, мой текст начинается на # symbCpp
Для быстрого старта на МосХаб мы подготовили список рекомендованных следующих шагов.
Вы профессионал? Тогда просто отредактируйте этот файл README.md так, как считаете нужным. Хотите сделать это еще легче? Используйте шаблон в конце данного документа!
Добавьте свои файлы в репозиторий
-
Создайте или загрузите файлы -
Добавьте файлы посредством командной строки или сделайте пуш существующего репозитория Git при помощи следующих команд:
cd existing_repo
git remote add origin https://hub.mos.ru/sblinnikov/symb.git
git branch -M main
git push -uf origin main
Интегрируйте собственные инструменты
Работайте совместно с командой
-
Пригласите к участию участников команды или коллег -
Создайте новый запрос на слияние -
Автоматически закрывайте задачи при помощи запроса на слияние -
Включите согласование запросов на слияние -
Выполняйте автоматическое слияние веток при успешном завершении конвейера CI/CD
Отредактируйте этот файл README
Когда вы готовы сделать этот файл README своим, просто отредактируйте его и используйте удобный шаблон ниже (или сделайте все по-своему - это ведь отправная точка вашего проекта).
Предложения для написания хорошего файла README
Все проекты отличаются друг от друга, так что для начала решите, какие из разделов применимы к вашему проекту. Эти разделы используются в качестве шаблона для большинства проектов разработки ПО с открытым исходным кодом. Также примите во внимание, что слишком длинный и детальный README все же лучше, чем слишком короткий. Если ваш README вам кажется слишком длинным, рассмотрите иные способы документирования, не предполагающие сокращение детальности информации.
Название проекта
Выберите такое название проекта, которое говорит само за себя
Описание
Дайте людям знать о специфических возможностях вашего проекта. Предоставьте контекст и добавьте ссылки на все дополнительные материалы, с которыми посетители вашего проекта могут быть незнакомы. Сюда же можно добавить список фич и подраздел с описанием окружений. Если есть проекты похожие на ваш, этот раздел будет тем местом, где можно описать ключевые отличия вашего проекта от других аналогичных проектов.
Бейджи
В некоторых файлах README вы могли видеть маленькие значки, обозначающие разнообразные метаданные, такие как статус прохождения проектов различных тестов. Вы можете воспользоваться сервисом Shields для добавление некоторых подобных бейджей в ваш README. Многие другие сервисы, включая МосХаб, также предоставляют инструкции по добавлению бейджей.
Скриншоты
В зависимости от того, над чем вы работаете, хорошей идеей может быть включение в README скриншотов или даже видео (обычно в виде GIF-анимации). Инструменты наподобие ttygif могут вам в этом помочь.
Установка
В рамках конкретной экосистемы разработки могут существовать общеизвестные способы установки софта, такие как Yarn, NuGet или Homebrew. Тем не менее, примите во внимание возможность того, что читатель вашего README может быть новичком, которому могут потребоваться более подробные указания. Перечисление конкретных шагов поможет устранить неопределенность и побудить людей начать использование вашего проекта как можно скорее.
Если ваш проект работает только в специфическом контексте (например, только на конкретной версии языка программирования), или он требует ручной установки специфических зависимостей, рекомендуется добавить дополнительный подраздел "Требования"
Примеры использования
По возможности сопровождайте ваш проект примерами использования и показывайте ожидаемый результат работы приложения. Полезно встроить небольшие примеры использования непосредственно в файл README, а также дать ссылки на более сложные примеры, если они слишком длинные для включения в файл README.
Поддержка
Объясните людям, где они могут получить техническую поддержку. Это может быть трекер задач, чат, адрес электронной почты и т.п.
Дорожная карта
Если у вас есть идеи для будущих релизов, их можно перечислить в данном разделе README.
Внести свой вклад
Если вы открыты ко вкладам сообщества, явно напишите об этом, а также перечислите требования, которые должны выполнить желающие внести свой вклад.
Для людей, которые хотят внести изменения в ваш проект, будет полезно иметь документацию о том, как им начать делать это. Возможно, им будет нужно запустить какой-либо скрипт или установить некие переменные окружения. Явно опишите требуемые шаги. Эти инструкции будут полезны вам самим в будущем.
Вы также можете внести в документ команды для запуска необходимых линтеров или тестов. Эти шаги помогут обеспечить высокое качество кода и уменьшить вероятность изменений, которые могут что-то непреднамеренно сломать. Инструкции по запуску тестов особенно полезны в случае, если для тестов требуются настройки сторонних инструментов, таких как сервер Selenium для тестирования веб-приложений.
Авторы и благодарности
Выразите свою благодарность тем, кто вносит вклад в ваш проект.
Лицензия
Для проектов с открытым исходным кодом необходимо указать лицензию, то есть явно написать о том, на каких условиях другие люди могут использовать ваш проект. Отсутствие информации о лицензии будет расцениваться как запрет легального использования вашего проекта. О видах лицензий можно прочитать тут.
Статус проекта
Если у вас не хватает сил или времени на ваш проект, сообщите об этом в начале файла README. Сообщите о том, что работа над проектом будет происходить медленно или будет совсем остановлена. Кто-нибудь может захотеть сделать форк вашего проекта, или найдется доброволец, готовый взять на себя роль сопровождающего вашего проекта, чтобы проект продолжал развиваться. Вы также можете явно написать о том, что ищете сопровождающего на ваш проект.
symbCpp
The source for this project is mostly taken from http://issc.uj.ac.za/symbolic/symbolic.html "Official website"
(seems to be not updated after 2010) with examples from
Quantum Mechanics Using Computer Algebra: Includes Sample Programs in C++, SymbolicC++, Maxima, Maple, and Mathematica W.-H. Steeb, Yorick Hardy: World Scientific, 2010 - Mathematics - 234 pages.
The goal of this project is not developing SymbolicC++, but rather showing simple recipes to work with it and developing examples for Quantum Mechanics in SymbolicC++, as well as Maxima (wxMaxima) and Mathematica. The examples are in the directory examples, see also doc.
SymbolicC++ was originally written as a collection of header files for C++. Many of the functions and classes provided are template functions and classes and in general cannot be compiled in as part of a library.
This project attempts to extract the parts of SymbolicC++ that can be compiled as part of a library and so create the include / library infrastructure. The src and include directories are populated by scripts from the SymbolicC++ header files.
Install
Installation to /usr/local
To install to /usr/local:
$ ./configure
$ make
$ make install
To compile a program using SymbolicC++ with GCC:
$ g++ -o program program.cpp -lsymbolicc++
To run the program:
$ ./program
A brief PDF document describing SymbolicC++ is provided (doc/introsymb.tex, produce doc/introsymb.pdf from it) and is installed as /usr/local/share/doc/SymbolicC++.pdf.
Installation elsewhere
This section describes installation to a directory "where_to_install". The directory must be a full path, i.e. it should not begin with "./" or "../".
To install:
$ ./configure --prefix=where_to_install
$ make
$ make install
** If the directory is a standard system directory, proceed as described ** in the section "Installation to /usr/local" above.
Compile
To compile a program using SymbolicC++ with GCC (all on one line):
g++ -I where_to_install/include
-L where_to_install/lib
-o program program.cpp -lsymbolicc++
Run
When running the program, make sure that the dynamic libraries can be located, for example by modifying /etc/ld.so.conf or by setting the LD_LIBRARY_PATH (for Bourne shell compatible shells)
$ ./program
Shared object "libsymbolicc++.so.3" not found
$ LD_LIBRARY_PATH=${LD_LIBRARY_PATH}:where_to_install/lib
$ export LD_LIBRARY_PATH
$ ./program
...
Documentation
A brief PDF document describing SymbolicC++ is provided (doc/introsymb.tex, produce doc/introsymb.pdf from it) and is installed as where_to_install/share/doc/SymbolicC++.pdf.
Important remarks
Description above, taken from the Official site for SymbolicC++, does not work due to the error:
/usr/local/lib//libsymbolicc++.so: undefined reference to `Number<int>::Number(int const&)'
/usr/local/lib//libsymbolicc++.so: undefined reference to `Number<double>::Number(double const&)'
collect2: error: ld returned 1 exit status
Next lines work (option -fno-elide-constructors is needed on 64bit systems, not on 32bit):
cd examples/
g++ -o test1.exe test1.cpp -fno-elide-constructors ../src/*.cpp
g++ -o matrix.exe matrix.cpp -fno-elide-constructors ../src/*.cpp
but it works only if include/ dir is in a known place, e.g. in /usr/local, if not, then do in this directory:
g++ -I include -o matrix.exe examples/matrix.cpp -fno-elide-constructors src/*.cpp
or put after -I the path to the place where you have copied the include/ dir from this directory
Now gflibsymb.sh works which has lines
#!/bin/tcsh
g++ -I include -c -fno-elide-constructors src/*.cpp
ar cvr ~/lib/libsymbcgf.a *.o
ar ts ~/lib/libsymbcgf.a
exit
This builds libsymbcgf.a in HOME/lib. Then quick translation is possible:
g++ -I ./include -L ~/lib -o test1.exe examples/test1.cpp -fno-elide-constructors -lsymbcgf
g++ -I ./include -L ~/lib -o matrix.exe examples/matrix.cpp -fno-elide-constructors -lsymbcgf
g++ -I ./include -L ~/lib -o loperators.exe examples/loperators.cpp -fno-elide-constructors -lsymbcgf
For 32bit systems use gf32libsymb.sh, and commands like
g++ -I ./include -L ~/lib -o test1.exe examples/test1.cpp -lsymbcgf
g++ -I ./include -L ~/lib -o bose.exe examples/bose.cpp -lsymbcgf
g++ -I ./include -L ~/lib -o separation.exe examples/separation.cpp -lsymbcgf
For intel icpc use library built with iclibsymb.sh and
icpc -I ./include -L ~/lib -o test1.exe examples/test1.cpp -lsymbc
icpc -I ./include -L ~/lib -o matrix.exe examples/matrix.cpp -lsymbc
Addendum for numerics
TREFOR
Use directory trefor to build a useful preprocessor for structured program design in fortran.
TREFOR==TREe FORtran
Read README there
Examples in Structured Programming
Directory trefor/StructProgramming has elementary examples from D.Gries etc. written in trefor (trn)