dupeguru/README.md

# dupeGuru

[dupeGuru][dupeguru] is a cross-platform (Linux, OS X, Windows) GUI tool to find duplicate files in
a system. It's written mostly in Python 3 and has the peculiarity of using
[multiple GUI toolkits][cross-toolkit], all using the same core Python code. On OS X, the UI layer
is written in Objective-C and uses Cocoa. On Linux, it's written in Python and uses Qt5.

The Cocoa UI of dupeGuru is hosted in a separate repo: https://github.com/hsoft/dupeguru-cocoa

## Current status: Additional Maintainers Wanted (/ Note on Things in General)

When I started contributing to dupeGuru, it was to help provide an updated Windows build for dupeGuru.  I hoped to contribute more over time and help work through some of the general issues as well.  Since Virgil Dupras left as the lead maintainer, I have not been able to devote enough time to work through as many issues as I had hoped.  Now I am going to be devoting a more consistent amount of time each month to work on dupeGuru, however I will not be able to get to all issues.  Additionally there are a few specific areas where additional help would be appreciated:

- OSX maintenance
  - UI issues (I have no experience with cocoa)
  - General issues & releases (I lack OSX environments / hardware to develop and test on, looking into doing builds through Travis CI.)
- Linux maintenance
  - Packaging (I have not really done much linux packaging yet, although will be spending some time trying to get at least .deb and potentially ppa's updated.)

I am still working to update the new site & update links within the help and the repository to use the new urls.  Additionally, hoping to get a 4.0.4 release out this year for at least Windows and Linux.

Thanks,

Andrew Senetar

## Contents of this folder

This folder contains the source for dupeGuru. Its documentation is in `help`, but is also
[available online][documentation] in its built form. Here's how this source tree is organised:

* core: Contains the core logic code for dupeGuru. It's Python code.
* qt: UI code for the Qt toolkit. It's written in Python and uses PyQt.
* images: Images used by the different UI codebases.
* pkg: Skeleton files required to create different packages
* help: Help document, written for Sphinx.
* locale: .po files for localisation.

There are also other sub-folder that comes from external repositories and are part of this repo as
git submodules:

* hscommon: A collection of helpers used across HS applications.
* qtlib: A collection of helpers used across Qt UI codebases of HS applications.

## How to build dupeGuru from source

### Windows
For windows instructions see the [Windows Instructions](Windows.md).

### Prerequisites

* [Python 3.4+][python]
* PyQt5

### make

dupeGuru is built with "make":

    $ make
    $ make run

### Generate Ubuntu packages

    $ bash -c "pyvenv --system-site-packages env && source env/bin/activate && pip install -r requirements.txt && python3 build.py --clean && python3 package.py"

### Running tests

The complete test suite is run with [Tox 1.7+][tox]. If you have it installed system-wide, you
don't even need to set up a virtualenv. Just `cd` into the root project folder and run `tox`.

If you don't have Tox system-wide, install it in your virtualenv with `pip install tox` and then
run `tox`.

You can also run automated tests without Tox. Extra requirements for running tests are in
`requirements-extra.txt`. So, you can do `pip install -r requirements-extra.txt` inside your
virtualenv and then `py.test core hscommon`

[dupeguru]: https://dupeguru.voltaicideas.net/
[cross-toolkit]: http://www.hardcoded.net/articles/cross-toolkit-software
[documentation]: http://dupeguru.voltaicideas.net/help/en/
[python]: http://www.python.org/
[pyqt]: http://www.riverbankcomputing.com
[tox]: https://tox.readthedocs.org/en/latest/
Tweaked README 2013-06-24 20:20:05 +00:00			`# dupeGuru`
Updated README to include clearer build instructions 2013-06-23 01:43:24 +00:00
Initial Update of Windows Packaging (#438) * Update run.py & .gitignore for windows - Update run.py to execute on windows as SIGQUIT is not available. - Update .gitignore to ignore the generate .pyd files Ref #300, #393 * Update package.py for windows Add package_windows back into package.py - Using cx_freeze for freezing installation - Will be using nsis for actual installer Tested with python 3.5 64bit on windows 10 Ref #393 * Update makefile for windows (+2 misc) - Update the makefile to support windows - Use different bin path in virtualenv - Use pyd instead of so files - Tested with Msys2 - Add .exe to .gitignore - Fix minor format error in package.py Ref #393 Add requirements-windows Add the requirements-windows.txt - contains cx-Freeze for bundling Ref #393 * Add initial setup.nsi Initial Version of a NSIS installer script - Multi-user install (install for just one or all) - Registers uninstaller (more values need to finish up) - Tested both single and all install / uninstall and works - Still need to add parameters instead of hardcoded values in some spots - Need to clean up vendor folders / keys if empty on uninstall - Need to add the other dupeGuru languages to the language list - Minor cleanup of script needed as well Ref #393 * Update setup.nsi Updates to setup.nsi including: - Defines from CLI - Version information (MAJOR, MINOR, PATCH) - Bits (64 / 32) - SourcePath (if we wanted something other than build) - Added extra defines to move application specifics to one location - Added extra defines for uninstall information - Added calculation of install size - Added switching between 64 and 32 bit contexts (need to verify functionality) - Updated output file naming - Added NSIS supported languages which are also supported by dupeGuru - Added rest of registry keys for uninstall information - Added missing registry key for installType - Added removeing Vendor folder and registry key if empty on uninstall Should be very close to having this installer script ready to integrate into the package.py script if desired. Ref #393 * Update README & requirements-windows Minor update to README to indicate windows is supported. Add PyQt5 to requirements-windows.txt to make installation easier. * Update packaging for windows - Update package.py to integrate NSIS for windows - Update makefile to deal with a few additional windows issues - Add Windows.md to contain specific windows instructions, if we want this can be merged with README.md - Minor formatting update to setup.nsi Ref #393 * Update README & Windows Instructions - Update the README to include a reference to the Windows instructions. - Add some additional notes into Windows Instructions and remove one incorrect command. - Update .gitignore to ignore all permutations of env* to allow for multiple side by side virtual environments (used to build different versions for windows) Ref: #393 * Update Window.md Fix broken python link and move nsis link for consistency. * More Details in Windows.md Update Windows.md including: - Information on compilier requirements for windows - Notes about the windows 10 sdk - Some clarification around some of the steps - Addition of msys2 links Going to review this a bit more to polish it up. Ref #393. 2017-08-28 23:27:17 +00:00			`[dupeGuru][dupeguru] is a cross-platform (Linux, OS X, Windows) GUI tool to find duplicate files in`
Updated README 2013-12-01 16:26:30 +00:00			`a system. It's written mostly in Python 3 and has the peculiarity of using`
			`[multiple GUI toolkits][cross-toolkit], all using the same core Python code. On OS X, the UI layer`
Bump python requirement to v3.4 2016-05-27 23:28:19 +00:00			`is written in Objective-C and uses Cocoa. On Linux, it's written in Python and uses Qt5.`
Updated README 2013-12-01 16:26:30 +00:00
Remove cocoa The cocoa UI code now lives in dupeguru-cocoa. 2017-03-12 01:41:47 +00:00			`The Cocoa UI of dupeGuru is hosted in a separate repo: https://github.com/hsoft/dupeguru-cocoa`

Update README.md and ISSUE_TEMPLATE.md - Update ISSUE_TEMPLATE.md to help obtain better information for bug reports. - Update README.md to reflect more recent changes and highlight areas of need. 2018-10-11 02:12:01 +00:00			`## Current status: Additional Maintainers Wanted (/ Note on Things in General)`
Add Current Status section to README 2015-04-12 19:31:01 +00:00
Update README.md and ISSUE_TEMPLATE.md - Update ISSUE_TEMPLATE.md to help obtain better information for bug reports. - Update README.md to reflect more recent changes and highlight areas of need. 2018-10-11 02:12:01 +00:00			When I started contributing to dupeGuru, it was to help provide an updated Windows build for dupeGuru. I hoped to contribute more over time and help work through some of the general issues as well. Since Virgil Dupras left as the lead maintainer, I have not been able to devote enough time to work through as many issues as I had hoped. Now I am going to be devoting a more consistent amount of time each month to work on dupeGuru, however I will not be able to get to all issues. Additionally there are a few specific areas where additional help would be appreciated:
Add Current Status section to README 2015-04-12 19:31:01 +00:00
Update README.md and ISSUE_TEMPLATE.md - Update ISSUE_TEMPLATE.md to help obtain better information for bug reports. - Update README.md to reflect more recent changes and highlight areas of need. 2018-10-11 02:12:01 +00:00			`- OSX maintenance`
			`- UI issues (I have no experience with cocoa)`
			`- General issues & releases (I lack OSX environments / hardware to develop and test on, looking into doing builds through Travis CI.)`
			`- Linux maintenance`
			`- Packaging (I have not really done much linux packaging yet, although will be spending some time trying to get at least .deb and potentially ppa's updated.)`
Add Current Status section to README 2015-04-12 19:31:01 +00:00
Update README.md and ISSUE_TEMPLATE.md - Update ISSUE_TEMPLATE.md to help obtain better information for bug reports. - Update README.md to reflect more recent changes and highlight areas of need. 2018-10-11 02:12:01 +00:00			`I am still working to update the new site & update links within the help and the repository to use the new urls. Additionally, hoping to get a 4.0.4 release out this year for at least Windows and Linux.`
Updated README 2013-12-01 16:26:30 +00:00
Update README.md and ISSUE_TEMPLATE.md - Update ISSUE_TEMPLATE.md to help obtain better information for bug reports. - Update README.md to reflect more recent changes and highlight areas of need. 2018-10-11 02:12:01 +00:00			`Thanks,`
Update README 2015-07-03 23:41:10 +00:00
Update README.md and ISSUE_TEMPLATE.md - Update ISSUE_TEMPLATE.md to help obtain better information for bug reports. - Update README.md to reflect more recent changes and highlight areas of need. 2018-10-11 02:12:01 +00:00			`Andrew Senetar`
Add Windows/Mac maintainer notice in the README 2015-12-25 01:50:33 +00:00
Clean up README 2016-06-06 21:00:57 +00:00			`## Contents of this folder`
Updated README 2013-12-01 16:26:30 +00:00
Add Current Status section to README 2015-04-12 19:31:01 +00:00			This folder contains the source for dupeGuru. Its documentation is in `help`, but is also
Updated README 2013-12-01 16:26:30 +00:00			`[available online][documentation] in its built form. Here's how this source tree is organised:`
Updated README to include clearer build instructions 2013-06-23 01:43:24 +00:00
			`* core: Contains the core logic code for dupeGuru. It's Python code.`
			`* qt: UI code for the Qt toolkit. It's written in Python and uses PyQt.`
			`* images: Images used by the different UI codebases.`
Improved arch packaging No need to bundle a .desktop file with arch source packages anymore. dupeGuru's source package takes care of that. 2014-04-19 21:48:48 +00:00			`* pkg: Skeleton files required to create different packages`
Updated README to include clearer build instructions 2013-06-23 01:43:24 +00:00			`* help: Help document, written for Sphinx.`
Tweaked README 2013-06-24 20:20:05 +00:00			`* locale: .po files for localisation.`
Updated README to include clearer build instructions 2013-06-23 01:43:24 +00:00
			`There are also other sub-folder that comes from external repositories and are part of this repo as`
Convert hscommon, qtlib and cocoalib to submodules ... rather than subtrees. That also represents a small qtlib updates which needed a code adjustment. 2016-05-26 01:07:30 +00:00			`git submodules:`
Updated README to include clearer build instructions 2013-06-23 01:43:24 +00:00
			`* hscommon: A collection of helpers used across HS applications.`
			`* qtlib: A collection of helpers used across Qt UI codebases of HS applications.`

Clean up README 2016-06-06 21:00:57 +00:00			`## How to build dupeGuru from source`
Updated README to include clearer build instructions 2013-06-23 01:43:24 +00:00
Initial Update of Windows Packaging (#438) * Update run.py & .gitignore for windows - Update run.py to execute on windows as SIGQUIT is not available. - Update .gitignore to ignore the generate .pyd files Ref #300, #393 * Update package.py for windows Add package_windows back into package.py - Using cx_freeze for freezing installation - Will be using nsis for actual installer Tested with python 3.5 64bit on windows 10 Ref #393 * Update makefile for windows (+2 misc) - Update the makefile to support windows - Use different bin path in virtualenv - Use pyd instead of so files - Tested with Msys2 - Add .exe to .gitignore - Fix minor format error in package.py Ref #393 Add requirements-windows Add the requirements-windows.txt - contains cx-Freeze for bundling Ref #393 * Add initial setup.nsi Initial Version of a NSIS installer script - Multi-user install (install for just one or all) - Registers uninstaller (more values need to finish up) - Tested both single and all install / uninstall and works - Still need to add parameters instead of hardcoded values in some spots - Need to clean up vendor folders / keys if empty on uninstall - Need to add the other dupeGuru languages to the language list - Minor cleanup of script needed as well Ref #393 * Update setup.nsi Updates to setup.nsi including: - Defines from CLI - Version information (MAJOR, MINOR, PATCH) - Bits (64 / 32) - SourcePath (if we wanted something other than build) - Added extra defines to move application specifics to one location - Added extra defines for uninstall information - Added calculation of install size - Added switching between 64 and 32 bit contexts (need to verify functionality) - Updated output file naming - Added NSIS supported languages which are also supported by dupeGuru - Added rest of registry keys for uninstall information - Added missing registry key for installType - Added removeing Vendor folder and registry key if empty on uninstall Should be very close to having this installer script ready to integrate into the package.py script if desired. Ref #393 * Update README & requirements-windows Minor update to README to indicate windows is supported. Add PyQt5 to requirements-windows.txt to make installation easier. * Update packaging for windows - Update package.py to integrate NSIS for windows - Update makefile to deal with a few additional windows issues - Add Windows.md to contain specific windows instructions, if we want this can be merged with README.md - Minor formatting update to setup.nsi Ref #393 * Update README & Windows Instructions - Update the README to include a reference to the Windows instructions. - Add some additional notes into Windows Instructions and remove one incorrect command. - Update .gitignore to ignore all permutations of env* to allow for multiple side by side virtual environments (used to build different versions for windows) Ref: #393 * Update Window.md Fix broken python link and move nsis link for consistency. * More Details in Windows.md Update Windows.md including: - Information on compilier requirements for windows - Notes about the windows 10 sdk - Some clarification around some of the steps - Addition of msys2 links Going to review this a bit more to polish it up. Ref #393. 2017-08-28 23:27:17 +00:00			`### Windows`
			`For windows instructions see the [Windows Instructions](Windows.md).`

Remove cocoa The cocoa UI code now lives in dupeguru-cocoa. 2017-03-12 01:41:47 +00:00			`### Prerequisites`

			`* [Python 3.4+][python]`
			`* PyQt5`

Add Makefile I finally took the time to properly learn how to write makefiles. This was long overdue, but here we go. Much of the makefile wraps `build.py`, but gradually, we'll extract stuff from there until the makefile is the main container for build logic. 2016-08-16 02:38:47 +00:00			`### make`

Remove cocoa The cocoa UI code now lives in dupeguru-cocoa. 2017-03-12 01:41:47 +00:00			`dupeGuru is built with "make":`
Add Makefile I finally took the time to properly learn how to write makefiles. This was long overdue, but here we go. Much of the makefile wraps `build.py`, but gradually, we'll extract stuff from there until the makefile is the main container for build logic. 2016-08-16 02:38:47 +00:00
			`$ make`
			`$ make run`

Update packaging to conform with package unification and few fixes (#372) * Rename package (dupeguru-se -> dupeguru) * Update package name in .desktop files and scripts * Add Ubuntu package building instructions * Fix build_pe_modules.py * Add description to package * Add conflicts dependencies to replace previous versions * Update python version * Unify .json configs * Few cosmetics changes (mainly missing end-lines and images permissions) 2016-06-29 02:39:23 +00:00			`### Generate Ubuntu packages`

			`$ bash -c "pyvenv --system-site-packages env && source env/bin/activate && pip install -r requirements.txt && python3 build.py --clean && python3 package.py"`

Clean up README 2016-06-06 21:00:57 +00:00			`### Running tests`
Add tox instructions in README Also, remove py33 from tox envlist 2016-01-05 22:14:05 +00:00
Fix verb tense in README.md (#406) 2017-01-09 03:34:49 +00:00			`The complete test suite is run with [Tox 1.7+][tox]. If you have it installed system-wide, you`
Add tox instructions in README Also, remove py33 from tox envlist 2016-01-05 22:14:05 +00:00			don't even need to set up a virtualenv. Just `cd` into the root project folder and run `tox`.

			If you don't have Tox system-wide, install it in your virtualenv with `pip install tox` and then
			run `tox`.

			`You can also run automated tests without Tox. Extra requirements for running tests are in`
			`requirements-extra.txt`. So, you can do `pip install -r requirements-extra.txt` inside your
			virtualenv and then `py.test core hscommon`

Update README.md and ISSUE_TEMPLATE.md - Update ISSUE_TEMPLATE.md to help obtain better information for bug reports. - Update README.md to reflect more recent changes and highlight areas of need. 2018-10-11 02:12:01 +00:00			`[dupeguru]: https://dupeguru.voltaicideas.net/`
Updated README 2013-12-01 16:26:30 +00:00			`[cross-toolkit]: http://www.hardcoded.net/articles/cross-toolkit-software`
Update README.md and ISSUE_TEMPLATE.md - Update ISSUE_TEMPLATE.md to help obtain better information for bug reports. - Update README.md to reflect more recent changes and highlight areas of need. 2018-10-11 02:12:01 +00:00			`[documentation]: http://dupeguru.voltaicideas.net/help/en/`
Tweaked README 2013-06-24 20:20:05 +00:00			`[python]: http://www.python.org/`
			`[pyqt]: http://www.riverbankcomputing.com`
Current status: unmaintained 2018-02-15 03:42:40 +00:00			`[tox]: https://tox.readthedocs.org/en/latest/`